.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacs_transform
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_TRANSFORM" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacs_transform \- rule\-based document transformation
.SH "SYNOPSIS"
.HP \w'\fBdacs_transform\fR\ 'u
\fBdacs_transform\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This web service is part of the
\fBDACS\fR
suite\&.
.PP
\fBdacs_transform\fR
can perform a variety of transformations on an original document to produce a new document\&. Transformations such as redaction, insertion, and replacement are available\&. What makes the program interesting is that any transformation can depend on a rule that is evaluated at run\-time, allowing a new document to be tailored for a specific user or context\&.
.PP
The program looks for embedded markup (meta\-information) called
directives
in the input document\&. A directive specifies a conditional (rule\-based) or unconditional operation that is evaluated at that point in the document to determine the output text that is to be interpolated into the program\*(Aqs output\&. Text outside of a directive is copied verbatim to the program\*(Aqs output\&.
.PP
One application of this software is to produce different versions of documentation from the same input\&. For example, consider a requirement to produce technical documentation for a series of printers where the printers are substantially the same (their documentation shares a lot of the same text and graphics) but each model has unique features or capabilities\&. Instead of producing a single manual that describes all models, which makes the manual larger and more complicated than necessary, this software provides a convenient way to create model\-specific documentation from the same input\&. This means that the documentation common to all printers is shared by all of the manuals, yet the manual for each printer is easily customized for the particular printer\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdacs_transform\fR
is similar in concept or purpose to the Apache modules
\m[blue]\fBmod_include\fR\m[]\&\s-2\u[2]\d\s+2
and
\m[blue]\fBmod_rewrite\fR\m[]\&\s-2\u[3]\d\s+2\&. It is not an Apache module, however, and can therefore be used with any web server, and provides rich, rule\-based selection of regions for processing\&. It can be used in conjunction with
\m[blue]\fBmod_ext_filter\fR\m[]\&\s-2\u[4]\d\s+2\&. It is also conceptually similar to languages like
\m[blue]\fBPHP\fR\m[]\&\s-2\u[5]\d\s+2
where ordinary content and special processing directives can be combined within a document\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\m[blue]\fBdacstransform(1)\fR\m[]\&\s-2\u[6]\d\s+2
command provides similar functionality from the command line\&. The
\m[blue]\fBtransform()\fR\m[]\&\s-2\u[7]\d\s+2
function is also available\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdacs_transform\fR
and
\fBdacstransform\fR
can be particularly useful tools for generating both static and dynamic web pages from template files\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For security reasons, access to
\fBdacs_transform\fR
is disabled by default\&. Some configuration capabilities and features expected in a production version have not been implemented\&. If there are multiple identities, only one identity (\fBREMOTE_USER\fR) is available during rule processing\&.
.RE
.sp .5v
.RE
.SS "Regions"
.PP
A directive delimits a
region
within the source document\&. A directive that is
\fIenabled\fR
processes its region in some way, otherwise the directive and its region are
\fIdisabled\fR
and produce no output\&. Whether a directive is enabled or disabled depends on the
\fBDACS\fR
rule that is named in the directive\&. Zero\-length regions (i\&.e\&., regions with no content) are allowed\&.
.PP
The output that is produced by
\fBdacs_transform\fR
depends on input that is copied verbatim, the selection of regions in the original document, the document\*(Aqs rules, region evaluation, and the context in which the rules are evaluated\&. Rules can not only inspect the requesting user\*(Aqs identity (based on the environment variable
\fBREMOTE_USER\fR), including roles (obtained from
\fBDACS_ROLES\fR), they can employ C\-like expressions and a variety of built\-in functions (see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[8]\d\s+2)\&. Directives are
\fInot\fR
emitted as part of the transformed document\&.
.PP
Every conditional region is given a name\&. With the exception of reserved names, region names have no particular significance to
\fBdacs_transform\fR; they are simply attributes to which rules may refer\&. Each document will usually have one or more rules associated with it\&.
.PP
For example, an author might assign a name representing a security level to each region in a document:
public,
secret,
top\-secret, and so on\&. For each of these security levels, a specified set of rules would be examined by
\fBdacs_transform\fR
to decide which identities are granted (or denied) access to the corresponding region\&. In this way, different users may be given different versions of the same source document; some users might not be able to view
secret
and
top\-secret
content, other might be able to view all content\&.
.PP
A document that combined text written in different languages might name regions
English,
French,
Russian, and so on; the English regions might be enabled by
\fBdacs_transform\fR
based on the user\*(Aqs
\fBDACS\fR
role or the user\*(Aqs stored preference for that language\&. Another document might contain region names corresponding to time zones:
PST,
MST,
EST, and so on\&. A rule might then require the time zone associated with the location corresponding to the user\*(Aqs apparent IP address to match that of the region being tested\&. Or an audio stream or speech synthesis content might be automatically enabled if a user has a role that indicates she is visually impaired\&.
.PP
At present, no facility is available to assist with working with meta\-information\&. It must either be added manually or generated by an application that understands how to insert meta\-information in its output\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBDirective and Attribute Syntax\fR
.RS 4
.PP
In an HTML document served by
\fBdacs_transform\fR, a region consists of a single directive or is delimited by a pair of directives\&. All other document content is ignored with respect to transformation\&. By default, directives are contained within HTML\-style comments and the start of a directive is indicated by a line having the initial nine characters "<!\-\-DACS" and ending with the normal HTML end\-of\-comment syntax, "\-\->"\&. Such a line is unlikely to occur in a document by accident, but the syntax is
\m[blue]\fBconfigurable\fR\m[]\&\s-2\u[9]\d\s+2\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Whitespace is not ignored at the beginning or end of an input line\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Because the syntax for comments defined for HTML is also acceptable in SGML and XML (and any similar markup language that is based on SGML),
\fBdacs_transform\fR
can also work with those documents\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A directive cannot be "commented out" except by modifying the line on which it occurs so that the directive will not be recognized as such\&. That is, the context in which a directive occurs with respect to the original document is not considered by
\fBdacs_transform\fR\&.
.RE
.sp .5v
.RE
.PP
A directive contains one or more
\fIattribute\fR="\fIvalue\fR" pairs\&. Exactly one attribute name must be a directive name that indicates the operation to be performed\&. An attribute name must be a
\m[blue]\fBsyntactically valid variable name\fR\m[]\&\s-2\u[10]\d\s+2\&. The
\fIvalue\fR
must be enclosed in matching double quotes, single quotes, or backticks (decimal ASCII code 96)\&. Backtick quotes are treated differently in that the enclosed string is evaluated as an
\m[blue]\fBexpression\fR\m[]\&\s-2\u[11]\d\s+2\&. Variables from the
\fIEnv\fR
and
\fIConf\fR
\m[blue]\fBnamespaces\fR\m[]\&\s-2\u[12]\d\s+2
are instantiated\&. The current directive\*(Aqs attributes are accessible in the
\fIAttr\fR
namespace; these attribute values are
\fIunevaluated\fR
and quoted\&.
.PP
This example input contains two regions:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS begin="English" \-\->
Hello!
<!\-\-DACS end="English" \-\->
<!\-\-DACS begin="French" \-\->
Bonjour!
<!\-\-DACS end="French" \-\->
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For all directives, the region name "*" is reserved and indicates that the region should be enabled without evaluating any rule\&. If an author wants to always insert some text or an identification string, for instance, this feature eliminates the need to create a rule that does nothing other than return
\fBTrue\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For all directives, a region name prefixed by the
\m[blue]\fBnegation operator\fR\m[]\&\s-2\u[13]\d\s+2
inverts the selection test\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For all directives, regardless of the region name, an attribute named "cond" may be provided\&. Its value is an expression that must evaluate to
\fBTrue\fR
for the region to be processed\&. If a rule also applies to the directive, both the rule and the expression must grant access\&.
.RE
.sp .5v
.RE
.PP
Directive names, which are described below, are reserved and have special meaning to
\fBdacs_transform\fR\&. Unrecognized attributes are ignored but can be referenced as arguments by rules\&. A given attribute cannot appear more than once within a directive\&. All attribute names are case\-insensitive\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNegation\fR
.RS 4
.PP
A region name prefixed by the negation operator ("!") indicates that the region should be enabled if the rule returns
\fBFalse\fR
and should be disabled if it returns
\fBTrue\fR\&. Note that the negation character is not part of the region name\&. This syntax eliminates the need to write separate "if\-true" and "if\-false" versions of the same rule, although it is an inefficient substitute for an if/else construct\&.
.PP
For example, if a document only has public and secret regions, instead of defining one rule for public regions and another for secret regions, an author might simply define a single rule to identify secret regions and use negation:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS begin="!secret" \-\->
This is public stuff, not secret stuff\&.
<!\-\-DACS end="!secret" \-\->
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBRecursion\fR
.RS 4
.PP
By default, content that is included during processing of an
insert,
insertv, or
expand
directive is recursively processed for directives\&. Recursion may be disabled on a case\-by\-case basis by specifying the
recurse
attribute with a value of "no" (case insensitively)\&. It may also be explicitly enabled by specifying the attribute value "yes" (case insensitively)\&.
.PP
A maximum stack depth is imposed, primarily to guard against infinite recursion\&. This limit is currently set to
\fB100\fR
at compile time\&.
.PP
Variables set by outer levels can be referenced by inner levels\&. If variables at different levels have the same name, however, only the innermost value is accessible\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBDirectives\fR
.RS 4
.PP
\fBDirective Index:\fR
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
begin: start a region
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
debug: emit variables for debugging
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
end: end a region
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
expand: insert content and interpolate variables
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
filter: transform content
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  6." 4.2
.\}
filterv: transform content, verbatim
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  7." 4.2
.\}
id: insert an identification string
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  8." 4.2
.\}
insert: insert content
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  9." 4.2
.\}
insertv: insert content, verbatim
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "10." 4.2
.\}
set: set or reset variables
.RE
.PP
begin
.RS 4
The
begin
directive starts a region with the specified name:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS begin="secret" \-\->
.fi
.if n \{\
.RE
.\}
.sp
If the region above named
secret
is enabled, its content is included in the program\*(Aqs output\&. Directives that appear in the region, including other
begin
directives, are processed\&. Variable references are not expanded; use the
\m[blue]\fBexpand\fR\m[]\&\s-2\u[14]\d\s+2
directive to interpolate variable references\&. Every
begin
directive must have a matching
\m[blue]\fBend\fR\m[]\&\s-2\u[15]\d\s+2
directive\&.
.sp
The region name (the value of the
begin
attribute) is accessible in rules using
\fI${Args::region}\fR\&.
.RE
.PP
debug
.RS 4
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\&.
.sp
By default, all variables in the
\fIAttrs\fR,
\fIConf\fR, and
\fIDACS\fR
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
\fIAttrs\fR
namespace\&. The same applies for the
Conf
and
DACS
attributes\&. These attribute names are case sensitive but their values are not\&.
.sp
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\&.
.RE
.PP
end
.RS 4
The end of a region started by a
\m[blue]\fBbegin\fR\m[]\&\s-2\u[16]\d\s+2,
\m[blue]\fBfilter\fR\m[]\&\s-2\u[17]\d\s+2,
\m[blue]\fBfilterv\fR\m[]\&\s-2\u[18]\d\s+2
or
\m[blue]\fBexpand\fR\m[]\&\s-2\u[14]\d\s+2
directive is indicated using the
end
directive:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS begin="secret" \-\->
This is some secret text\&.
<!\-\-DACS end="secret" \-\->
.fi
.if n \{\
.RE
.\}
.sp
When properly balanced, regions can be nested\&.
.RE
.PP
expand
.RS 4
This directive expands variable references in inserted content\&. Also, text containing variable references may appear in the original content, delimited by an
end
directive\&.
.sp
An
expr,
uri, or
filename
attribute may be used to specify the source of the input as with the
\m[blue]\fBinsert\fR\m[]\&\s-2\u[19]\d\s+2
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\&.
.sp
Directives in the expanded text are recursively processed, modulo the
recurse
attribute (see
\m[blue]\fBRecursion\fR\m[]\&\s-2\u[20]\d\s+2)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% cat inputfile
<!\-\-DACS expand="*" \-\->
Nice dog, ${DACS::dog1}\&.
<!\-\-DACS end="*" \-\->
Meow!
<!\-\-DACS expand="*" cond="${DACS::dog3} eq:i \*(Aqbandito\*(Aq" \-\->
Good boy, ${DACS::dog2}\&.
<!\-\-DACS end="*" \-\->
% dacstransform \-Ddog1=Auggie \-Ddog2=Harley \-Ddog3=Bandito < inputfile
Nice dog, Auggie\&.
Meow!
Good boy, Harley\&.
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
filter
.RS 4
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This feature is only partially implemented\&. In the current implementation, a
filter
directive must use the
expr
operation and may not include another
filter
region\&.
.sp .5v
.RE
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
\m[blue]\fBfilterv\fR\m[]\&\s-2\u[18]\d\s+2\&.
.sp
Either the
expr
or
uri
operations must be specified\&.
.sp
If an
expr
attribute is present, the original document content, including its final newline character, is passed to the given
\m[blue]\fBexpression\fR\m[]\&\s-2\u[11]\d\s+2
as the value of the variable
\fI${DACS::stdin}\fR\&. The value of the expression (a string) replaces the region\*(Aqs original content\&. An evaluation error causes the program to terminate\&.
.sp
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
\fICONTENT\fR\&.
.sp
If no operation attribute is provided, the original content is evaluated as an
\m[blue]\fBexpression\fR\m[]\&\s-2\u[11]\d\s+2
and its value becomes the new content of the region\&.
.sp
To interpolate the current date you might use:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS filter="public" expr="strftime(\*(Aq%v\*(Aq)" \-\->
<!\-\-DACS end="public" \-\->
.fi
.if n \{\
.RE
.\}
.sp
Or equivalently:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS filter="public" \-\->
strftime("%v")
<!\-\-DACS end="public" \-\->
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
To simply substitute variable values into the original content, use the
\m[blue]\fBexpand\fR\m[]\&\s-2\u[14]\d\s+2
directive or the
\m[blue]\fBexpand()\fR\m[]\&\s-2\u[21]\d\s+2
function\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS filter="*" expr="expand(${DACS::stdin})" section="Hello, world" \-\->
<h1>${Attr::section}</h1>
<!\-\-DACS end="*" \-\->
.fi
.if n \{\
.RE
.\}
.sp
Or, alternatively:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS filter="*" section="Hello, world" \-\->
expand("<h1>${Attr::section}</h1>")
<!\-\-DACS end="*" \-\->
.fi
.if n \{\
.RE
.\}
.sp
In either variation, the three lines in the document are replaced by a single line:
.sp
.if n \{\
.RS 4
.\}
.nf
<h1>Hello, world</h1>
.fi
.if n \{\
.RE
.\}
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
A
filter
directive with an
expr
or
uri
attribute and an empty region can be written more simply using an
insert
directive\&.
.sp .5v
.RE
.RE
.PP
filterv
.RS 4
This directive is identical to
\m[blue]\fBfilter\fR\m[]\&\s-2\u[17]\d\s+2
except that no newline is appended\&.
.RE
.PP
id
.RS 4
If the region is enabled, the directive is replaced by the current time and date, and a
\fBDACS\fR
version identification string\&. This directive has no matching
end
directive; it is essentially a region with no content\&.
.sp
For example, the directive:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS id="*" \-\->
.fi
.if n \{\
.RE
.\}
.sp
will be replaced by a line similar to this:
.sp
.if n \{\
.RS 4
.\}
.nf
<\-\-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 \-\->
.fi
.if n \{\
.RE
.\}
.sp
Note that the replacement line appears as a comment in the emitted document and will pass through
\fBdacs_transform\fR
unaltered\&.
.RE
.PP
insert
.RS 4
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
\fInot\fR
expanded \- if that is required, use the
\m[blue]\fBexpand\fR\m[]\&\s-2\u[14]\d\s+2
directive\&. Directives in the inserted content are not processed if
\m[blue]\fBrecursion\fR\m[]\&\s-2\u[20]\d\s+2
has been disabled\&.
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-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(\*(Aq%v\*(Aq)" \-\->
<!\-\-DACS insert="*" expr="exec(\*(Aq/bin/date\*(Aq)" \-\->
<!\-\-DACS insert="*" expr="${Attr::arg1} + ${Attr::arg2}" arg1="10" arg2="20" \-\->
.fi
.if n \{\
.RE
.\}
.sp
The region name (the value of the
insert
attribute) is accessible to rules as the value of
\fI${Args::region}\fR\&. 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\&.
.sp
The
filename
attribute gives the pathname of a file to be inserted into the document at the current location\&. When invoked as
\fBdacs_transform\fR, the pathname must be absolute (i\&.e\&., it must begin with a slash character)\&.
.sp
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\*(Aqs scheme is
file, it is equivalent to the
filename
attribute\&. The
http
and
https
schemes are also recognized\&.
.sp
A third choice is the
expr
attribute\&. The
\m[blue]\fBexpression\fR\m[]\&\s-2\u[11]\d\s+2
is evaluated and its result is inserted into the document; an evaluation error causes the program to terminate\&.
.sp
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
\m[blue]\fBinsertv\fR\m[]\&\s-2\u[22]\d\s+2\&.
.sp
These directives demonstrates how to expand a variable reference found in a template file into the current document:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS insert="*" expr="expand(get(\*(Aq/tmp/h1_template\*(Aq))" s="Section 1"\-\->
<!\-\-DACS insert="*" expr="expand(get(\*(Aq/tmp/h1_template\*(Aq))" s="Section 2"\-\->
.fi
.if n \{\
.RE
.\}
.sp
If the file
/tmp/h1_template
looks like:
.sp
.if n \{\
.RS 4
.\}
.nf
<h1>${Attr::s}</h1>
.fi
.if n \{\
.RE
.\}
.sp
then these two lines would be inserted in the program\*(Aqs output:
.sp
.if n \{\
.RS 4
.\}
.nf
<h1>Section 1</h1>
<h1>Section 2</h1>
.fi
.if n \{\
.RE
.\}
.sp
Equivalent but slightly simpler directives can be used for this example:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS expand="*" filename="/tmp/h1_template" s="Section 1"\-\->
<!\-\-DACS expand="*" filename="/tmp/h1_template" s="Section 2"\-\->
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
insertv
.RS 4
This directive is identical to
\m[blue]\fBinsert\fR\m[]\&\s-2\u[19]\d\s+2
except that no newline is appended\&.
.RE
.PP
set
.RS 4
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\&.
.sp
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\&.
.sp
If
gfile
looks like:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-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" \-\->
.fi
.if n \{\
.RE
.\}
.sp
and
gfile2
looks like:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-DACS debug="*" show="attrs" \-\->
<!\-\-DACS set="*" foo="5" bar="6" bazz="7" \-\->
<!\-\-DACS debug="*" show="attrs" \-\->
.fi
.if n \{\
.RE
.\}
.sp
then processing
gfile
will emit this output:
.sp
.if n \{\
.RS 4
.\}
.nf
<!\-\-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"
\-\->
.fi
.if n \{\
.RE
.\}
.sp
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBConfiguration\fR
.RS 4
.PP
Configuration variables can be set to change some of the program\*(Aqs defaults:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_docs\fR: This is the full pathname of the root directory in which original documents are kept\&. By default, the program will use a subdirectory
\fI${Conf::DACS_HOME}\fRdacs_transform/docs\&. (default:
/usr/local/dacs/dacs_transform/docs)
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
Change the default with care\&. In the absence of an appropriate access control rule, setting the pathname to "/" or the empty string, would provide access to any file on the server that can be read by this web service\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_acls\fR: This is the VFS specification for the rules\&. By default, the program will use
\fI${Conf::DACS_HOME}\fRdacs_transform/acls\&. (default:
[transform\-acls]dacs\-fs:/usr/local/dacs/dacs_transform/acls)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_annotation\fR: This is the annotation to interpolate in redacted text instead of the default\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_prefix\fR: Instead of the default prefix used to introduce a directive, the value of this variable is used\&. It must appear at the beginning of a line\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_suffix\fR: Instead of the default prefix used to end a directive, the value of this variable is used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_rprefix\fR: A line whose beginning matches the specified regular expression introduces a directive\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fItransform_rsuffix\fR: The end of a directive is found by matching the specified regular expression\&.
.RE
.PP
IEEE Std 1003\&.2 ("POSIX\&.2") "extended" regular expressions are supported (\m[blue]\fBregex(3)\fR\m[]\&\s-2\u[23]\d\s+2)\&.
.RE
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[24]\d\s+2,
\fBdacs_transform\fR
understands the following CGI arguments:
.PP
\fIDOC\fR
.RS 4
This value of this argument specifies the document to be transformed as a file on the server running
\fBdacs_transform\fR\&. It is an absolute path that is remapped within a segregated area of the web server\&.
.RE
.PP
\fIDOCURI\fR
.RS 4
This argument specifies the document to be transformed as a URI\&. The URI must use the
http
or
https
scheme\&. The HTTP
GET
method is used to fetch the document and the URI may include query arguments\&. The URI must be properly URL\-encoded\&.
.RE
.PP
\fIANNOTATE\fR
.RS 4
If this argument is present and its value is "yes", each deleted region of text is denoted in the retrieved document; contiguous deleted regions are denoted only once\&. The default annotation assumes a document
Content\-Type
of
text/html\&.
.RE
.PP
\fICONTENT_TYPE\fR
.RS 4
If this argument is present, this will be the MIME
Content\-Type
of the returned document\&. If this argument is omitted, the program will try to guess the type based on the suffix of the name of the original document, or default to
text/html\&.
.RE
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacstransform(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[11]\d\s+2,
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[25]\d\s+2
.SH "BUGS"
.PP
There is a lot of room for improvement and new features\&. Directive syntax slants towards the arcane; that may get worse before it gets better\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[26]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[27]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
mod_include
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_include.html
.RE
.IP " 3." 4
mod_rewrite
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_rewrite.html
.RE
.IP " 4." 4
mod_ext_filter
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_ext_filter.html
.RE
.IP " 5." 4
PHP
.RS 4
\%http://www.php.net/
.RE
.IP " 6." 4
dacstransform(1)
.RS 4
\%http://dacs.dss.ca/man/dacstransform.1.html
.RE
.IP " 7." 4
transform()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#transform
.RE
.IP " 8." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man//dacs/man/dacs.exprs.5.html
.RE
.IP " 9." 4
configurable
.RS 4
\%http://dacs.dss.ca/man/#configuration
.RE
.IP "10." 4
syntactically valid variable name
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#variable_syntax
.RE
.IP "11." 4
expression
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP "12." 4
namespaces
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#reserved_namespaces
.RE
.IP "13." 4
negation operator
.RS 4
\%http://dacs.dss.ca/man/#negation
.RE
.IP "14." 4
expand
.RS 4
\%http://dacs.dss.ca/man/#EXPAND
.RE
.IP "15." 4
end
.RS 4
\%http://dacs.dss.ca/man/#END
.RE
.IP "16." 4
begin
.RS 4
\%http://dacs.dss.ca/man/#BEGIN
.RE
.IP "17." 4
filter
.RS 4
\%http://dacs.dss.ca/man/#FILTER
.RE
.IP "18." 4
filterv
.RS 4
\%http://dacs.dss.ca/man/#FILTERV
.RE
.IP "19." 4
insert
.RS 4
\%http://dacs.dss.ca/man/#INSERT
.RE
.IP "20." 4
Recursion
.RS 4
\%http://dacs.dss.ca/man/#recursion
.RE
.IP "21." 4
expand()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#expand
.RE
.IP "22." 4
insertv
.RS 4
\%http://dacs.dss.ca/man/#INSERTV
.RE
.IP "23." 4
regex(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&esektion=3&emanpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "24." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP "25." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP "26." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "27." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE