<commit_before>ErlyDTL [![Build Status](https://travis-ci.org/erlydtl/erlydtl.png?branch=master)](https://travis-ci.org/erlydtl/erlydtl)
=======

ErlyDTL compiles Django Template Language to Erlang bytecode.

Project homepage: <https://github.com/erlydtl/erlydtl/wiki>

ErlyDTL implements the Django Template Language as documented for
version *1.6*, here:
<http://docs.djangoproject.com/en/1.6/ref/templates/builtins/>

Despite our best efforts to be completely compatible with the Django
Template Languge, there are still a few
[differences](https://github.com/erlydtl/erlydtl#differences-from-standard-django-template-language).


Compilation
-----------

To compile ErlyDTL, run

    make

in this directory.


Template compilation
--------------------

Usage:

```erlang
erlydtl:compile_file("/path/to/template.dtl", my_module_name)

erlydtl:compile_file("/path/to/template.dtl", my_module_name, Options)

erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name)

erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name, Options)
```

Result:

```erlang
{ok, Module}
{ok, Module, Warnings}
{ok, Module, Binary}
{ok, Module, Binary, Warnings}

error
{error, Errors, Warnings}
```

Options is a proplist possibly containing:

* `auto_escape` - Control automatic HTML escaping of template
  values. Enabled by default.

* `binary` - Include the compiled template binary code in the result
  tuple (between the module name and any warning/error lists). Note,
  this option is named the same as for the Erlang compiler, with
  similar use, except that this option does NOT affect whether or not
  a .beam file is saved.

* `binary_strings` - Whether to compile strings as binary terms
  (rather than lists). Defaults to `true`.

* `blocktrans_fun` - A two-argument fun to use for translating
  `blocktrans` blocks, `trans` tags and `_(..)` expressions. This will
  be called once for each pair of translated element and locale
  specified in `blocktrans_locales`. The fun should take the form:

  ```erlang
  Fun(Block::string(), Locale::string()) -> <<"ErlyDTL code">>::binary() | default
  ```

* `blocktrans_locales` - A list of locales to be passed to
  `blocktrans_fun`.  Defaults to [].

* `compiler_options` - Proplist with extra options passed directly to
  `compiler:forms/2`. This can prove useful when using extensions to
  add extra defines etc when compiling the generated code.

* `custom_filters_modules` **deprecated** - A list of modules to be
  used for handling custom filters. The modules will be searched in
  order and take precedence over the built-in filters. Each custom
  filter should correspond to an exported filter, e.g.

  ```erlang
  some_filter(Value) -> iolist()
  ```

  If the filter takes any arguments (e.g. "foo:2"), those will be
  added to the call:

  ```erlang
  some_filter(Value, Arg) -> iolist()
  ```

* `custom_tags_dir` - Directory of DTL files (no extension) includable
  as tags.  E.g. if `$custom_tags_dir/foo` contains `<b>{{ bar
  }}</b>`, then `{% foo bar=100 %}` will evaluate to `<b>100</b>`.

* `custom_tags_modules` **deprecated** - A list of modules to be used
  for handling custom tags. The modules will be searched in order and
  take precedence over `custom_tags_dir`. Each custom tag should
  correspond to an exported function with one of the following
  signatures:

  ```erlang
  some_tag(TagVars)          -> iolist()
  some_tag(TagVars, Options) -> iolist()
  ```

  The `TagVars` are variables provided to a custom tag in the
  template's body (e.g. `{% foo bar=100 %}` results in `TagVars =
  [{bar, 100}]`).  The `Options` are options passed as the second
  argument to the `render/2` call at render-time. (These may include
  any options, not just `locale` and `translation_fun`.)

* `debug_compiler` - Enable compiler debug diagnostics.  Currently it
  debug prints the options passed to `compile:forms` (i.e. if
  verbosity is >= 2; that is, with two or more `verbose` options) and
  enables the saving of the compiled template in source form to a .erl
  file.

* `debug_info` - This option is passed to `compile:forms` to include
  debug information in the compiled module.

* `debug_root` - The root directory for debug source dumps. If set to
  `false`, no source dump will be saved. Defaults to `undefined`,
  leaving the source dump next to the source template file.

* `default_libraries` - A list of libraries that should be loaded by
  default when compiling a template. Libraries can be specified either
  by name (when there is a name to module mapping also provided in the
  `libraries` option) or by module.

* `doc_root` - Included template paths will be relative to this
  directory; defaults to the compiled template's directory.

* `extension_module` **experimental** - This is work in progress to
  make erlydtl extensible.

* `force_recompile` - Recompile the module even if the source's
  checksum has not changed. Useful for debugging.

* `libraries` - A list of `{Name, Module}` libraries implementing
  custom tags and filters. `Module` should implement the
  `erlydtl_library` behaviour.

* `locale` **deprecated** - The same as {blocktrans_locales, [Val]}.

* `no_env` - Do not read additional options from the OS environment
  variable `ERLYDTL_COMPILER_OPTIONS`.

* `no_load` - Do not load the compiled template.

* `out_dir` - Directory to store generated .beam files. If not
  specified, no .beam files will be created and a warning is
  emitted. To silence the warning, use `{out_dir, false}`.<commit_msg>Clarify applicability of the new debug_root option.<commit_after>ErlyDTL [![Build Status](https://travis-ci.org/erlydtl/erlydtl.png?branch=master)](https://travis-ci.org/erlydtl/erlydtl)
=======

ErlyDTL compiles Django Template Language to Erlang bytecode.

Project homepage: <https://github.com/erlydtl/erlydtl/wiki>

ErlyDTL implements the Django Template Language as documented for
version *1.6*, here:
<http://docs.djangoproject.com/en/1.6/ref/templates/builtins/>

Despite our best efforts to be completely compatible with the Django
Template Languge, there are still a few
[differences](https://github.com/erlydtl/erlydtl#differences-from-standard-django-template-language).


Compilation
-----------

To compile ErlyDTL, run

    make

in this directory.


Template compilation
--------------------

Usage:

```erlang
erlydtl:compile_file("/path/to/template.dtl", my_module_name)

erlydtl:compile_file("/path/to/template.dtl", my_module_name, Options)

erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name)

erlydtl:compile_template("<html>{{ foo }}</html>", my_module_name, Options)
```

Result:

```erlang
{ok, Module}
{ok, Module, Warnings}
{ok, Module, Binary}
{ok, Module, Binary, Warnings}

error
{error, Errors, Warnings}
```

Options is a proplist possibly containing:

* `auto_escape` - Control automatic HTML escaping of template
  values. Enabled by default.

* `binary` - Include the compiled template binary code in the result
  tuple (between the module name and any warning/error lists). Note,
  this option is named the same as for the Erlang compiler, with
  similar use, except that this option does NOT affect whether or not
  a .beam file is saved.

* `binary_strings` - Whether to compile strings as binary terms
  (rather than lists). Defaults to `true`.

* `blocktrans_fun` - A two-argument fun to use for translating
  `blocktrans` blocks, `trans` tags and `_(..)` expressions. This will
  be called once for each pair of translated element and locale
  specified in `blocktrans_locales`. The fun should take the form:

  ```erlang
  Fun(Block::string(), Locale::string()) -> <<"ErlyDTL code">>::binary() | default
  ```

* `blocktrans_locales` - A list of locales to be passed to
  `blocktrans_fun`.  Defaults to [].

* `compiler_options` - Proplist with extra options passed directly to
  `compiler:forms/2`. This can prove useful when using extensions to
  add extra defines etc when compiling the generated code.

* `custom_filters_modules` **deprecated** - A list of modules to be
  used for handling custom filters. The modules will be searched in
  order and take precedence over the built-in filters. Each custom
  filter should correspond to an exported filter, e.g.

  ```erlang
  some_filter(Value) -> iolist()
  ```

  If the filter takes any arguments (e.g. "foo:2"), those will be
  added to the call:

  ```erlang
  some_filter(Value, Arg) -> iolist()
  ```

* `custom_tags_dir` - Directory of DTL files (no extension) includable
  as tags.  E.g. if `$custom_tags_dir/foo` contains `<b>{{ bar
  }}</b>`, then `{% foo bar=100 %}` will evaluate to `<b>100</b>`.

* `custom_tags_modules` **deprecated** - A list of modules to be used
  for handling custom tags. The modules will be searched in order and
  take precedence over `custom_tags_dir`. Each custom tag should
  correspond to an exported function with one of the following
  signatures:

  ```erlang
  some_tag(TagVars)          -> iolist()
  some_tag(TagVars, Options) -> iolist()
  ```

  The `TagVars` are variables provided to a custom tag in the
  template's body (e.g. `{% foo bar=100 %}` results in `TagVars =
  [{bar, 100}]`).  The `Options` are options passed as the second
  argument to the `render/2` call at render-time. (These may include
  any options, not just `locale` and `translation_fun`.)

* `debug_compiler` - Enable compiler debug diagnostics.  Currently it
  debug prints the options passed to `compile:forms` (i.e. if
  verbosity is >= 2; that is, with two or more `verbose` options) and
  enables the saving of the compiled template in source form to a .erl
  file.

* `debug_info` - This option is passed to `compile:forms` to include
  debug information in the compiled module.

* `debug_root` - Only applies when `debug_compiler` is `true`. The
  root directory for debug source dumps. If set to `false`, no source
  dump will be saved. Defaults to `undefined`, leaving the source dump
  next to the source template file.

* `default_libraries` - A list of libraries that should be loaded by
  default when compiling a template. Libraries can be specified either
  by name (when there is a name to module mapping also provided in the
  `libraries` option) or by module.

* `doc_root` - Included template paths will be relative to this
  directory; defaults to the compiled template's directory.

* `extension_module` **experimental** - This is work in progress to
  make erlydtl extensible.

* `force_recompile` - Recompile the module even if the source's
  checksum has not changed. Useful for debugging.

* `libraries` - A list of `{Name, Module}` libraries implementing
  custom tags and filters. `Module` should implement the
  `erlydtl_library` behaviour.

* `locale` **deprecated** - The same as {blocktrans_locales, [Val]}.

* `no_env` - Do not read additional options from the OS environment
  variable `ERLYDTL_COMPILER_OPTIONS`.

* `no_load` - Do not load the compiled template.

* `out_dir` - Directory to store generated .beam files. If not
  specified, no .beam files will be created and a warning is
  emitted. To silence the warning, use `{out_dir, false}`.
{'fraction_non_alphanumeric': 0.10694419522698725, 'fraction_numerical': 0.0035887313834559484, 'mean_word_length': 4.0737369139736, 'pattern_counts': {'":': 0, '<': 27, '<?xml version=': 0, '>': 39, 'https://': 8, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4774392', 'n_tokens_mistral': 3436, 'n_tokens_neox': 3319, 'n_words': 1345}