/usr/share/doc/dacs-examples/man/dacsexpr.1.html

<!-- Copyright (c) 2003-2013 -->
<!-- Distributed Systems Software.  All rights reserved. -->
<!-- See the file LICENSE for redistribution information. -->
<!-- $Id: copyright-html 2625 2013-01-22 18:15:12Z brachman $ -->
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>dacsexpr</title><link rel="stylesheet" type="text/css" href="css/dacsdocs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div id="refentry" class="para16">
<script language="javascript" type="text/javascript" src="css/js/fontselector.js"></script>
<table width="100%"><tr>
<td align="left">
<b>DACSEXPR(1)</b></td>
<td align="center">
<b>DACS Tools and Utilities</b></td>
<td align="right">
<b>DACSEXPR(1)</b></td>
</tr></table>
<div class="refnamediv"><h2>NAME</h2><p>dacsexpr &#8212; <span class="command"><strong>DACS</strong></span> expression language shell and interpreter</p></div><div class="refsynopsisdiv"><h2>SYNOPSIS</h2><div class="cmdsynopsis"><p><code class="command">dacsexpr</code>  [<code class="option">-x</code>] [<em class="replaceable"><code><a class="ulink" href="dacs.1.html#dacsoptions" target="_top">dacsoptions</a></code></em>] [<code class="option">-dl</code>] [<code class="option">-e</code> <em class="replaceable"><code>expr</code></em>] [<code class="option">-n</code>] [<code class="option">-p</code>] [<code class="option">-s</code>] [ <code class="option">-h</code>  |   <code class="option">-help</code> ] [<code class="option">-test</code>]<br> [<code class="option">--</code>] [<em class="replaceable"><code>filename</code></em>] [<em class="replaceable"><code>script-arg</code></em>...]</p></div></div><div class="refsect1"><a name="idm44"></a><h2>DESCRIPTION</h2><p>This program is part of the <span class="command"><strong>DACS</strong></span> suite.</p><p>The <span class="command"><strong>dacsexpr</strong></span> utility
evaluates <span class="command"><strong>DACS</strong></span> expressions
(see <a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>).
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 <span class="command"><strong>DACS</strong></span>.
</p><p>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 <code class="option">-q</code> flag is given
(one of the
<a class="ulink" href="dacs.1.html#dacsoptions" target="_top"><span class="emphasis"><em>dacsoptions</em></span></a>),
nothing is printed, expression evaluation errors are suppressed,
and the program terminates with an appropriate
<a class="ulink" href="#diagnostics" target="_top">exit status</a>;
otherwise the result is written to the standard output.
If neither a <code class="option">-q</code> flag is given nor any flag that controls the
logging level, then the logging level is set to <code class="literal">warn</code>
overriding any configuration file logging level directive; this behaviour
is usually convenient.
</p><p>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 <strong class="userinput"><code>help</code></strong> for assistance.
If the
<a class="ulink" href="http://www.freebsd.org/cgi/man.cgi?query=readline&amp;apropos=0&amp;sektion=3&amp;manpath=FreeBSD+10.1-RELEASE&amp;format=html" target="_top">readline(3)</a>
functionality was configured
when the program was built, command line editing and history are available
in interactive mode.
</p><p>A script can be executed through the
system's "<code class="literal">#!</code>" mechanism:
</p><pre class="screen">
#!/usr/local/dacs/bin/dacsexpr

