<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>Module pibfi_options</title>
</head>
<body bgcolor="white">
<h1>Module pibfi_options</h1>
<ul><li>
<a href="#index">Function index</a></li><li>
<a href="#exported">Exported functions</a></li><li>
<a href="#internal">Documented Internal Functions</a></li></ul>
<h2>Description</h2>
Options parser for <code>pibfi</code>.
<h3>Synopsis</h3>
<p>This module implements collecting options
from the command line.</p>
<p>When invoking <code>pibfi</code> from the command line, the
following syntax can be used:</p>
<ul><code>erl -noshell <i>options</i> -run pibfi run <i>filename</i></code></ul>
<p>The following options are recognized.</p>
<ul>
<li>Options pertaining to the parser:
<ul>
<li><code>-dontstrip <i>s</i></code>, where <i>s</i> is a string of
characters, default null (empty), specifies the set of characters
(beyond the 8 basic Brainf*ck instructions)
which
will not be stripped from the parsed source prior to optimization.
Note that if this option if given without an argument, it is assumed
to be the set of all applicable characters - in other words, nothing
at all will be stripped.</li>
<li><code>-optimize <i>n</i></code>, where <i>n</i> is an integer,
default 1, sets the optimization level of the parser.
At optimization level 0, no optimization occurs.
At optimization level 1, run-length encoding is performed on the
instructions. Further optimization levels may be defined in the
future. Note that if this option if given without an argument,
it is assumed to be asking for the most thorough yet quickly
available optimization.</li>
<li><code>-statuscmd <i>c</i></code>, where <i>c</i> may be
any single-character string of the term <code>undefined</code>,
default "#" (octalthorpe), specifies
which symbol, when encountered, is treated
as a debugging instruction which displays a status report.</li>
<li><code>-heredoc <i>c</i></code>, where <i>c</i> may be
a single-character string or the term <code>undefined</code>,
default <code>undefined</code>, specifies which symbol when encountered,
is treated as the marker that signifies that input is embedded in
the program source code following it. This input will be stripped
from the source (even if it contains valid Brainf*ck instructions)
and will be made available to <code>-infile heredoc</code> (see
below.) Note that if this option is given with no argument,
"!" (exclamation point) is assumed.</li>
</ul>
</li>
<li>Options pertaining to the Brainf*ck tape:
<ul>
<li><code>-tapemodule <i>m</i></code>, where <i>n</i> is the name of
an Erlang module conforming to the <code>pibfi_tape</code> behaviour,
defaulting to whatever <code>pibfi</code> determines would be optimal
for the given sourcecode, (currently always <code>pibfi_tape_ets</code>),
names the module which implements the backing for the simulated tape.</li>
<li><code>-maxcell <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default <code>infinity</code>, sets the
highest value that can be placed into a cell on the tape.</li>
<li><code>-mincell <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default 0, sets the
lowest value that can be placed into a cell on the tape.
(Note that <code>infinity</code> actually represents negative infinity
here.)</li>
<li><code>-wrapcell <i>b</i></code>, where <i>b</i> is a boolean
(<code>true</code> or <code>false</code>), default <code>false</code>,
determines what happens when either limit of any cell in the tape is
exceeded. When <code>-wrapcell</code> is <code>true</code>, the limits
will be taken as modulus boundaries, and the value will 'wrap around'
to the opposite limit. When <code>-wrapcell</code> is <code>false</code>,
an exception will be generated. Note that if <i>b</i> is omitted
after <code>-wrapcell</code>, <code>true</code> is assumed.
Also note that <code>-wrapcell true</code> is not compatible with
either <code>-maxcell infinity</code> or <code>-mincell infinity</code>
(for what should be obvious reasons.)</li>
<li><code>-maxtape <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default <code>infinity</code>, sets the
rightmost position to which the tape head can move. Note that the initial
position of the tape head is considered position 0.</li>
<li><code>-mintape <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default 0, sets the
leftmost position to which the tape head can move.
(Note that <code>infinity</code> actually represents negative infinity
here.)</li>
<li><code>-wraptape <i>b</i></code>, where <i>b</i> is a boolean,
default <code>false</code>, determines what happens when either limit
of the tape head is exceeded. With <code>-wraptape true</code>,
the limits will be taken as modulus boundaries,
and the position of the tape head will 'wrap around' to the
opposite limit. With <code>-wraptape false</code>,
an exception will be generated when this happens.
Note that if <i>b</i> is omitted
after <code>-wraptape</code>, <code>true</code> is assumed. Also note
that <code>-wraptape true</code> is not compatible with either
<code>-maxtape infinity</code> or <code>-mintape infinity</code>.</li>
</ul>
</li>
<li>Options pertaining to input and output:
<ul>
<li><code>-infile <i>s</i></code>, where <i>s</i> is a filename or
one of the terms <code>tty</code> or <code>heredoc</code>,
default <code>tty</code>, sets the
source of the input to the Brainf*ck program.
<code>tty</code> indicates an interactive terminal session with
"standard input".
<code>heredoc</code> indicates input will come from the
"here-doc" portion of the program source code (note that the
<code>-heredoc</code> option must also be given to parse the
source code.)
Using this option is preferred
over redirecting standard I/O with the shell, as it is a hint to the
interpreter that the program is not being run interactively.</li>
<li><code>-outfile <i>s</i></code>, where <i>s</i> is a filename or
the term <code>tty</code>, default <code>tty</code>, sets the
destination of the output of the Brainf*ck program. This is preferred
to redirecting standard I/O with the shell, as it is a hint to the
interpreter that the program is not being run interactively.</li>
<li><code>-maxout <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default <code>infinity</code>, sets the
maximum character value which can be output.</li>
<li><code>-minout <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default 0, sets the minimum character
value which can be output.
(Note that <code>infinity</code> actually represents negative infinity
here.)</li>
<li><code>-wrapout <i>b</i></code>, where <i>b</i> is a boolean,
default <code>false</code>, determines what happens when either limit
of character output is exceeded. With <code>-wrapout true</code>,
the limits will be taken as modulus boundaries,
and the actual character output will be computed by 'wrapping around'
the rquested value to the opposite limit.
With <code>-wrapout false</code>,
an exception will be generated. Note that if <i>b</i> is omitted
after <code>-wrapout</code>, <code>true</code> is assumed. Also note
that <code>-wrapout true</code> is not compatible with either
<code>-maxout infinity</code> or <code>-minout infinity</code>.</li>
<li><code>-maxin <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default <code>infinity</code>, sets the
maximum character value which can be input.</li>
<li><code>-minin <i>n</i></code>, where <i>n</i> is any integer or the
term <code>infinity</code>, default 0, sets the minimum character
value which can be input.
(Note that <code>infinity</code> actually represents negative infinity
here.)</li>
<li><code>-wrapin <i>b</i></code>, where <i>b</i> is a boolean,
default <code>false</code>, determines what happens when either limit
of character input is exceeded. With <code>-wrapin true</code>,
the limits will be taken as modulus boundaries,
and the actual character input will be computed by 'wrapping around'
the rquested value to the opposite limit.
With <code>-wrapin false</code>,
an exception will be generated. Note that if <i>b</i> is omitted
after <code>-wrapin</code>, <code>true</code> is assumed. Also note
that <code>-wrapin true</code> is not compatible with either
<code>-maxin infinity</code> or <code>-minin infinity</code>.</li>
<li><code>-xlatout <i>s</i></code>, where <i>s</i> is string
in the form given below,
default value <tt>#10=#nl</tt>, specifies a mapping between
characters the Brainf*ck program sees itself as sending to output,
and the characters that the operating system actually receives.
The syntax for the mapping specification is described by this mini-grammar:
<ul><li>
<tt><i>string</i> "=" <i>string</i> ["," <i>string</i> "=" <i>string</i> ]</tt>
</li></ul>
Control and other characters can be embedded in this string by
giving their ASCII values in decimal preceded by a <tt>#</tt>
symbol. A single <tt>#</tt> symbol can be represented by the
sequence <tt>#35</tt>. A single <tt>=</tt> symbol can be
represented by the sequence <tt>#61</tt>.
A single <tt>,</tt> symbol can be
represented by the sequence <tt>#44</tt>.
The current operating system newline
sequence can be represented by <tt>#nl</tt>.
Note that whitespace is not allowed in this grammar,
and must be represented by <tt>#32</tt>, etc.
Note that if the <code>-xlatout</code> option is present
with no argument, this means that there should be <i>no</i> translation
mapping between Brainf*ck output and operating system output.</li>
<li><code>-xlatin <i>s</i></code>, where <i>s</i> is a string
in the form given above,
default value <tt>#nl=#10</tt>, specifies a complementary mapping between
characters on the operating system's input and
the Brainf*ck program's input.
Note that if the <code>-xlatin</code> option is present
with no argument, this means that there should be no translation
mapping of input.</li>
<li><code>-eof <i>i</i></code>, where <i>i</i> is any integer
or one of the terms <code>halt</code>, <code>stop</code>,
or <code>nop</code>, default 0,
determines the single ASCII character that will be given repeatedly to
the Brainf*ck program during execution of the <code>,</code> instruction
at and after the end of input is encountered.
If <code>halt</code> is given for <code>eof</code>, the Brainf*ck
program will be halted with an error
if it attempts to read past the end of user input.
If <code>stop</code> is given for <code>eof</code>, the Brainf*ck
program will be terminated normally if it attempts to read past
the end of user input.
If <code>nop</code> is given for <code>eof</code>, the Brainf*ck
program will act as if nothing at all happened if it attempts
to read past the end of user input (the tape will not be altered in
any way.)</li>
</ul>
</li>
<li>Debugging and other options:</li>
<ul>
<li><code>-quiet</code>, if given, suppresses all startup
output generated by the interpreter. It does not suppress
status reports.</li>
<li><code>-autopsy</code>, if given, causes the interpreter to
issue a status report after the program terminates normally.</li>
<li><code>-statusevery <i>n</i></code>, where <i>n</i> is an
integer specifying a duration or the term <code>undefined</code>,
default <code>undefined</code>, tells <code>pibfi</code>
to generate periodic status reports at the given interval,
if it is not <code>undefined</code>. If the duration is given
as a plain integer, units of milliseconds are assumed. The
duration may also be given as an integer followed immediately
by <code>s</code>, <code>m</code>, or <code>h</code>, in which
case the units of measurement will be taken to be seconds,
minutes, or hours, respectively.</li>
</ul>
</ul>
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1"><tr><th colspan="2" align="left">Exported Functions</th></tr>
<tr><td><a href="#get_flag-1">get_flag/1</a></td><td>Gets a switch from the command line.</td></tr>
<tr><td><a href="#get_option-3">get_option/3</a></td><td>Gets an option from a list of (already parsed) option tuples.</td></tr>
<tr><td><a href="#get_opts-1">get_opts/1</a></td><td>Gets a set of options from the command line.</td></tr>
<tr><th colspan="2" align="left">Internal Documented Functions</th></tr>
<tr><td><a href="#convert-2">convert/2</a></td><td>Converts an option value specified on the command line to a
term that <code>pibfi</code> can work with internally.</td></tr>
<tr><td><a href="#missing-1">missing/1</a></td><td>Gets the default value for an option specified with no value
on the command line.</td></tr>
<tr><td><a href="#unescape-1">unescape/1</a></td><td>Transforms escape codes in a string into embedded characters.</td></tr>
</table>
<h2><a name="exported">Exported Functions</a></h2>
<h3><a name="get_flag-1">get_flag/1</a></h3>
<p><code>get_flag(Switch::atom()) -> true | false</code></p>
<p>Gets a switch from the command line.</p>
<h3><a name="get_option-3">get_option/3</a></h3>
<p><code>get_option(Options::[{atom(), term()}], Option::atom(), Default::term()) -> term()</code></p>
<p>Gets an option from a list of (already parsed) option tuples.</p>
<h3><a name="get_opts-1">get_opts/1</a></h3>
<p><code>get_opts([atom()]) -> [{atom(), term()}]</code></p>
<p>Gets a set of options from the command line.</p>
<h2><a name="internal">Documented Internal Functions</a></h2>
<h3><a name="convert-2">convert/2</a></h3>
<p><code>convert(atom(), string()) -> term()</code></p>
<p>Converts an option value specified on the command line to a
term that <code>pibfi</code> can work with internally.</p>
<h3><a name="missing-1">missing/1</a></h3>
<p><code>missing(atom()) -> term()</code></p>
<p>Gets the default value for an option specified with no value
on the command line.</p>
<h3><a name="unescape-1">unescape/1</a></h3>
<p><code>unescape(string()) -> string()</code></p>
<p>Transforms escape codes in a string into embedded characters.
The escape code <tt>#<i>i</i></tt> where <tt><i>i</i></tt> is a
decimal integer of from one to three digits is converted into an
ASCII character of that value.</p></body>
</html>