dacs_transform

DACS_TRANSFORM(8)           DACS Web Services Manual           DACS_TRANSFORM(8)



NAME
       dacs_transform - rule-based document transformation

SYNOPSIS
       dacs_transform [dacsoptions[1]]

DESCRIPTION
       This web service is part of the DACS suite.

       dacs_transform 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.

       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's output. Text outside of a directive is copied verbatim
       to the program's output.

       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.

           Notedacs_transform is similar in concept or purpose to the Apache
               modules mod_include[2] and mod_rewrite[3]. 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 mod_ext_filter[4].
               It is also conceptually similar to languages like PHP[5] where
               ordinary content and special processing directives can be
               combined within a document.

           •   The dacstransform(1)[6] command provides similar functionality
               from the command line. The transform()[7] function is also
               available.

           •   dacs_transform and dacstransform can be particularly useful tools
               for generating both static and dynamic web pages from template
               files.

           •   For security reasons, access to dacs_transform 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 (REMOTE_USER) is available
               during rule processing.

   Regions
       A directive delimits a region within the source document. A directive
       that is enabled processes its region in some way, otherwise the directive
       and its region are disabled and produce no output. Whether a directive is
       enabled or disabled depends on the DACS rule that is named in the
       directive. Zero-length regions (i.e., regions with no content) are
       allowed.

       The output that is produced by dacs_transform depends on input that is
       copied verbatim, the selection of regions in the original document, the
       document's rules, region evaluation, and the context in which the rules
       are evaluated. Rules can not only inspect the requesting user's identity
       (based on the environment variable REMOTE_USER), including roles
       (obtained from DACS_ROLES), they can employ C-like expressions and a
       variety of built-in functions (see dacs.exprs(5)[8]). Directives are not
       emitted as part of the transformed document.

       Every conditional region is given a name. With the exception of reserved
       names, region names have no particular significance to dacs_transform;
       they are simply attributes to which rules may refer. Each document will
       usually have one or more rules associated with it.

       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 dacs_transform 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.

       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 dacs_transform based on the user's DACS role or the user's
       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's 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.

       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.

       Directive and Attribute Syntax
           In an HTML document served by dacs_transform, 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 configurable[9].

               Note
               •   Whitespace is not ignored at the beginning or end of an input
                   line.

               •   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), dacs_transform can also work with
                   those documents.

               •   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 dacs_transform.

           A directive contains one or more attribute="value" pairs. Exactly one
           attribute name must be a directive name that indicates the operation
           to be performed. An attribute name must be a syntactically valid
           variable name[10]. The value 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 expression[11]. Variables from the Env and Conf
           namespaces[12] are instantiated. The current directive's attributes
           are accessible in the Attr namespace; these attribute values are
           unevaluated and quoted.

           This example input contains two regions:

               <!--DACS begin="English" -->
               Hello!
               <!--DACS end="English" -->
               <!--DACS begin="French" -->
               Bonjour!
               <!--DACS end="French" -->


               Note
               •   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 True.

               •   For all directives, a region name prefixed by the negation
                   operator[13] inverts the selection test.

               •   For all directives, regardless of the region name, an
                   attribute named "cond" may be provided. Its value is an
                   expression that must evaluate to True for the region to be
                   processed. If a rule also applies to the directive, both the
                   rule and the expression must grant access.

           Directive names, which are described below, are reserved and have
           special meaning to dacs_transform. 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.

       Negation
           A region name prefixed by the negation operator ("!") indicates that
           the region should be enabled if the rule returns False and should be
           disabled if it returns True. 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.

           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:

               <!--DACS begin="!secret" -->
               This is public stuff, not secret stuff.
               <!--DACS end="!secret" -->


       Recursion
           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).

           A maximum stack depth is imposed, primarily to guard against infinite
           recursion. This limit is currently set to 100 at compile time.

           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.

       Directives
           Directive Index:

            1. begin: start a region

            2. debug: emit variables for debugging

            3. end: end a region

            4. expand: insert content and interpolate variables

            5. filter: transform content

            6. filterv: transform content, verbatim

            7. id: insert an identification string

            8. insert: insert content

            9. insertv: insert content, verbatim

           10. set: set or reset variables

           begin
               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[14] directive to
               interpolate variable references. Every begin directive must have
               a matching end[15] directive.

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

           debug
               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.

           end
               The end of a region started by a begin[16], filter[17],
               filterv[18] or expand[14] 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.

           expand
               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[19] 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[20]).

                   % 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.


           filter

                   Note
                   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.
               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[18].

               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[11] 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[11] 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" -->


                   Tip
                   To simply substitute variable values into the original
                   content, use the expand[14] directive or the expand()[21]
                   function. For example:

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

                   Or, alternatively:

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

                   In either variation, the three lines in the document are
                   replaced by a single line:

                       <h1>Hello, world</h1>

                   Tip
                   A filter directive with an expr or uri attribute and an empty
                   region can be written more simply using an insert directive.

           filterv
               This directive is identical to filter[17] except that no newline
               is appended.

           id
               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.

           insert
               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[14] directive.
               Directives in the inserted content are not processed if
               recursion[20] 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[11] 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[22].

               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"-->


           insertv
               This directive is identical to insert[19] except that no newline
               is appended.

           set
               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"
                   -->


       Configuration
           Configuration variables can be set to change some of the program's
           defaults:

           •   transform_docs: This is the full pathname of the root directory
               in which original documents are kept. By default, the program
               will use a subdirectory ${Conf::DACS_HOME}dacs_transform/docs.
               (default: /usr/local/dacs/dacs_transform/docs)

                   Security
                   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.

           •   transform_acls: This is the VFS specification for the rules. By
               default, the program will use
               ${Conf::DACS_HOME}dacs_transform/acls. (default:
               [transform-acls]dacs-fs:/usr/local/dacs/dacs_transform/acls)

           •   transform_annotation: This is the annotation to interpolate in
               redacted text instead of the default.

           •   transform_prefix: 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.

           •   transform_suffix: Instead of the default prefix used to end a
               directive, the value of this variable is used.

           •   transform_rprefix: A line whose beginning matches the specified
               regular expression introduces a directive.

           •   transform_rsuffix: The end of a directive is found by matching
               the specified regular expression.

           IEEE Std 1003.2 ("POSIX.2") "extended" regular expressions are
           supported (regex(3)[23]).

   Web Service Arguments
       In addition to the standard CGI arguments[24], dacs_transform understands
       the following CGI arguments:

       DOC
           This value of this argument specifies the document to be transformed
           as a file on the server running dacs_transform. It is an absolute
           path that is remapped within a segregated area of the web server.

       DOCURI
           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.

       ANNOTATE
           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.

       CONTENT_TYPE
           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.