printf("%s\n", "Hello, world.")
</pre><p>
Such programs always use the script file as input, therefore no
expression or other file can be specified on the "<code class="literal">#!</code>" line.
</p><p>
Command line arguments can be passed to a script.
If <code class="filename">dig-it</code> contains:
</p><pre class="screen">
#!/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}));
</pre><p>
then running the script produces:
</p><pre class="screen">
% ./dig-it sha3-224 mymsg
88fdaa49d0371a79efa2d6e8a55d27d62cd39ad393309d9a18665763
</pre><p>
</p><p>The <code class="varname">Env</code> namespace is initialized
from the program's environment.
For example, if the value of the environment variable <code class="envar">LOGNAME</code>
is <code class="literal">bobo</code>, then <code class="varname">${Env::LOGNAME}</code> will be
instantiated with that value.
Syntactically invalid variable names are silently ignored.
</p><p>An empty <code class="varname">Expr</code> namespace is created.
In interactive use, the prompt string can be changed by assigning
a string to <code class="varname">${Expr::prompt}</code> and the continuation
prompt can be changed by setting
<code class="varname">${Expr::prompt2}</code>.
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note1"></a>Note</h3><p>Configuration directives and the <code class="varname">Conf</code> variable
namespace are available only if a configuration file is processed
(e.g., by giving the <code class="option">-uj</code> command line flag).
This is relevant, for example, if the
<a class="ulink" href="dacs.exprs.5.html#http" target="_top">http()</a> function is called using
the <code class="literal">https</code> scheme because proper operation will require
the <a class="ulink" href="dacs.conf.5.html#SSL_PROG" target="_top">SSL_PROG</a> directive to
be configured.
See <a class="ulink" href="dacs.conf.5.html" target="_top">dacs.conf(5)</a>.
</p></div></div><div class="refsect1"><a name="idm88"></a><h2>OPTIONS</h2><p>If an expression or file has not already been specified,
a filename may appear as the last argument.
If <em class="replaceable"><code>filename</code></em> is "<code class="literal">-</code>",
the standard input is read.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-dl</code></span></dt><dd><p>Print debugging information to <span class="symbol">stderr</span>.
</p></dd><dt><span class="term"><code class="option">-e</code> <em class="replaceable"><code>expr</code></em></span></dt><dd><p>The given expression is evaluated.
</p></dd><dt><span class="term"><code class="option">-h</code><br></span><span class="term"><code class="option">-help</code></span></dt><dd><p>Display a help message and exit.
</p></dd><dt><span class="term"><code class="option">-n</code></span></dt><dd><p>Do not evaluate any expressions, only check for
syntax errors.
</p></dd><dt><span class="term"><code class="option">-p</code></span></dt><dd><p>Print the final result to the standard output,
unless it has been suppressed by <code class="option">-q</code> or <code class="option">-n</code>.
Without this flag, the result would have to be output by the program.
</p></dd><dt><span class="term"><code class="literal">-s</code></span></dt><dd><p>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.
</p></dd><dt><span class="term"><code class="option">-test</code></span></dt><dd><p>The input is a test case:
</p><pre class="screen">
#!/usr/local/dacs/bin/dacsexpr -test
// expect-exact:17
${x} = 17;
</pre><p>
A test case consists of options followed by an expression.
There can be zero or more options, one per line, embedded within
a <code class="literal">//</code> style comment:
</p><pre class="screen">
{ whitespace* "//" whitespace* <em class="replaceable"><code>option-name</code></em> ":" <em class="replaceable"><code>option-value</code></em> end-of-line }*
</pre><p>
No whitespace is allowed before or after the "<code class="literal">:</code>".
As a special case, lines having the following format are ignored:
</p><pre class="screen">
whitespace* "///" .* end-of-line
</pre><p>
</p><p>The first non-option line terminates the options and is the first line
of the expression to be evaluated.
</p><p>Here is an example:
</p><pre class="screen">
/// Test bitwise shifts
// expect-exact:1024
1 &lt;&lt; 10
</pre><p>
</p><p>An option controls how the test is to be performed and gives the
expected result:
 </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">expect:</code><em class="replaceable"><code>regex</code></em><br></span><span class="term"><code class="literal">expect-regex:</code><em class="replaceable"><code>regex</code></em></span></dt><dd><p>The result string must match <em class="replaceable"><code>regex</code></em>.
 These two option names are equivalent.
 </p></dd><dt><span class="term"><code class="literal">expect-identical:</code><em class="replaceable"><code>string</code></em></span></dt><dd><p>The result string must match <em class="replaceable"><code>string</code></em>
  exactly.
 </p></dd><dt><span class="term"><code class="literal">expect-exact:</code><em class="replaceable"><code>string</code></em></span></dt><dd><p>The result string must match <em class="replaceable"><code>string</code></em>
  exactly, except that C-style character constants (preceded by a backslash)
  in <em class="replaceable"><code>string</code></em> are interpolated.
 </p></dd><dt><span class="term"><code class="literal">expect-code:</code><em class="replaceable"><code>code</code></em></span></dt><dd><p>The result code must match <em class="replaceable"><code>code</code></em>,
 which is 0 if the result is <code class="constant">True</code>, 1 if the result
