dacsexpr

DACSEXPR(1)                   DACS Commands Manual                   DACSEXPR(1)



NAME
       dacsexpr - DACS expression language shell and interpreter

SYNOPSIS
       dacsexpr [-x] [dacsoptions[1]] [-dl] [-e expr] [-n] [-p] [-s] [-h |
                -help] [-test]
                [--] [filename] [script-arg...]

DESCRIPTION
       This program is part of the DACS suite.

       The dacsexpr utility evaluates DACS expressions (see dacs.exprs(5)[2]).
       It is often a useful aid when composing or testing expressions to be used
       in access control rules, or when debugging ACLs and configuration
       directives. While they continue to be referred to as "expressions" for
       historical reasons, it has become possible to write small programs, and
       the language can also be useful as a simple scripting language
       independent of the rest of DACS.

       If an expression is provided, it is evaluated and the result is printed
       to the standard output. At most one expression can be specified. If the
       -q flag is given (one of the dacsoptions[1]), nothing is printed,
       expression evaluation errors are suppressed, and the program terminates
       with an appropriate exit status[3]; otherwise the result is written to
       the standard output. If neither a -q flag is given nor any flag that
       controls the logging level, then the logging level is set to warn
       overriding any configuration file logging level directive; this behaviour
       is usually convenient.

       If no expression is provided, the program reads its standard input. If
       the input is not coming from a terminal type device, the program runs in
       "batch mode" and prompting is suppressed; otherwise, the program runs in
       "interactive mode". When prompted in interactive mode, enter help for
       assistance. If the readline(3)[4] functionality was configured when the
       program was built, command line editing and history are available in
       interactive mode.

       A script can be executed through the system's "#!" mechanism:

           #!/usr/local/dacs/bin/dacsexpr

           printf("%s\n", "Hello, world.")

       Such programs always use the script file as input, therefore no
       expression or other file can be specified on the "#!" line.

       Command line arguments can be passed to a script. If dig-it contains:

           #!/usr/local/dacs/bin/dacsexpr

           if (${Argv::#} != 3) {
             printf("Usage: dig-it digest-name msg\n");
             exit(1);
           }

           printf("%s\n", digest(${Argv::2}, 0, ${Argv::1}));

       then running the script produces:

           % ./dig-it sha3-224 mymsg
           88fdaa49d0371a79efa2d6e8a55d27d62cd39ad393309d9a18665763

       The Env namespace is initialized from the program's environment. For
       example, if the value of the environment variable LOGNAME is bobo, then
       ${Env::LOGNAME} will be instantiated with that value. Syntactically
       invalid variable names are silently ignored.

       An empty Expr namespace is created. In interactive use, the prompt string
       can be changed by assigning a string to ${Expr::prompt} and the
       continuation prompt can be changed by setting ${Expr::prompt2}.

           Note
           Configuration directives and the Conf variable namespace are
           available only if a configuration file is processed (e.g., by giving
           the -uj command line flag). This is relevant, for example, if the
           http()[5] function is called using the https scheme because proper
           operation will require the SSL_PROG[6] directive to be configured.
           See dacs.conf(5)[7].

OPTIONS
       If an expression or file has not already been specified, a filename may
       appear as the last argument. If filename is "-", the standard input is
       read.

       -dl
           Print debugging information to stderr.

       -e expr
           The given expression is evaluated.

       -h
       -help
           Display a help message and exit.

       -n
           Do not evaluate any expressions, only check for syntax errors.

       -p
           Print the final result to the standard output, unless it has been
           suppressed by -q or -n. Without this flag, the result would have to
           be output by the program.

       -s
           If a single expression is being evaluated from the command line or a
           file and the result of evaluation is a string or bstring, the output
           will be surrounded by quotes unless this flag is specified.

       -test
           The input is a test case:

               #!/usr/local/dacs/bin/dacsexpr -test
               // expect-exact:17
               ${x} = 17;

           A test case consists of options followed by an expression. There can
           be zero or more options, one per line, embedded within a // style
           comment:

               { whitespace* "//" whitespace* option-name ":" option-value end-of-line }*

           No whitespace is allowed before or after the ":". As a special case,
           lines having the following format are ignored:

               whitespace* "///" .* end-of-line

           The first non-option line terminates the options and is the first
           line of the expression to be evaluated.

           Here is an example:

               /// Test bitwise shifts
               // expect-exact:1024
               1 << 10

           An option controls how the test is to be performed and gives the
           expected result:

           expect:regex
           expect-regex:regex
               The result string must match regex. These two option names are
               equivalent.

           expect-identical:string
               The result string must match string exactly.

           expect-exact:string
               The result string must match string exactly, except that C-style
               character constants (preceded by a backslash) in string are
               interpolated.

           expect-code:code
               The result code must match code, which is 0 if the result is
               True, 1 if the result is False, and 2 if an error occurs. If this
               option is not given, a default code of 0 is assumed.

           expect-type:type
               The type of the result must match type, which can be integer,
               real, string, bstring, literal, or undef.

           expect-flags:flags
               Currently, the only recognized values for flags are rw_namespaces
               and ro_namespaces. The former allows the test to create or modify
               variables in the DACS, Args, or Env namespace; by default, these
               namespaces are read-only. This might be useful when testing
               from()[8], for instance, because it allows the test to set a
               value for ${DACS::REMOTE_ADDR}. The default behaviour can be
               explicitly selected by specifying ro_namespaces.

           show-result:{yes | no}
               The result is printed to the standard output only if the option
               value is yes.

           If the test fails, a descriptive message is printed to the standard
           error. The program's exit status will be 0 if the test was
           successful, 1 otherwise.

           This example should succeed without displaying the result:

               // expect-exact:2
               // expect-type:integer
               /// show-result:yes
               1 + 1


               Note
               The DACS distribution includes a set of test cases in the
               src/tests directory that can be run for regression testing (do
               "make tests" from the src directory). Some of the functions
               provided by dacs.exprs(5)[2] are also used internally by DACS, so
               it is critical that all tests are successful even for functions
               that are not used from the user level.

       -x
           If this is the very first flag it indicates that dacsexpr is being
           executed as a script via the system's "#!" mechanism. This might be
           useful if the program's heuristic for determining this is incorrect.
           The last argument must be a filename.

       --
           This argument explicitly marks the last flag argument. A filename
           argument might follow.

EXAMPLES
       The following command evaluates the expression argument (note that it is
       a single argument to the command) and outputs the result to stdout:

           % dacsexpr -e "1+1"
           2
           % dacsexpr -e '${Env::USER}'
           "bobo"
           % dacsexpr -u example.com -e '"FEDERATION_NAME=" . ${Conf::FEDERATION_NAME}'
           "FEDERATION_NAME=EXAMPLE"
           % dacsexpr - a b c <<HERE
           ? print("First arg is \"\${Argv::1}\"")
           ? HERE
           First arg is "a"
           % cat ex
           #!/usr/local/dacs/bin/dacsexpr

           print("Argv[2] is ${Argv::2}");
           % chmod 0755 ex
           % ./ex foo bar baz
           Argv[2] is bar


DIAGNOSTICS
       If an error occurs, a message may be written to stderr, depending on the
       logging level. In general, the program exits 0 if and only if everything
       was fine. If a command line expression is evaluated, the program exits 0
       if the expression evaluates to True, 1 if it evaluates to False, and 2 if
       an error occurs. If an explicit call to exit() is made and no true error
       condition occurred, then the program will exit with the argument value.

SEE ALSO
       dacs.exprs(5)[2]

BUGS
       New and little-used features should be used with care. This advice
       applies to all software.

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

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

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

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

        3. exit status
           http://dacs.dss.ca/man/#diagnostics

        4. readline(3)
           https://www.freebsd.org/cgi/man.cgi?query=readline&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html

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

        6. SSL_PROG
           http://dacs.dss.ca/man/dacs.conf.5.html#SSL_PROG

        7. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

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

        9. www.dss.ca
           http://www.dss.ca

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



DACS 1.4.40                        02/19/2019                        DACSEXPR(1)