Options

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}