Version: 7.0

b4A Expressions

The provide a replacement algorithm with which simple value replacements can be carried out or extended functions can be used for replacement.

Simple replacements

These can be used to replace previously defined variables in character strings. In addition, the values of the variables can be changed before replacement with lists of regular expressions. Which variables are defined depends on the module that supports b4A Expressions. The variable lists can therefore be found in the module documentation.

To replace a variable, certain markers must be defined in the string, as in the following example.

This is the object %(object_name) of type %(object_type)

If the variables object_name and object_type are defined, the values of the variables are inserted in the text. To change the values before the replacement, replacement rules can be specified in the markers.

The object title is set to %(object_name/_/ /§§/./ /§§/[A-Z]+/CAPITALIZE/)

The replacement rules are defined as a semicolon-separated list in the marker. Each rule consists of two parts. A regular expression that defines the part to be replaced and the character string with which the part is to be replaced. The format is defined as follows:

/\<regular expression>/\<replacement text>/

There are three special values for the <replacement text> that are not used directly as replacements, but are functions that are applied to the value of the variable.

UPPERCASE: replaces the part with upper case letters.
LOWERCASE: replaces the part with lower case letters.
CAPITALIZE: replaces the part with a word with the first letter in upper case and the rest in lower case.

If the replacement text or regular expression is to contain slashes, these must be preceded by a backslash (\).