DIAGNOSTICS
       The program exits 0 if everything was fine, 1 if an error occurred.

SEE ALSO
       dacstransform(1)[6], dacs.exprs(5)[11], dacs.acls(5)[25]

BUGS
       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.

AUTHOR
       Distributed Systems Software (www.dss.ca[26])

COPYING
       Copyright © 2003-2018 Distributed Systems Software. See the LICENSE[27]
       file that accompanies the distribution for licensing information.

NOTES
        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. mod_include
           http://httpd.apache.org/docs/2.4/mod/mod_include.html

        3. mod_rewrite
           http://httpd.apache.org/docs/2.4/mod/mod_rewrite.html

        4. mod_ext_filter
           http://httpd.apache.org/docs/2.4/mod/mod_ext_filter.html

        5. PHP
           http://www.php.net/

        6. dacstransform(1)
           http://dacs.dss.ca/man/dacstransform.1.html

        7. transform()
           http://dacs.dss.ca/man/dacs.exprs.5.html#transform

        8. dacs.exprs(5)
           http://dacs.dss.ca/man//dacs/man/dacs.exprs.5.html

        9. configurable
           http://dacs.dss.ca/man/#configuration

       10. syntactically valid variable name
           http://dacs.dss.ca/man/dacs.exprs.5.html#variable_syntax

       11. expression
           http://dacs.dss.ca/man/dacs.exprs.5.html

       12. namespaces
           http://dacs.dss.ca/man/dacs.exprs.5.html#reserved_namespaces

       13. negation operator
           http://dacs.dss.ca/man/#negation

       14. expand
           http://dacs.dss.ca/man/#EXPAND

       15. end
           http://dacs.dss.ca/man/#END

       16. begin
           http://dacs.dss.ca/man/#BEGIN

       17. filter
           http://dacs.dss.ca/man/#FILTER

       18. filterv
           http://dacs.dss.ca/man/#FILTERV

       19. insert
           http://dacs.dss.ca/man/#INSERT

       20. Recursion
           http://dacs.dss.ca/man/#recursion

       21. expand()
           http://dacs.dss.ca/man/dacs.exprs.5.html#expand

       22. insertv
           http://dacs.dss.ca/man/#INSERTV

       23. regex(3)
           https://www.freebsd.org/cgi/man.cgi?query=regex&apropos=0&esektion=3&emanpath=FreeBSD+10.3-RELEASE&format=html

       24. standard CGI arguments
           http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args

       25. dacs.acls(5)
           http://dacs.dss.ca/man/dacs.acls.5.html

       26. www.dss.ca
           http://www.dss.ca

       27. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE



DACS 1.4.40                        02/19/2019                  DACS_TRANSFORM(8)