The begin directive starts a region with the specified name:

<!--DACS begin="secret" -->

If the region above named secret is enabled, its content is included in the program's output. Directives that appear in the region, including other begin directives, are processed. Variable references are not expanded; use the expand directive to interpolate variable references. Every begin directive must have a matching end directive.

The region name (the value of the begin attribute) is accessible in rules using ${Args::region}.

The debug directive can be helpful for understanding or debugging processing. It emits variables that exist at the point where an enabled debug directive is processed. This directive has no matching end directive; it is essentially a region with no content.

By default, all variables in the Attrs, Conf, and DACS namespaces are emitted. The attribute name show can be set to Attrs, Conf, or DACS to restrict output to the particular namespace. The value all is equivalent to the default. Alternatively, the attribute name Attrs can be set to "yes" (or "no") to select (or deselect) the Attrs namespace. The same applies for the Conf and DACS attributes. These attribute names are case sensitive but their values are not.

The emitted output is preceded by the directive prefix string in effect and followed by the directive suffix string in effect. It is assumed that no text is emitted in the debugging output that might accidentally be recognized as the suffix string.

The end of a region started by a begin, filter, filterv or expand directive is indicated using the end directive:

<!--DACS begin="secret" -->
This is some secret text.
<!--DACS end="secret" -->

When properly balanced, regions can be nested.

This directive expands variable references in inserted content. Also, text containing variable references may appear in the original content, delimited by an end directive.

An expr, uri, or filename attribute may be used to specify the source of the input as with the insert directive. Variable references in the text from these sources are expanded. If one of these attributes is not specified, the directive must be terminated by an end directive.

Directives in the expanded text are recursively processed, modulo the recurse attribute (see Recursion).

% cat inputfile
<!--DACS expand="*" -->
Nice dog, ${DACS::dog1}.
<!--DACS end="*" -->
Meow!
<!--DACS expand="*" cond="${DACS::dog3} eq:i 'bandito'" -->
Good boy, ${DACS::dog2}.
<!--DACS end="*" -->
% dacstransform -Ddog1=Auggie -Ddog2=Harley -Ddog3=Bandito < inputfile
Nice dog, Auggie.
Meow!
Good boy, Harley.

Original document content within a delimited region, if any, is replaced by new material using the filter directive. This directive must have a corresponding end directive. A newline is appended to the result; if this behaviour is undesirable, use filterv.

Either the expr or uri operations must be specified.

If an expr attribute is present, the original document content, including its final newline character, is passed to the given expression as the value of the variable ${DACS::stdin}. The value of the expression (a string) replaces the region's original content. An evaluation error causes the program to terminate.

If the uri attribute is present, it specifies a web service to which the region should be passed as input and the output of which should replace the original document content. By default, the URI is invoked using the POST method but if a method attribute is present it specifies the HTTP method to use. The http and https schemes are supported. The input is passed as an argument named CONTENT.

If no operation attribute is provided, the original content is evaluated as an expression and its value becomes the new content of the region.

To interpolate the current date you might use:

<!--DACS filter="public" expr="strftime('%v')" -->
<!--DACS end="public" -->

Or equivalently:

<!--DACS filter="public" -->
strftime("%v")
<!--DACS end="public" -->

<!--DACS filter="*" expr="expand(${DACS::stdin})" section="Hello, world" -->
<h1>${Attr::section}</h1>
<!--DACS end="*" -->

<!--DACS filter="*" section="Hello, world" -->
expand("<h1>${Attr::section}</h1>")
<!--DACS end="*" -->

<h1>Hello, world</h1>

This directive is identical to filter except that no newline is appended.

If the region is enabled, the directive is replaced by the current time and date, and a DACS version identification string. This directive has no matching end directive; it is essentially a region with no content.

For example, the directive:

<!--DACS id="*" -->

will be replaced by a line similar to this:

<--DACS Generated 6-Sep-2007@11:37:43 by dacstransform DACS 1.4.20
 Release date 13-Aug-07 09:39:03 (revid 2034) on example.com -->

Note that the replacement line appears as a comment in the emitted document and will pass through dacs_transform unaltered.

