DACSEXPR(1) | DACS Commands Manual | DACSEXPR(1) |
NAME¶
dacsexpr - DACS expression language shell and interpreterSYNOPSIS¶
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. If the program is executed through the system's "#!" mechanism, one or more command line arguments can be given:#!/usr/local/dacs/bin/dacsexpr -test // expect-exact:17 ${x} = 17;
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. -dlPrint debugging information to stderr.
-e expr
The given expression is evaluated.
-h
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. 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:
No whitespace is allowed before or after the ":". As a special case,
lines having the following format are ignored:
The first non-option line terminates the options and is the first line of the
expression to be evaluated.
Here is an example:
An option controls how the test is to be performed and gives the expected
result:
expect: regex
expect-regex: regex
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
{ whitespace* "//" whitespace* option-name ":" option-value end-of-line }*
whitespace* "///" .* end-of-line
/// Test bitwise shifts // expect-exact:1024 1 << 10
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
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¶
Copyright2003-2013 Distributed Systems Software. See the LICENSE[10] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsoptions
- 3.
- exit status
- 4.
- readline(3)
- 5.
- http()
- 6.
- SSL_PROG
- 7.
- dacs.conf(5)
- 8.
- from()
- 9.
- www.dss.ca
- 10.
- LICENSE
07/17/2013 | DACS 1.4.28b |