Remixml

!Lib Size

Remixml is a sophisticated XML/XHTML macro language/templating compiler
engine in Javascript.

The Remixml templating engine has the following features:
- It don't need no stinkin' artificial magic delimiters.
- Rich powerful language with dynamic inheritance, autoescaping, functions,
whitespace-collapsing, asynchronous control and more.
- Fast & lean: Small 7 KB gzipped runtime which includes the compiler
which can precompile templates in node and in the browser.
- Compiles to minified Javascript.
- User defined HTML tags in Remixml support named parameters and
recursion.
- Extensible with custom filters and tags programmed in Javascript.
- Easy multi-level caching for even more speed.
- Available everywhere in node and all modern web browsers.
- It contains a fully featured fast validating XHTML parser.
- It shields the Remixml programmer from fatal browser errors by
trapping and logging all errors from within (even from direct javascript
embedded in Remixml), but forgivingly continues parsing to deliver
content regardless.
- Comes with numerous loadable library modules to tailor functionality to the
specific environment leaving the core small.
- Turing complete.
- Preserves all whitespace by default.

The language and primitives used, blend in completely with
standard XML/XHTML syntax and therefore integrate smoothly with
existing XML/XHTML syntax colouring editors.

Compiling and processing XML, XHTML and Remixml automatically performs
sanity checks and shows clear and precise warnings about missing opening
or closing tags.

The package includes a comprehensive regression-testsuite to assure
code quality.

Requirements

It runs inside any webbrowser or NodeJS environment supporting at least
ECMAScript ES2018.

Minified and gzip-compressed, it is less than 7 KB of code.

It has zero dependencies on other modules.

It supports (but does not require) output to the incremental-dom.

Basic usage

In essence Remixml is a macro language that has XHTML/XML-like syntax
and uses special entities to fill in templates. The entities that are
recognised by Remixml are always of the form: &scope.varname;
I.e. they distinguish themselves from regular HTML entities by always
having at least one dot in the entity name.

The following sample Javascript code will illustrate the point:

``js
Remixml.parse2txt(

Title of &_.sitename; for &_.description;

Some global variables &var.some; or &var.globalvars; or
&var.arrays.1; or &var.arrays.2; or &var.objects.foo; or
&anything.really;

,
{_: {
sitename: "foo.bar",
description: "faster than lightning templates"
},
var: {
some: "other",
globalvars: 7,
arrays: ["abc", 14, "def"],
objects: {"foo":"bar", "indeed":"yes"}
},
anything: {
really: "other",
whatever: 7
}
});
`

$3

Simple assigment:

`html
the new value
`

Simple calculations:

`html

`

Conditionals:

`html

yes


second condition valid


otherwise

`

Counted loop:

`html

This is line &_._recno;


`

Iterating through an object or array:

`html
aa,b,cc,d,eee,f

This is record &_._recno; value: &_._value;


`

Defining your own HTML to make it more readable, maintainable and
DRY:

`html
First define some macros


&_.href;



You can click towards .



Now use them



`

Even recursive functions are possible:

`html

1


_.val *






Faculty calculation of &_.valinput;

&_.valinput;! =

Now call our custom HTML tag


`

Reference documentation

$3

& scope . variablename : encoding % formatting ;

- scope

References the primary level in the context object.
- variablename

References second and deeper levels in the context
object (can contain multiple dots to designate deeper levels, is used
to access both objects and arrays).
Variables from the parent scope can always be referenced:
e.g. &_.foo; is a variable named foo in the current scope, whereas
&_._.foo; refers to a variable named foo in the parent scope.
By prepending _. to the path every time, you go one level deeper.
- encoding (optional)

Specifies the encoding to be used when substituting the variable.
The standard encodings available are (you can add custom encodings
using add_filter()):
- html

Default: encodes using
HTML entities.
This is AKA auto-escaping, which prevents XSS (Cross-Site-Scripting).
- uric

URI component: encodes URI arguments in an URL.
- json

Encodes as a JSON string.
- none

No encoding, as is, can be abbreviated as ":;".
- recurse or r

Like none but immediately searches for new entities to substitute
inside the replaced content.
- formatting (optional)

Note: in order to use this, the remixml-fmt module must have been
loaded.

printf()-like formatting
specification
.

Supported formats: %c, %d, %e, %f, %g, %s, %x.

If the formatting string equals a three-letter currency (all capitals),
the value will be formatted like a currency (including currency symbol)
in the current locale.

There is a special format %t: any string following it will be parsed
as a strftime()-like formatting
specification
.

Most formats are supported. Unsupported formats will stay in the
string unchanged.

Note: all entity references evaluate safely. If the entity contains
undefined parts, the resulting substitution string will always be empty.

Note: the entity reference must not contain spaces (the spaces shown
above are there to clarify the format, they should not be used in a real
entity reference). The scope and variablename parts can be described
using the following regular expression: [_$a-zA-Z0-9]+.

$3

All tags strip fully enclosed whitespace patches between tags on the first level
if a single - parameter is given.

`html



