Skip to content

Options

Constantin Mihai edited this page Jun 16, 2022 · 31 revisions

Changing Options

The behavior of the compiler and renderer can be changed through various options.

Simply use the setOptions function.

eryn.setOptions({
    optionName: "value",
    someBool: true,
    ....
});

since 0.3.0 You can also pass options to eryn when importing it:

const eryn = require('eryn')({
    optionName: "value",
    someBool: true,
    ....
});

It only accepts one parameter: an Object containing properties in the form optionName: newValue.

Exceptions

If an option name or value is invalid (e.g. option name doesn't exist, value is String instead of bool), it is ignored. No exceptions are thrown.

List of options

Below is a list of all available options.

Name Type Default Description
bypassCache bool false If true, the render function will always (re)compile files, even if they are present in the cache. This is useful while developing, as you can edit files on the fly. If the file is present in the cache, the old compiled data is deleted
throwOnEmptyContent bool false If true, the render function will throw an exception if you attempt to use content when it is undefined (e.g. in a self-closed component)
throwOnMissingEntry bool false If true, the render function will throw an exception if a file is not present in the cache when rendering that file. This is useful if you want to manually compile all files and prevent path-related errors (i.e. not the same path as in the cache, which results in recompilation). In other words, the render function will no longer automatically compile files that are not present in the cache
throwOnCompileDirError bool false If true, the compileDir function will throw an exception, instead of showing an error, when a file in the directory fails to compile
ignoreBlankPlaintext bool false If true, the compiler will ignore plaintext that only contains whitespace characters (i.e. \r, \n, \t and space). This is useful if you write consecutive templates on new lines for clarity, but you want them to be rendered directly one after the other with no spaces or lines between. You can use this for rendering binary files
logRenderTime bool false If true, the render time (in microseconds) will be logged every time the render function is executed
enableDeepCloning bool false Whether or not to use deep cloning when making a copy of an object (see #23). Enabling this might lead to significant drops in performance, so only use this if it's necessary.
cloneIterators bool false Whether or not to assign clones to iterators, such that modifying the iterator won't have any effect on the original element. Note: in order for this option to fully take effect, you also need to set enableDeepCloning to true. This may lead to significant drops in performance.
cloneBackups bool false Whether or not to assign clones to the local and shared objects when backing them up before rendering a component. Note: in order for this option to fully take effect, you also need to set enableDeepCloning to true. This may lead to significant drops in performance.
cloneLocalInLoops bool false Whether or not to assign a clone to the local object inside loop templates, such that any modifications done to it inside the loop will not persist outside the loop. Note: in order for this option to fully take effect, you also need to set enableDeepCloning to true. This may lead to significant drops in performance.
debugDumpOSH bool false Whether or not to dump the OSH intermediary format of the compiled templates. This is used for debugging purposes, and shouldn't normally be enabled.
workingDirectory string . The working directory used for compiling and rendering via relative paths
templateEscape char \ The character which escapes a templateEnd marker
templateStart string [| The string which marks the start of a template
templateEnd string |] The string which marks the end of a template
bodyEnd string end The string which marks the template as a body end
commentStart string // The string which marks the template as a comment template
commentEnd string //|] The string which marks the end of a comment template
voidTemplate string # The string which marks the template as a void template
conditionalStart string ? The string which marks the template as a conditional template start (like if)
elseStart string : The string which marks the template as an else template start (like else)
elseConditionalStart string :? The string which marks the template as an else conditional template start (like else if)
loopStart string @ The string which marks the template as a loop template start (like for)
loopSeparator string : The string which separates the iterator from the array (like of in for ... of ...)
loopReverse string ~ The string which marks the loop as a reverse loop (i.e. will iterate in reverse order)
componentStart string % The string which marks the template as a component template start
componentSeparator string : The string which separates the component name from the context
componentSelf string / The string at the end of the template which marks the component as self-closing
mode string normal The mode under which the system operates. Must be either normal or strict. See the Modes page for more info

Example

By using the setOptions function, you can change the syntax however you like.

Here's an example which was previously shown.

eryn.setOptions({
    templateStart: "{{",
    templateEnd: "}}",

    conditionalStart: "if",

    loopStart: "for",
    loopSeparator: "of",
    
    componentStart: "component",
    componentSeparator: "with",
    componentSelf: "self"
});

After setting those options, the syntax looks like this:

{{block_of_code}}

{{if expression}}
body
{{end}}

{{for iterator of array}}
body
{{end}}


{{component comp_path}}
content
{{end}}

{{component comp_path self}}

{{component comp_path with context}}
content
{{end}}

{{component comp_path with context self}}

This is just an example. You can change the syntax however you want.

Remarks

When changing the syntax, you need to be careful, especially with the templateEnd option.

Consider templateEnd = "}}". Here's an example of what could go wrong:

{{component comp.eryn with { test: { hello: "world"}} }}

Due to performance reasons, the compiler looks for the first occurrence of }}, starting after the component template start marker. The first occurrence is here:

{{component comp.eryn with { test: { hello: "world"}} }}
                                                   ^^

So, the compiler marks that as the template end, which may lead to problems.

The solution is to use the templateEscape marker:

{{component comp.eryn with { test: { hello: "world"\}} }}

Now, that occurrence will be marked as escaped, so the next occurrence will be chosen:

{{component comp.eryn with { test: { hello: "world"\}} }}
                                                    ^^ (escaped)
{{component comp.eryn with { test: { hello: "world"\}} }}
                                                       ^^

Here's another example:

{{component comp.eryn with { test: { hello: "world"}}}}
                                                   ^^

The escape will be done as follows:

{{component comp.eryn with { test: { hello: "world"}\}}}
                                                     ^^ (escaped)
{{component comp.eryn with { test: { hello: "world"}\}}}
                                                      ^^

Tip: the escape character advances the index by 1.

Therefore, placing the escape character like this:

{{component comp.eryn with { test: { hello: "world"\}}}}
                                                    ^^ (escaped)
{{component comp.eryn with { test: { hello: "world"\}}}}
                                                     ^^

...will still lead to problems.

The escape character can be used in all template types in order to escape templateEnd:

  • Normal / Comment / Void templates

  • Conditional / Inverted Conditional templates

  • Loop templates (the array part)

  • Component templates

Syntax Tips

In general, you need to be careful about these things:

  • templateEnd: should not appear anywhere in the template (can be solved with templateEscape)

  • loopSeparator: should not appear anywhere in the iterator

  • componentSeparator: should not appear anywhere in the component path

  • commentEnd: should not be equal to templateEnd since 0.2.0

Intro

    Home

    Getting Started

Engine Basics

    Context

    Templates

    Local

    Shared

    Modes

Functions

    Compile

    Render

    Options

Other

    Security Concerns

    Known Issues

Clone this wiki locally