# Hardcode Haml - Haml for Hardcore Coders (and Embedded devices)
Compiling Haml markup/templates to program code.
*Warning:* There are still some language features missing. The TODO section is
an imcomplete documentation of the the parts I am aware of.
## Concept
Most template engines for compiled and statically typed languages (like C and
C++) are only able to do simple search and replace jobs for given values. Having
used template engines in script languages like Ruby, Python or Java Script makes
returning to those template engines hard. This is where Hardcode Haml comes into
play.
Haml was first implemented in ruby and got ported to multiple other languages.
It compines the ability to replace parts of your markup with values calculated
at runtime (even allowing evaluation of code directly from the markup) and
additionally replaces XML with more writeable and readable markup.
This project turns Haml markup into program code. Therefore the markup gets
parsed and processed before runtime and maybe even optimized by your compiler.
Therefore execution time, memory footprint and file size on the target device
should be superior to other approaches. The drawback is, that your templates are
compiled in your binary and you can't edit them on the target system.
The language modules will generate a function which, when executed, will output
the generated XML markup into a stream. The parameters of the function can be
referenced directly from within the template. Haml contains syntax elements
which let you print out evaluated code and even pass code directly to the
generated code. Loops and other control flow elements can be used to repeat
blocks or conditionally display them.
To fullfill the needs of the target languages, Haml syntax has to be extended.
We need a way to specify the name and type of the parameters given to the
template. Additionally most languages need a way to execute code before the
function declaration (e.g. to include headers).
## State
Hardcode Haml is used in at least one production environment (in which I am
involved). The development is driven by this project as we find bugs and
important missing features. I am confident that Hardcode Haml in its current
state is stable and comprehensive enough to be useful in other projects.
If you are missing a useful feature or find a bug please file an issue on
[Github](https://github.com/thammi/Hardcode-Haml/issues). Also feel free to
contact me there if you have any questions.
## Supported Languages
Output can currently be generated in several languages
* C++ _(using ostream)_
* C _(using fputs())_
* python _(using Pythons file objects)_
Other languages can be implemented with ease. All language implementations are
currently smaller than 100 lines (including whitespaces).
Haml passes code directly to the underlying language, so the language modules
won't be interchangable without replacing some code in your templates.
## Hardcode Haml Dialect
Some syntax changes were neccessary to adopt Haml to the target languages.
### Declaration
As languages like C and C++ do not have tightly built-in dictionary types using
those does not come natural in these languages. I therefore decided to use a
more native approach to pass the data into the template: Function parameters. To
declare those the Haml syntax has to be extended:
? int a, std::string b
The `?` declares the parameters passed to the templates and starts the actual
template. An implicit `?` at the start of the document is assumed if there is
none explicit declaration.
Introducing this operator has another advantage: It is possible to introduce
code which will be placed outside the actual function processing the template.
Simply write this code before the `?` declaration. The way this code behaves
depends on the language you are using. In C/C++ this code will be added to the
header which enables you to include files and declare types used in your
template.
### Boolean attributes
Boolean attributes are implicit in ruby and detected at runtime. Hardcode Haml
tries to do as much as possible in the parser and avoids complexity in the
language modules. Another problem is that not all target languages are able to
determine whether an expression evaluates to a boolean. Hardcode Haml therefore
extends the syntax with the '?=' and '?=>' operators for attributes.
Boolean attributes are useful for radiobuttons, checkboxes and select elements.
Simply write:
%input(type="radio" checked?=foo)
... or ...
%input(type="radio"){"checked" ?=> foo}
This code evaluates to the following (X)HTML when `foo` is true:
<input type="radio" checked="checked">
... and when `foo` is false to:
<input type="radio">
## Example
There is an example in the [Wiki](https://github.com/thammi/Hardcode-Haml/wiki/Example-Workflow-%28C++%29).
## Todos
### Tasks
* correct scoping according to indent
* implement most common syntax/language elements (see below)
* ...
* document implemented functionality and introduced syntax extensions of Haml
* clean up the code (especially in the parser)
* target language site helper
* ...
### Syntax/Language Elements
#### Must have
* entity escape (static, dynamic?)
* filters (infrastructure, some filters)
### May have
* whitespace removal (< and >)
* conditional comments /\[] (only needed to support IE afaik)
* whitespace preservation
* escaping/unescaping html in evaluations
### Won't implement (in the near future)
* object reference \[] (too close to the target language)
## Links
* [Official Haml Homepage](http://haml-lang.com/)
* [Haml "Reference"](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html)
Raw data
{
"_id": null,
"home_page": "http://www.chaossource.net/hardcode_haml/",
"name": "hardcode-haml",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "haml template html web",
"author": "Thammi",
"author_email": "thammi@chaossource.net",
"download_url": null,
"platform": null,
"description": "# Hardcode Haml - Haml for Hardcore Coders (and Embedded devices)\n\nCompiling Haml markup/templates to program code.\n\n*Warning:* There are still some language features missing. The TODO section is\nan imcomplete documentation of the the parts I am aware of.\n\n## Concept\n\nMost template engines for compiled and statically typed languages (like C and\nC++) are only able to do simple search and replace jobs for given values. Having\nused template engines in script languages like Ruby, Python or Java Script makes\nreturning to those template engines hard. This is where Hardcode Haml comes into\nplay.\n\nHaml was first implemented in ruby and got ported to multiple other languages.\nIt compines the ability to replace parts of your markup with values calculated\nat runtime (even allowing evaluation of code directly from the markup) and\nadditionally replaces XML with more writeable and readable markup.\n\nThis project turns Haml markup into program code. Therefore the markup gets\nparsed and processed before runtime and maybe even optimized by your compiler.\nTherefore execution time, memory footprint and file size on the target device\nshould be superior to other approaches. The drawback is, that your templates are\ncompiled in your binary and you can't edit them on the target system.\n\nThe language modules will generate a function which, when executed, will output\nthe generated XML markup into a stream. The parameters of the function can be\nreferenced directly from within the template. Haml contains syntax elements\nwhich let you print out evaluated code and even pass code directly to the\ngenerated code. Loops and other control flow elements can be used to repeat\nblocks or conditionally display them.\n\nTo fullfill the needs of the target languages, Haml syntax has to be extended.\nWe need a way to specify the name and type of the parameters given to the\ntemplate. Additionally most languages need a way to execute code before the\nfunction declaration (e.g. to include headers).\n\n## State\n\nHardcode Haml is used in at least one production environment (in which I am\ninvolved). The development is driven by this project as we find bugs and\nimportant missing features. I am confident that Hardcode Haml in its current\nstate is stable and comprehensive enough to be useful in other projects.\n\nIf you are missing a useful feature or find a bug please file an issue on\n[Github](https://github.com/thammi/Hardcode-Haml/issues). Also feel free to\ncontact me there if you have any questions.\n\n## Supported Languages\n\nOutput can currently be generated in several languages\n\n* C++ _(using ostream)_\n* C _(using fputs())_\n* python _(using Pythons file objects)_\n\nOther languages can be implemented with ease. All language implementations are\ncurrently smaller than 100 lines (including whitespaces).\n\nHaml passes code directly to the underlying language, so the language modules\nwon't be interchangable without replacing some code in your templates.\n\n## Hardcode Haml Dialect\n\nSome syntax changes were neccessary to adopt Haml to the target languages.\n\n### Declaration\n\nAs languages like C and C++ do not have tightly built-in dictionary types using\nthose does not come natural in these languages. I therefore decided to use a\nmore native approach to pass the data into the template: Function parameters. To\ndeclare those the Haml syntax has to be extended:\n\n ? int a, std::string b\n\nThe `?` declares the parameters passed to the templates and starts the actual\ntemplate. An implicit `?` at the start of the document is assumed if there is\nnone explicit declaration.\n\nIntroducing this operator has another advantage: It is possible to introduce\ncode which will be placed outside the actual function processing the template.\nSimply write this code before the `?` declaration. The way this code behaves\ndepends on the language you are using. In C/C++ this code will be added to the\nheader which enables you to include files and declare types used in your\ntemplate.\n\n### Boolean attributes\n\nBoolean attributes are implicit in ruby and detected at runtime. Hardcode Haml\ntries to do as much as possible in the parser and avoids complexity in the\nlanguage modules. Another problem is that not all target languages are able to\ndetermine whether an expression evaluates to a boolean. Hardcode Haml therefore\nextends the syntax with the '?=' and '?=>' operators for attributes.\n\nBoolean attributes are useful for radiobuttons, checkboxes and select elements.\nSimply write:\n\n %input(type=\"radio\" checked?=foo)\n\n... or ...\n\n %input(type=\"radio\"){\"checked\" ?=> foo}\n\nThis code evaluates to the following (X)HTML when `foo` is true:\n\n <input type=\"radio\" checked=\"checked\">\n\n... and when `foo` is false to:\n\n <input type=\"radio\">\n\n## Example\n\nThere is an example in the [Wiki](https://github.com/thammi/Hardcode-Haml/wiki/Example-Workflow-%28C++%29).\n\n## Todos\n\n### Tasks\n\n* correct scoping according to indent\n* implement most common syntax/language elements (see below)\n* ...\n* document implemented functionality and introduced syntax extensions of Haml\n* clean up the code (especially in the parser)\n* target language site helper\n* ...\n\n### Syntax/Language Elements\n\n#### Must have\n\n* entity escape (static, dynamic?)\n* filters (infrastructure, some filters)\n\n### May have\n\n* whitespace removal (< and >)\n* conditional comments /\\[] (only needed to support IE afaik)\n* whitespace preservation\n* escaping/unescaping html in evaluations\n\n### Won't implement (in the near future)\n\n* object reference \\[] (too close to the target language)\n\n## Links\n\n* [Official Haml Homepage](http://haml-lang.com/)\n* [Haml \"Reference\"](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html)\n\n",
"bugtrack_url": null,
"license": "AGPLv3",
"summary": "Haml for hardcore coders (and C++/C/... projects)",
"version": "0.3.0",
"project_urls": {
"Homepage": "http://www.chaossource.net/hardcode_haml/"
},
"split_keywords": [
"haml",
"template",
"html",
"web"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "25c8e4f7833a0f9cc513801c82d925bd3a3b7c028c0cdff46e0f6d414f793b98",
"md5": "6238d0e456da6782437711073832029b",
"sha256": "20968687a3b8219d8f44eca2081880f1baa4190ff9f459c4900c800853f1de32"
},
"downloads": -1,
"filename": "hardcode_haml-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6238d0e456da6782437711073832029b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 28293,
"upload_time": "2024-10-30T12:53:32",
"upload_time_iso_8601": "2024-10-30T12:53:32.660236Z",
"url": "https://files.pythonhosted.org/packages/25/c8/e4f7833a0f9cc513801c82d925bd3a3b7c028c0cdff46e0f6d414f793b98/hardcode_haml-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-30 12:53:32",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "hardcode-haml"
}
JSON