is <code class="constant">False</code>, and 2 if an error occurs.
If this option is not given, a default code of 0 is assumed.
 </p></dd><dt><span class="term"><code class="literal">expect-type:</code><em class="replaceable"><code>type</code></em></span></dt><dd><p>The type of the result must match
  <em class="replaceable"><code>type</code></em>, which can be
  <code class="literal">integer</code>, <code class="literal">real</code>,
 <code class="literal">string</code>,  <code class="literal">bstring</code>,
<code class="literal">literal</code>, or <code class="literal">undef</code>.
 </p></dd><dt><span class="term"><code class="literal">expect-flags:</code><em class="replaceable"><code>flags</code></em></span></dt><dd><p>Currently, the only recognized values for
 <em class="replaceable"><code>flags</code></em> are
 <code class="literal">rw_namespaces</code> and <code class="literal">ro_namespaces</code>.
The former allows the test to create or modify variables in the
<code class="varname">DACS</code>, <code class="varname">Args</code>, or <code class="varname">Env</code>
namespace; by default, these namespaces are read-only.
This might be useful when testing
<a class="ulink" href="dacs.exprs.5.html#from" target="_top">from()</a>, for instance,
because it allows the test to set a value for
<code class="varname">${DACS::REMOTE_ADDR}</code>.
The default behaviour can be explicitly selected by specifying
<code class="literal">ro_namespaces</code>.
 </p></dd><dt><span class="term"><code class="literal">show-result:{yes | no}</code></span></dt><dd><p>The result is printed to the standard output only if
  the option value is <code class="literal">yes</code>.
 </p></dd></dl></div><p>
