Download version 1.4.8: Windows or Linux

Text Library: Evolicity Text Substitution Engine

This library has 55 classes.

Evolicity is a text substitution language that was inspired by the Velocity text substitution language for Java. Evolicity provides a way to merge the data from Eiffel objects into a text template. The template can be either supplied externally or hard-coded into an Eiffel class. The language includes, substitution variables, conditional statements and loops. Substitution variables have a BASH like syntax. Conditionals and loops have an Eiffel like syntax.

The text of this web site was generated by the Eiffel-view repository publisher (See class EIFFEL_VIEW_APP) using the following combination of Evolicity templates:

To make an Eiffel class serializable with Evolicity you inherit from class EVC_SERIALIZEABLE. Read the class notes for details on how to use. You can also access the substitution engine directly from the shared instance in class EVC_SHARED_TEMPLATES

FEATURES

Templates are compiled to an intermediate byte code stored in .evc files. This saves time consuming lexing operations on large templates.

Has a class EVC_CACHEABLE_SERIALIZEABLE for caching the substituted output. Useful for generating pages on a web-server.

VARIABLE CONTEXTS

Variables which can be referenced in the template are specified by implementing the function getter_function_table in classes inheriting EVC_EIFFEL_CONTEXT. It returns a table mapping variable names to agent functions.

getter_function_table: like getter_functions
      --
   do
      create Result.make (<<
         ["<varible-name>",      agent some_function],
         ..
      >>)
   end

Result Types

The result type of each agent function must conform to one of the following:

1. Basic Types

A basic type is one of: READABLE_STRING_GENERAL, INTEGER_32_REF, NATURAL_32_REF, BOOLEAN_REF or REAL_64_REF

2. Evolicity Context

A type conforming to EVC_CONTEXT or EVC_CONTEXT_IMP or EVC_SERIALIZEABLE. In the client template page, you use the standard feature call dot notation to select which object within the context you want to substitute into the template.

3. An Iterable List

An iterable list ITERABLE [G] where G recursively conforms to one of the types 1 to 3.

STANDARD VARIABLES

Contexts which inherit EVC_SERIALIZEABLE have a number of built-in standard variables. These are:

encoding_name: the output encoding for the current template. For example: UTF-8
template_name: the name of the current template. Internally this is of type FILE_PATH.
current: the current context of the template

SYNTAX REFERENCE

Variable Identifiers

Evolicity identifiers must start with an alphabetical character optionally followed by a string of alphanumeric or underscore characters. The standard way to substitute Evolicity variables into the text template is to place the variable name in curly braces prefixed with the '$' symbol, for example foo or foo.bar is: ${foo} or ${foo.bar}. However if there are no identifier characters adjoining the left or right of the variable name as for example ${foo}_x, then this syntax may be abbreviated to just: $foo or $foo.bar

Function Calls

When implementing the {EVC_EIFFEL_CONTEXT}.getter_function_table table it is possible to assign functions with open arguments. You can then call the function from the template using this syntax:

@<qualified-name> (<expression-list>..)

For now the kinds of expression you can use are limited to the following:

A variable reference: $<qualified-name>.
A REAL_64 constant.
An INTEGER_64 constant.
A quoted string.

Conditional Directives

#if <boolean expression> then
   <directive block>
#else
   <directive block>
#end

Currently only a limited range of boolean expressions are possible. A future release will implement a more complete expression parser. For the time being the following types of non-recursive expression are supported:

Numeric comparisons where a and b are numeric variables or integer constants: $a < $b, $a > 0, $a = 0, $a /= 0
Logical conjunction: <expr> and <expr> where <expr> is a numeric comparison or boolean reference variable.
Logical negation: not <expr> where <expr> is a numeric comparison or boolean reference variable.
Container status: <sequence-name>.is_empty where <sequence-name> is a reference to an Eiffel object conforming to type SEQUENCE [G].

More complicated expressions can be implemented an Eiffel function returning a boolean and then referenced as an Evolicity variable.

Iteration of ITERABLE [G] containers

There are two loop syntax alternatives to iterate any object which conforms to the type ITERABLE [G] where G is an object that satisfies the condition {EVC_CONTEXT}.is_valid_type.

1. foreach loop

#foreach $<variable-name> in $<list-name> loop
   <directive block>
#end

The loop index can be referenced using the implicit variable: $loop_index. If in addition the container also conforms to TABLE_ITERABLE [G], then the table key value can be referenced by inserting an additional variable name, separated by a comma. This is similar to Python.

#foreach $<variable-name>, $<key-name> in $<table-name> loop
   <directive block>
#end

2. across loop

This loop syntax imitates the Eiffel across syntax as follows:

#across $<iterable-name> as $<variable-name> loop
   <directive block>
#end

The object referenced by <iterable-name> must conform to type ITERABLE [G]. Exactly like in Eiffel you reference the item values in the directive block using the syntax $<variable-name>.item, and the cursor index can be referenced as: $<variable-name>.cursor_index. If in addition the container also conforms to TABLE_ITERABLE [G], then the table key value can be referenced as $<variable-name>.key.

The Evaluate Directive

The #evaluate directive exists to include the contents of a substituted template inside another template. The #evaluate directive takes two arguments, the first is a reference to a template, and the second to some data that can be referenced from the specified template.

There are 4 ways to reference a template for an #evaluate directive. These are as follows

1. Class template

#evaluate ({<CLASS-NAME>}.template, $<variable-name>)

Here <CLASS-NAME> must be some type which conforms to type EVC_SERIALIZEABLE and therefore has a template. The variable in the second argument is some Eiffel data accessible as an Evolicity variable which is referenced by the nested template.

2. Template reference

#evaluate ($<variable-name>.template_name, $<variable-name>)

