Understanding of function variable

[philippe-levan]

Hi,

When I look at the code, it seems that we can add a "function variable" into a template like $my_var(foo.bar)

Then in my json, I can add the variable "variables":{"my_var(foo.bar)":{"type":"text","value":"my_value"}}

and then all the string $my_var(foo.bar) is replaced by my_value.

Is there another feature associated to these "function variables" or it is just the way to have variables with a more flexible variable name (which is useful for me) ?

[Kyrela]

TL;DR Function variables are text variables. They are useful if you want to allow usage of programming-like syntax in order to add multiple variables interpretations possibilities. But, Lotemplate doesn't interpret them in a different way.

Note that this answer only speaks about text variables, but the same exact text can be used to speak about table variables (as they also support this syntax)

---

What are Function Variables?

Function variables are just regular text variables, and operate in the same way as text variables - in terms of code and usage. The only thing that really differentiates them from regular text variables is their syntax.

• $my_var - regular variable
• $my_func($my_var) - function variables

As they are text variables, lotemplate will return them just like regular variables:

{
     "my_func($my_var)": {
         "type": "text",
         "value": ""
     }
}

The pattern to match them is very specific and follows a specific syntax:

\$\w+(?:\((?<arg>(?R)|"[^"]*"|[^$"\s()][^\s()]*)(?:[+ ](?&arg))*\))?

Examples include:

• $my_func($my_var)
• $truncate($my_var 10)
• $concat($my_var "text to append")
• $concat($my_var one_word_to_concat)
• $surround_with($my_func($my_var) "------- "+$surround_text)

Why use Function Variables?

Here's an example:

Suppose you are developing software to fill documents containing variables such as $current_address, $name, etc. There may be a use case when you want to restrict the length of the text used to replace the variables to not exceed x characters, where x is relative to the document - it's not a constant. So, you want to give users the ability to specify the maximum length.

You can simply instruct users to write $max_length($current_address 240) and then parse the variable names using regex (or another parsing method) to find the pattern max_length\(\$(\w+)\s+(\d+)\). You can then truncate the variable contained in the match group 1 in order to not exceed the maximum set by the match group 2.

How to Use Function Variables?

As previously mentioned, function variables are just text variables, so lotemplate does not treat them any differently. You have to parse the variable names returned by lotemplate yourself and correctly set the variable value relative to the variable name - all on your own. As previously mentioned, lotemplate does NOT provide any logic related to function variables - only the search for this type of pattern.

Why not treat function variables as a type in their own right / Why not treat function variables as entiere variables / Why not return them parsed?

Of course, the ideal scenario would be for lotemplate to return variables like this:

{
     "my_func": {
         "type": "function",
         "value": ""
     },
     "my_var": {
         "type": "text",
         "value": ""
     }
}

For a text like this: $my_func($my_var).

However, this would require code to be sent and executed by Lotemplate. Because you cannot give the return value, you have to describe what your function is actually doing.

This poses 3 issues:

1. Application context loss
   The fact that lotemplate would be executing your code also means that it would not be possible to access specific information if you're developing your own product, such as access to the database or execution context.
2. Security problems
   The fact that your code will be evaluated is a security issue. It is like keeping a door open to allow malicious code to be injected.
3. Language limitations.
   Lotemplate is written in Python, which means that the code to be executed would also need to be written in Python, as it would be Lotemplate that executes your code. This would limit the scope of what could be executed to code that can be evaluated by Python's built-in eval() function. Function definitions and imports would not be allowed, and only simple Python expressions that describe a value could be used.

Instead, by treating function variables as regular text variables, lotemplate provides a flexible way to allow for custom variable interpretation while still maintaining security and simplicity. It's up to the user to parse and interpret the variables returned by lotemplate in a way that fits their needs.

---

In summary, function variables are a powerful tool for allowing custom interpretation of variables in lotemplate, but they should be treated as regular text variables and parsed by the user to avoid security and complexity issues.

[philippe-levan]

Thanks for your very complete answer !

[Kyrela]

No problem, have a great day!