</p><p>If the test fails, a descriptive message is printed to the standard
error.
The program's exit status will be <code class="literal">0</code> if the test was
successful, <code class="literal">1</code> otherwise.
</p><p>This example should succeed without displaying the result:
</p><pre class="screen">
// expect-exact:2
// expect-type:integer
/// show-result:yes
1 + 1
</pre><p>
</p><div class="note" style="margin-left: 0.125in; margin-right: 0.125in;"><h3 class="title"><a name="note2"></a>Note</h3><p>The <span class="command"><strong>DACS</strong></span>
distribution includes a set of test cases
in the <code class="filename">src/tests</code> directory that can be run for
regression testing
(do "<code class="literal">make tests</code>" from the
<code class="filename">src</code> directory).
Some of the functions provided by
<a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a> are also used internally
by <span class="command"><strong>DACS</strong></span>, so it is critical that all tests are successful
even for functions that are not used from the user level.
</p></div></dd><dt><span class="term"><code class="literal">-x</code></span></dt><dd><p>If this is the very first flag it indicates that
<span class="command"><strong>dacsexpr</strong></span> is being executed as a script via the
system's "<code class="literal">#!</code>" mechanism.
This might be useful if the program's heuristic for determining this
is incorrect.
The last argument must be a filename.
</p></dd><dt><span class="term"><code class="literal">--</code></span></dt><dd><p>This argument explicitly marks the last flag argument.
A filename argument might follow.
</p></dd></dl></div></div><div class="refsect1"><a name="idm240"></a><h2>EXAMPLES</h2><p>The following command evaluates the expression argument
(note that it is a single argument to the command) and outputs the
result to <span class="symbol">stdout</span>:
</p><pre class="programlisting">
% 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 &lt;&lt;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
</pre><p>
</p></div><div class="refsect1"><a name="diagnostics"></a><h2>DIAGNOSTICS</h2><p>If an error occurs, a message may be written to
<span class="symbol">stderr</span>, depending on the logging level.
In general, the program exits <code class="literal">0</code> if and only if
everything was fine.
If a command line expression is evaluated, the program exits
<code class="literal">0</code> if the expression evaluates to <code class="constant">True</code>,
<code class="literal">1</code> if it evaluates to <code class="constant">False</code>,
and <code class="literal">2</code> if an error occurs.
If an explicit call to <code class="function">exit()</code> is made and no
true error condition occurred, then the program will exit with the
argument value.
</p></div><div class="refsect1"><a name="idm256"></a><h2>SEE ALSO</h2><p><a class="ulink" href="dacs.exprs.5.html" target="_top">dacs.exprs(5)</a>
</p></div><div class="refsect1"><a name="idm260"></a><h2>BUGS</h2><p>New and little-used features should be used with care.
This advice applies to all software.
</p></div><div class="refsect1"><a name="idm263"></a><h2>AUTHOR</h2><p>Distributed Systems Software
(<a class="ulink" href="http://www.dss.ca" target="_top">www.dss.ca</a>)
</p></div><div class="refsect1"><a name="idm267"></a><h2>COPYING</h2><p>Copyright  2003-2016 Distributed Systems Software.
See the
<a class="ulink" href="../misc/LICENSE" target="_top"><code class="filename">LICENSE</code></a>
file that accompanies the distribution
for licensing information.
</p></div>
<!-- Generated from   $Id: dacsexpr.1.xml 2903 2016-07-05 14:49:44Z brachman $ -->
<table width="100%"><tr>
<td align="left">
<b>DACS Version 1.4.38a</b></td>
<td align="center">
<b> 5-Feb-2018</b></td>
<td align="right">
<b>DACSEXPR(1)</b></td>
</tr></table>
<hr><p>
<!-- Begin font size selector -->
<table width="100%"><tr><td align="left">
<span class="set_font"><a href="index.html" title="Table of Contents">Table of Contents</a></span></td>
<td align="center"><span class="logo"><a href="http://www.dss.ca"><img src="/css/images/dss-long-14y.png" title="Distributed Systems Software, Inc."></a></span></td>
<td width="5%" align="right">
<div class="fontsize_label" title="Font size selector">Font:</div>
</td>
<td width="10%" align="left">
<!-- NB: must set both left margin and padding to work in all browsers-->
<!-- The onFocus code eliminates annoying post-click decoration -->
<ul id="fontsizecontainer" class="size02">
 <li><a href="javascript:setFont('0');" onFocus="if(this.blur)this.blur()" title="Smallest text size [0]"><span>Z</span></a></li>
 <li><a href="javascript:setFont('1');" onFocus="if(this.blur)this.blur()" title="Medium text size [1]"><span>Z</span></a></li>
 <li><a href="JavaScript:setFont('2');" onFocus="if(this.blur)this.blur()" title="Large text size [2]"><span>Z</span></a></li>
 <li><a href="JavaScript:setFont('3');" onFocus="if(this.blur)this.blur()" title="Largest text size [3]"><span>Z</span></a></li>
</ul>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('-');" onFocus="if(this.blur)this.blur()" title="Decrease current font size">&#8722;&#8722;</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFontConfig();" onFocus="if(this.blur)this.blur()" title="Remember current font size">Set</a></span>
</td>
<td width="3%" align="center">
<span class="set_font"><a href="javascript:setFont('+');" onFocus="if(this.blur)this.blur()" title="Increase current font size">++</a></span>
</td></tr></table>
<!-- End font size selector -->
<script language="javascript" type="text/javascript">
doFontConfig();</script>
</p><small><p><b>  $Id: dacsexpr.1.xml 2903 2016-07-05 14:49:44Z brachman $</b></p></small>
</div></body></html>
dacs-examples 1.4.38a-2build1 / usr / share / doc / dacs-examples / man / dacsexpr.1.html