Document text is read from a specified source using the insert directive. Exactly one filename, uri, or expr attribute must be provided. Variable references in the inserted content are not expanded - if that is required, use the expand directive. Directives in the inserted content are not processed if recursion has been disabled.

<!--DACS Interpolate browser-specific JavaScript -->
<!--DACS insert="mozilla" filename="/dacs/dacs_transform/js/js1.html" -->
<!--DACS insert="ie" filename="/dacs/dacs_transform/js/js2.html" -->
<!--DACS insert="netscape" filename="/dacs/dacs_transform/js/js3.html" -->

<!--DACS insert="*" uri="http://example.com/data" -->
<!--DACS insert="*" expr="strftime('%v')" -->
<!--DACS insert="*" expr="exec('/bin/date')" -->
<!--DACS insert="*" expr="${Attr::arg1} + ${Attr::arg2}" arg1="10" arg2="20" -->

The region name (the value of the insert attribute) is accessible to rules as the value of ${Args::region}. This directive has no matching end directive; it is essentially a region with no content. Like the begin and end directives, the insert directive names the region so that an appropriate rule can be applied.

The filename attribute gives the pathname of a file to be inserted into the document at the current location. When invoked as dacs_transform, the pathname must be absolute (i.e., it must begin with a slash character).

The uri attribute gives a URI that is invoked to obtain the document to be inserted. The GET method is used by default, but if a method attribute is present it specifies the HTTP method to use. The returned document is inserted at the current location. If the URI's scheme is file, it is equivalent to the filename attribute. The http and https schemes are also recognized.

A third choice is the expr attribute. The expression is evaluated and its result is inserted into the document; an evaluation error causes the program to terminate.

Because it is needed in many cases and harmless in many others, a newline character is emitted after the inserted text. If this behaviour is undesirable, use insertv.

These directives demonstrates how to expand a variable reference found in a template file into the current document:

<!--DACS insert="*" expr="expand(get('/tmp/h1_template'))" s="Section 1"-->
<!--DACS insert="*" expr="expand(get('/tmp/h1_template'))" s="Section 2"-->

If the file /tmp/h1_template looks like:

<h1>${Attr::s}</h1>

then these two lines would be inserted in the program's output:

<h1>Section 1</h1>
<h1>Section 2</h1>

Equivalent but slightly simpler directives can be used for this example:

<!--DACS expand="*" filename="/tmp/h1_template" s="Section 1"-->
<!--DACS expand="*" filename="/tmp/h1_template" s="Section 2"-->

This directive is identical to insert except that no newline is appended.

This directive is used to set variables that will exist for the remainder of the current scope (the document being processed) and any documents that are recursively processed. Setting a variable creates it or overrides its existing value. Any occurrences of the variable in an outer scope are unaffected, as are variables that are created from attributes associated with a directive.

This directive is useful to set a variable to a string that will be used more than once during document processing, or to establish configuration-related variables in a single location. This directive can prevent having to repeatedly pass the same string argument as an attribute in multiple directives.

If gfile looks like:

<!--DACS set="*" foo="1" bar="2" -->
<!--DACS debug="*" show="attrs" -->
<!--DACS set="*" foo="3" bar="4" -->
<!--DACS debug="*" show="attrs" -->
<!--DACS insert="*" filename="gfile2" -->
<!--DACS debug="*" show="attrs" -->

and gfile2 looks like:

<!--DACS debug="*" show="attrs" -->
<!--DACS set="*" foo="5" bar="6" bazz="7" -->
<!--DACS debug="*" show="attrs" -->

then processing gfile will emit this output:

<!--DACS Debug:
Attrs:
debug="*"
show="attrs"
set="*"
foo="1"
bar="2"
-->

<!--DACS Debug:
Attrs:
debug="*"
show="attrs"
set="*"
foo="3"
bar="4"
-->

<!--DACS Debug:
Attrs:
debug="*"
show="attrs"
insert="*"
filename="gfile2"
set="*"
foo="3"
bar="4"
-->

<!--DACS Debug:
Attrs:
debug="*"
show="attrs"
set="*"
foo="5"
bar="6"
bazz="7"
insert="*"
filename="gfile2"
-->

<!--DACS Debug:
Attrs:
debug="*"
show="attrs"
set="*"
foo="3"
bar="4"
-->