Here the first argument is a reference to an object that conforms to type EVC_SERIALIZEABLE and therefore has a template name which be referenced with the implicit variable name template_name.

3. Template path reference

#evaluate ($<template-variable-name>, $<variable-name>)

Here the <template-variable-name> references a file path to an externally loadable template.

You can merge nested templates in a loop using the following syntax.

#across $<iterable-name> as $<variable-name> loop
   #evaluate ($<variable-name>.item.template_name, $<variable-name>.item)
#end

Here the iterable container must conform to type ITERABLE [EVC_SERIALIZEABLE]. Note that even if the the nested text spans multiple lines, as it most likely will do, it will be indented to same indent level as the #evaluate directive.

4. Quoted path string relative to template

#evaluate ("<relative-path>", $Current)

The Include Directive

#include ($<file-path-reference>)
OR
#include ("<file-path>")

The #include directive exists to include another file containing "static text" with no substitution code. The argument can be either a variable reference to a path string or a quoted path.

Directory: library/text/template/evolicity

. /expressions/boolean

. /expressions/comparison

. /serialization

. /support

[ . ]

EVC_COMPILER

Evolicity compiler

EVC_FILE_LEXER

Evolicity file lexer

EVC_SHARED_TEMPLATES

Provides global access to the Evolicity template substitution engine.

The templating substitution language was named "Evolicity" as a portmanteau of "Evolve" and "Felicity" which is also a partial anagram of "Velocity" the Apache project which inspired it. It also bows to an established tradition of naming Eiffel orientated projects starting with the letter 'E'.

Further Information

Click on class link to see notes and client examples.

EVC_TEMPLATES

Top level class for Evolicity accessible via class EVC_SHARED_TEMPLATES

The templating substitution language was named Evolicity as a portmanteau of "Evolve" and "Felicity" which is also a partial anagram of "Velocity" the Apache project which inspired it. It also bows to an established tradition of naming Eiffel orientated projects starting with the letter 'E'.

context

EVC_CONTEXT

Evolicity context

EVC_CONTEXT_IMP

A createable Evolicity context where you add variables in the following ways:

from a table of strings using make_from_string_table
from a table of referenceable object_table using make_from_object_table
Calling put_variable or put_integer

Further Information

Click on class link to see client examples.

EVC_EIFFEL_CONTEXT

Evolicity eiffel context

Further Information

Click on class link to see client examples.

EVC_REFLECTIVE_EIFFEL_CONTEXT

Evolicity Eiffel context with attribute field values available available by reflection

Further Information

Click on class link to see notes and client examples.

EVC_TUPLE_CONTEXT

Evolicity tuple context

Further Information

Click on class link to see client examples.

directives

EVC_ACROSS_DIRECTIVE

Implements an across loop imitating Eiffel syntax as alternative to foreach syntax

EVC_COMPILED_TEMPLATE

Evolicity compiled template

EVC_COMPOUND_DIRECTIVE

Evolicity compound directive

EVC_DIRECTIVE

Evolicity directive

EVC_EVALUATE_DIRECTIVE

Evolicity evaluate directive

EVC_FOREACH_DIRECTIVE

Implemention of iteration of a container conforming to ITERABLE [G]

Further Information

Click on class link to see notes.

EVC_FREE_TEXT_DIRECTIVE

Evolicity free text directive

EVC_IF_ELSE_DIRECTIVE

Evolicity if else directive

EVC_INCLUDE_DIRECTIVE

Evolicity include directive

EVC_NESTED_TEMPLATE_DIRECTIVE

Evolicity nested template directive

EVC_VARIABLE_SUBST_DIRECTIVE

Evolicity variable substitution directive

expressions

EVC_COMPARABLE

Evolicity comparable

EVC_COMPARABLE_VARIABLE

Evolicity comparable variable

EVC_EXPRESSION

Evolicity expression

EVC_NUMERIC_EXPRESSION

Evolicity numeric expression

Further Information

Click on class link to see client examples.

EVC_REFERENCE_EXPRESSION

Evolicity reference expression

expressions/boolean

EVC_BOOLEAN_AND_EXPRESSION

Evolicity boolean and expression

EVC_BOOLEAN_CONJUNCTION_EXPRESSION

Evolicity boolean conjunction expression

EVC_BOOLEAN_EXPRESSION

Evolicity boolean expression

EVC_BOOLEAN_NOT_EXPRESSION

Evolicity boolean not expression

EVC_BOOLEAN_OR_EXPRESSION

Evolicity boolean or expression

EVC_BOOLEAN_REFERENCE_EXPRESSION

Evolicity boolean reference expression

expressions/comparison

EVC_COMPARISON

Evolicity comparison

EVC_EQUAL_TO_COMPARISON

Evolicity equal to comparison

EVC_GREATER_THAN_COMPARISON

Evolicity greater than comparison

EVC_LESS_THAN_COMPARISON

Evolicity less than comparison

EVC_NOT_EQUAL_TO_COMPARISON

Evolicity not equal to comparison

serialization

EVC_CACHEABLE_SERIALIZEABLE

Caches the output of as_text for either EVC_SERIALIZEABLE_AS_STRING_8 or EVC_SERIALIZEABLE_AS_ZSTRING

Further Information

Click on class link to see client examples.

EVC_REFLECTIVE_SERIALIZEABLE

Reflective Evolicity serializeable context

EVC_SERIALIZEABLE

Objects conforming to this class can be serialized as text files using an Evolicity template. A template contains a mixture of literal text and Evolicity code that outputs data from Eiffel objects. The template can be an either an external file or hard coded in the class by implementing the function template: READABLE_STRING_GENERAL.

Further Information

Click on class link to see notes and client examples.

Click on class link to see client examples.