`

- mkmapping="" selector="" json="" clone=""
tag="" args="" scope="">...

Attributes:
- var or variable

Assign to the named variable.
- expr

Use the javascript expression specified in this attribute.
Or, alternately, if the attribute is empty, javascript from
the content of this tag is used. Evaluates the javascript and
stores the result.
- regexp

A regular expression to match the content to.
- split

Split the content on this value; if used together with regexp,
it will split the content using a regular
expression.
- join

Join an array using the specified separator.
- mkmapping

Assign this comma-separated list of names to the columns of the array.
- selector

Extract the selected content into an array of
Nodes.
- clone

Clone the first level an array of object into the target while copying.
- json

Parse the content as JSON.
- tag

Declare a custom tag. &_._contents; can be used to reference
the contents of the tag. All argument values are accessible
as variables from the local scope (_). E.g. an attribute
foo="bar" can be referenced as &_.foo; inside the tag definition.
- args

Specifies which arguments this tag expects. All other arguments are
accessible through &_._restargs;.
Using something like allows you to pass
on all the remaining arguments. The special argument :: accepts
an object and spreads out the elements as individual attributes.
Note that all locally defined variables in the current _. scope
not mentioned in the args argument will be included in &_._restargs;.
- scope

Create a toplevel alias for the local scope in this tag definition.
-

Attributes:
- var or variable

Delete the named variable.
- tag

Delete the named tag from the current scope, restores the
definition of this tag from the parent scope (if any).
- ...

Attributes:
- expr

If the Javascript expression evaluates to true, include the
content of the if tag.
- ...

If the last truth value was true, include the content
of the then tag. Not needed for a typical if/else
construction; usually used after a for tag
to specify code that needs to be included if the for tag
actually completed at least one iteration.
- ...

Attributes:
- expr

If the last truth value was false and the Javascript expression evaluates
to true, include the content of the elif tag.
- ...

If the last truth value was false, include the content of
the else tag. Can also be used after a for to specify
code that needs to be included if the for tag did not iterate
at all.
- ...


Upon iteration the following special variables are defined:
- &_._recno;

Starts at 1 and counts up per iteration.
- &_._index;

Contains the current loopindex for counted loops, or the index
for iterations through arrays, or
the key of the current element for iterations through objects.
- &_._value;

Contains the current value for iterations through arrays or objects.

Attributes:
- from

Start counting from here (defaults to 0).
- to

Count up till and including to.
- step

Stepsize (defaults to 1).
- in

Iterate through the named variable (the variable needs to contain
either an array or an object).
- orderby

A comma-separated list of Javascript variable expressions to sort an
iteration
through an object by. When the function desc() is applied to
the expression, the order of that expression will be reversed.
Use the _ scope to designate elements from the current element; if
we are iterating over an array, then a mere _ thus will have the value
of the element.
There is shortcut reference _index which refers to the index
of the current element.
- scope

Create a toplevel alias for the local scope in the current for loop.
- mkmapping

Assign this comma-separated list of names to the columns of an array
in each record. If mkmapping="" and the object in _._value
already has members,
then these members are simply copied into the _ scope;
i.e. _._value.foo becomes accessible as _.foo
as well.
- ...

Should be used inside a for loop. It will suppress its content
upon the first iteration.
- variables="" scope="" expr="">

More explicit way to access variable content instead of through
entities.

Attributes:
- var or variable

Variable name to be inserted. Typically convenient to index objects
using a different variable content as the index.
- quote

Quote method (see entities), defaults to none (contrary to the
entities, which default to html).
- format

Format method (see entities).
- offset

Substring index starting at this offset.
- limit

Substring limit the total number of characters.
- join

If it is an array, join it to a string using the provided separator.
- variables

Insert a variable group:
- dump

Insert a JSON encoded dump of all accessible variables.
- scope

Limit the scope of the dumped variables to the mentioned scope only.
- expr

Use the javascript expression specified in this attribute.
Or, alternately, if the attribute is empty, javascript from
the content of this tag is used. Evaluates the javascript and inserts
the result.
- expr="">...

Attributes:
- from

Search in the content of this tag for this text.
- regexp

Search for this regular expression.
- flags

Regular expression flags.
- to

Replace found occurrences with this text.
$ characters here have special meaning.
- expr

Replace found occurrences with this javascript expression.
- ...

Attributes:
- keep

A comma separated list of all tags that need to be preserved.
- strip

A comma separated list of all tags that need to be stripped.
- ...

Truncates whitespace at both ends, and reduce other whitespace runs of
more than one character to a single space.
- ...

Attributes:
- name

Construct a new tag inline using this name.
Subtags:
- ...

Attributes:
- name

Add attributes to the tag with these names and values.
The attrib subtags need to be at the beginning
of the maketag.
- ...

Reevaluate the content (e.g. useful to execute a tag
created with maketag).

Attributes:
- recurse

Specify the maximum recursion depth; defaults to 0.
Specifying no value sets the maximum depth to unlimited.
Evaluation stops automatically as soon as no changes are detected
anymore.
-

Copy the contents of this tag verbatim without further parsing
(and leave the script tag itself). To force parsing inside
script tags use ... instead.
-

Treated exactly like