%(package_dependencies/ *§§ */<\/br>/)
%(folder/.*\///)

Functions

Functions are another variant of . These can perform various tasks on the text to be replaced. Functions are defined as follows:

%{<function name>[,\<option>[,\<option>...]]:<parameter>:\<replacement text>}

The options of a function are specified as a comma-separated list. An option is specified in the following format:

<name>=<value>

To set Boolean options to the value true, it is sufficient to specify only the name.

<name>

IF

The IF function can be used to define a conditional text output. The value of an attribute is compared. The replacement text is only transferred to the documentation if the condition is met.

%{IF[,\<option>[,\<option>...]]:<comparison>:\<replacement text>}

Options:

ignore_case[=(true|false)]: If the option is set, comparisons are not case-sensitive.

The following operators are available for the comparison:

==: Checks whether the value of an attribute is equal to a given value
!=: Checks whether the value of an attribute is not equal to a given value
~=: Checks whether the value of an attribute contains a given value
>: Checks whether the value of an attribute is greater than a given value (numbers)
<: Checks whether the value of an attribute is greater than a given value (numbers)
!: Checks whether the value of an attribute is empty (list or character string)
?: Checks whether the value of an attribute is not empty (list or character string)

Some of the operators can only be applied to certain types of attributes. This is indicated accordingly in the list above. These conditions can be linked with the Boolean operators & (and) and | (or). The conditions are evaluated from left to right up to the last condition.

If the attribute is empty, the text is displayed.

%{IF:!sync_list:
    The sync list is empty
}

If the attribute is not empty, the text is displayed.

%{IF:?sync_list:
||Sync object||Start action||End action||End action|{{Else}}|
%{LOOP_LIST:sync_list:|%(sync_object)|%(start)|%(evening)|%(end)|%(else)|}
}

If the attribute corresponds to the value true.

%{IF:runtime==true:
Runtime values are set
}

If the attribute runtime has the value true and the list sync_list is not empty, the text is output.

%{IF:runtime==true&?sync_list:
Runtime values are set and sync list is not empty
}

LOOP_LIST

The LOOP_LIST function can be used to iterate over lists of attributes. The replacement text is inserted for each element in the list.

%{LOOP_LIST[,\<option>[,\<option>...]]:\<attribute>:\<replacement text>}

Options:

separator=<separator>: If this option is set, no line breaks are inserted after the individual entries, but the specified characters are.

The specified <attribute> must contain a list. Each element of the list is again a collection of attributes that are replaced in the <replacement text>.

COUNT_LIST

The COUNT_LIST function can be used to count the elements of a list. The result is available as an attribute and can be used in the replacement text.

%{COUNT_LIST:\<attribute>:\<replacement text>}

In the following example, the number of objects in the package is output.

%{COUNT_LIST:objects:<p>Number of objects: %(count)</p>}

JOIN

The JOIN function allows you to combine a field for each element of a list in a character string. The separator between the elements can be configured.

%{JOIN:<list>,<field>:<separator>}

The following expression can be used to output the names of the sync objects of a job.

%{JOIN:sync_list,sync_object:, }

The list of sync objects is output with a comma (,) as separator

LOOP_XY

The LOOP_XY function is specially designed for displaying attributes of RA objects. Here, lists are not made available as a data structure, but through individual attributes that contain a structure coding in their names.

query_0_0 = query1
query_0_1 = param1
query_1_0 = query1
query_1_1 = param1

The numbers in the attribute names indicate the row as well as the column within the list structure. Thus, all attributes of this list that begin with query_0_ form the elements of the first list element. The LOOP_XY function can be used to display such attributes in a list similar to LOOP_LIST.

%{LOOP_XY:\<attribute pattern>:\<replacement text>}

In the <attribute pattern>, the identifiers $x (column) and $y (row) indicate how the attributes of the list are structured. In the replacement text, the elements of such a list can be accessed using virtual attributes that are named after the number of the column (e.g. %(1), %(2)).

%{LOOP_XY:query_$y_$x:<tr><td><i>%(1)</i></td><td>%(2)</td></tr>}

LOOP_Y

The LOOP_Y function is similar to the LOOP_XY function. This is about attributes that encode the row of the list elements in the name, but the column is defined by a descriptive name.

response_part_0_script_0_code_0 = store.bla
response_part_0_script_0_queryType = JSONPath
response_part_0_script_0_resourceName = &jsonvar#
response_part_0_script_0_saveTo = variable
response_part_0_script_0_useArray = true
response_part_0_script_1_code_0 = if ( store.fasel.equals( "hello world" ) )

The use of the LOOP_Y function is the same as the LOOP_XY function. Only the row ($y) needs to be specified in the attribute pattern, as the column is defined by the end of the attribute name.

%{LOOP_Y:\<attribute pattern>:\<replacement text>}

Attributes that correspond to the endings of the original attributes can be used in the replacement text. Everything after the specified attribute pattern corresponds to the name of the virtual attributes.

%{LOOP_Y:response_part_0_script_$y_:<tr><td>%(queryType)</td><td>%(saveTo)</td><td>%(resourceName)</td><td><div class="code">%(code_0)</div></td><td>%(useArray)</td></tr>}

LOOP_LINES

The LOOP_LINES function can be used to iterate over the individual lines of a multi-line attribute.

%{LOOP_LINES[,\<option>[,\<option>...]]:\<attribute>[,\<regular expression>]:\<replacement text>}

Options:

ignore_case[=(true|false)]: If the option is set, filtering with the regular expression is not case-sensitive.

The regular expression can be used to filter the lines that are taken into account in the loop. The attribute line can be used to insert the content of a line in the replacement text. The attribute number, which contains the line number, is also available.

%{LOOP_LINES,ignore_case:process,"^\:.*activate_uc_object.*":<tr><td>%(number)</td><td><p class="code">%(line)</p></td></tr>}

COUNT_LINES

The COUNT_LINES function can be used to count the lines in a multi-line string. As with LOOP_LINES, the lines can be filtered based on a regular expression.

%{COUNT_LINES[,\<option>[,\<option>...]]:\<attribute>[,\<regular expression>]:\<replacement text>}

Options:

ignore_case[=(true|false)]: If the option is set, filtering with the regular expression is not case-sensitive.

The attribute count is available for the replacement text to output the number of lines.

%{COUNT_LINES,ignore_case:process,"^\:.*activate_uc_object.*":<p>Found %(count) object activations</p>}

DEFINE

The DEFINE function can be used to define replacements for attribute values. This can be used, for example, to adapt values to the output format. The definitions must be defined before replacements are used. It is recommended to use the #HEADER and #HEADER_RUNNABLE templates.

%{DEFINE:\<value>:\<replacement text>}

The <value> can also be specified as a regular expression. The replacement is then applied to all values that match the expression. The expressions should therefore be defined as precisely as possible to avoid ambiguity.

The actual value can also be reinserted in the replacement text. The attribute value can be used for this, as with normal attribute replacement. Some examples are given below.

The following commands can be used to automatically convert the boolean values true and false into a checkbox for the HTML output:

%{DEFINE:true:<input type="checkbox" name="" value="" checked disabled>}
%{DEFINE:false:<input type="checkbox" name="" value="" disabled>}

The actual value is not required here. The following definition can be used to display numerical values right-aligned:

%{DEFINE:[0-9]+:<div style="text-align: right">%(value)</div>}

The original value is used here with the expression %(value). The following definition can be used to display the numbers in italics for timestamps:

%{DEFINE:[0-9]{2}\:[0-9]{2}\:[0-9]{2}:<div style="text-align: right"><i>%(value/:.*///)</i>:<i>%(value/[^:]*://§§/:[^:]*//)</i>:<i>%(value/.*://)</i></div>}

CONST_ATTR

The CONST_ATTR function allows constants to be created in the current context. Context is to be understood here as a scope of validity that refers to the editing of a template. The values of the attributes can also reference other existing attributes.

%{CONST_ATTR:\<attribute name>:\<value>}

In the following example, the new attributes width and height are defined and assigned the value of a number.

%{CONST_ATTR:width:330.0}
%{CONST_ATTR:height:150.0}

If another attribute is part of the value, the attributes are referenced as follows using the familiar syntax.

%{CONST_ATTR:my_x: My x is %(x)}
%{CONST_ATTR:my_y:My y is %(y)}

As can be seen in the examples, constants of different data types can be defined.

SET_ATTR

The SET_ATTR function can be used to add new attributes or change existing attributes. It works in a similar way to the CONST_ATTR function. However, attributes created with this function can also be used in the parameters of other functions, as can be seen in the following example. In addition, they are only valid in the respective context. For example, attributes defined within a LOOP_LIST function cannot be used outside of it.

Attributes created in this way are of the string type. This can be influenced with the TYPE option. The following types are available:

STRING
BOOLEAN
INTEGER
DOUBLE

%{SET_ATTR:subfolder:%(folder/.*\////)}
%{IF:subfolder==CONFIG:
    <p>%(name) is a configuration object</p>
}

%{SET_ATTR,TYPE=DOUBLE:a_number:%{EVAL:js:3.14 * 42}}

EVAL

The EVAL function offers the option of accessing other programming languages and thereby accessing the defined attributes.

%{EVAL:<interpreter>:<statement>}

Currently js (Javascript) is supported as <interpreter>. This allows any Javascript statements to be evaluated. The result is displayed in the result text instead of the call. In the following example, one is subtracted from the value of the attribute x. The result of the calculation is then displayed in the text.

%{EVAL:js:%(x)-1}

Any other Javascript statements can also be selected. For example, a manipulation of the character strings.

%{EVAL:js:"%(alias_or_name)".substring( 4 )}





%{EVAL:js:
    var a = "%(alias_or_name)"
    if ( a.startsWith( "PCK." ) )
        a.substring( 4 )
    else
        a
}

SCRIPT

The SCRIPT function can be used to generate text segments for documentation using other programming languages. All attributes, constants and definitions are available in the script. The text segment can be defined via a previously defined variable. The call looks like this:

%{SCRIPT:<language>:\<Script>}

Currently groovy (Groovy) is supported as <language>. This means that any Groovy scripts can be executed. The following variables are available in the script:

$attributes: All attributes are available in this variable

$constants: This variable contains all constants defined with the CONST_ATTR function

$defines: This variable contains all definitions for value substitutions that were created with the DEFINE function

$output: This variable contains an object of the type StringBuilder. Functions such as append can be used to extend the output of the script

The following examples refer to the index and use attributes that are available there. In the first example, a list of objects with their folders is written to the output file.

%{SCRIPT:groovy:
  for( object in $attributes.objects ) {
    $output.append( "$object.name in folder $object.folder\n" );
  }
}

The multi-line character strings available in Groovy can be used to append several lines to the output at once. The attributes can be resolved directly in the string.

%{SCRIPT:groovy:
$output.append( """\
### b4A Package $attributes.package_name



* A
* list
* of
* items
""" );

Constants defined in one block can be used in other SCRIPT blocks. This means that data can be exchanged between blocks.

%{SCRIPT:groovy:
$constants.DEMO = "welcome to b4A"
}



%{SCRIPT:groovy:
$output.append( $constants.DEMO )
}

DATE

The DATE function allows you to enter a date in the text. A deviation can be defined based on the current date. This can be specified in years, months and days. The dates are always output in the format YYYY-MM-DD.

The following expression can be used to output the current day.

%{DATE::}

Use the following expression for the day before.

%{DATE:-1d:}

And for the day 13 months and 5 days ago, the following expression can be used.

%{DATE:-1y-1m-5d:}

TIME

The TIME function works in the same way as the DATE function, except that it refers to a time that is output in the format HH:MM:SS.

%{TIME::}

For the time, which will be in 3 hours, 5 minutes and 46 seconds, the following specification can be used.

%{TIME:3h5m46s:}

XML2ATTR

note

This function is currently only available for the pm.DocBuilder and util.Mail modules

The XML2ATTR function translates the content of XML variables into best4Automic expression attributes. The elements of the XML documents are converted into individual attributes.

The following XML document is converted into a JavaScript object which can be used directly in the b4A Expressions.

<?xml version="1.0" encoding="UTF-8"?>
  <best4Automic version="4.4.0alpha1">
      <pm>
          <compliance>
              <tests>
                  <test key="agent">
                      <title>Check agents</title>
                      <result>Succeeded</result>
                      <details>The agents of all objects are valid</details>
                  </test>
                  <test key="folders">
                      <title>Check the folder structure</title>
                      <result>Succeeded</result>
                      <details>All necessary folders exist</details>
                  </test>
              </tests>
          </compliance>
      </pm>
  </best4Automic>

The following object is created from the document.

{
  "best4Automic": {
    "version": "6.0.4",
    "pm": {
      "compliance": {
        "tests": {
          "test": [
            {
              "result": "Succeeded",
              "details": "The agents of all objects are valid",
              "title": "Check agents",
              "key": "agent"
            },
            {
              "result": "Succeeded",
              "details": "All necessary folders exist",
              "title": "Check the folder structure",
              "key": "folders"
            }
          ]
        }
      }
    }
  }
}

To access the version field, for example, the attribute best4Automic.version can be used. The LOOP_LIST function can be used to evaluate the results of the tests.

%{LOOP_LIST:best4automic.pm.compliance.tests.test:
  The result of test %(key) is %(result)
}

The function supports two options. The KEY option can be used to select the key of the XML variable from which the XML document is read. If the key is not specified, each key of the variable is read and all documents are mapped as attributes. Each of the documents is encapsulated in an object with the name of the key.

Optionally, the PREFIX option can be added to the function. This option defines an attribute in which the result is embedded.

%{XML2ATTR,PREFIX=xml,KEY=test:VARA.XML)}

The object then looks like this.

{
  "xml": {
    "test": {
      "best4Automic": {
        "version": "6.0.4",
        "pm": {
          "compliance": {
            "tests": {
              "test": [
                {
                  "result": "Succeeded",
                  "details": "The agents of all objects are valid",
                  "title": "Check agents",
                  "key": "agent"
                },
                {
                  "result": "Succeeded",
                  "details": "All necessary folders exist",
                  "title": "Check the folder structure",
                  "key": "folders"
                }
              ]
            }
          }
        }
      }
    }
  }
}

Simple replacements​

Functions​

IF​

LOOP_LIST​

COUNT_LIST​

JOIN​

LOOP_XY​

LOOP_Y​

LOOP_LINES​

COUNT_LINES​

DEFINE​

CONST_ATTR​

SET_ATTR​

EVAL​

SCRIPT​

DATE​

TIME​

XML2ATTR​

Simple replacements

Functions

IF

LOOP_LIST

COUNT_LIST

JOIN

LOOP_XY

LOOP_Y

LOOP_LINES

COUNT_LINES

DEFINE

CONST_ATTR

SET_ATTR

EVAL

SCRIPT

DATE

TIME

XML2ATTR