mthl
/
texinfo


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904
							<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml" xmlns:epub="http://www.idpf.org/2007/ops" xmlns:m="http://www.w3.org/1998/Math/MathML" xmlns:pls="http://www.w3.org/2005/01/pronunciation-lexicon" xmlns:ssml="http://www.w3.org/2001/10/synthesis" xmlns:svg="http://www.w3.org/2000/svg">
  <head>
    <title>Command-line arguments</title>
    <link rel="stylesheet" type="text/css" href="docbook-epub.css"/>
    <link rel="stylesheet" type="text/css" href="kawa.css"/>
    <script src="kawa-ebook.js" type="text/javascript"/>
    <meta name="generator" content="DocBook XSL-NS Stylesheets V1.79.1"/>
    <link rel="prev" href="Running.xhtml" title="How to start up and run Kawa"/>
    <link rel="next" href="Scripts.xhtml" title="Running Command Scripts"/>
  </head>
  <body>
    <header/>
    <section class="sect1" title="Command-line arguments" epub:type="subchapter" id="Options">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both">Command-line arguments</h2>
          </div>
        </div>
      </div>
      <a id="idm139667880310992" class="indexterm"/>
      <p>You can pass various flags to Kawa, for example:
</p>
      <pre class="screen">kawa -e '(display (+ 12 4))(newline)'
</pre>
      <p>or:
</p>
      <pre class="screen">java kawa.repl -e '(display (+ 12 4))(newline)'
</pre>
      <p>Either causes Kawa to print ‘<code class="literal">16</code>’, and then exit.
</p>
      <p>At startup, Kawa executes an init file from the user’s home
directory.
The init file is named <code class="literal">.kawarc.scm</code> on Unix-like systems
(those for which the file separator is <code class="literal">'/'</code>),
and <code class="literal">kawarc.scm</code> on other systems.
This is done before the read-eval-print loop
or before the first <code class="literal">-f</code> or <code class="literal">-c</code> argument.  (It is not run
for a <code class="literal">-e</code> command, to allow you to set options to override
the defaults.)
</p>
      <section class="sect2" title="Argument processing" epub:type="division" id="idm139667880304720">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Argument processing</h3>
            </div>
          </div>
        </div>
        <p>Kawa processes the command-line arguments in order.
Options (which either start with ‘<code class="literal">-</code>’ or contain a ‘<code class="literal">=</code>’)
may “use up” one or more command arguments.
Some of the options (‘<code class="literal">-c</code>’, ‘<code class="literal">-e</code>’, ‘<code class="literal">-f</code>’, ‘<code class="literal">-s</code>’,
‘<code class="literal">-C</code>’, <code class="literal">-w</code>, ‘<code class="literal">--</code>’, <code class="literal">--browse-manual</code>)
are <em class="firstterm">action options</em>; others set various properties.
</p>
        <p>When all the command-line arguments have been “used up”
and if no action options have been seen,
then Kawa enters an interactive read-eval-print loop.
(If an action option has been seen, we’re done.)
</p>
        <p>If the next command-line argument is not an option
(does not start with ‘<code class="literal">-</code>’ nor contains a ‘<code class="literal">=</code>’)
then we’re done if we’ve seen an action option (and the
last action option wasn’t preceded by <code class="literal">--with-arg-count</code>).
(Presumably any remaining arguments were command-line-arguments
used by the action option.)
</p>
        <p>Otherwise, the first remaining argument names either a
file that is read and evaluated, or a compiled class.
In the former case, the whole file is read and compiled as a module
before being loaded (unlike the <code class="literal">-f</code> flag which reads and
evaluates the file command by command.)
If the argument is the fully-qualified name of a class,
then the class is loaded, an instance allocated,
and its <code class="literal">run</code> method invoked.  If the class was compiled from
a Kawa Scheme module, then invoking <code class="literal">run</code> has the
effect of evaluating the module body.
The <code class="literal">command-line-arguments</code> vector is set to any remaining
arguments after the file/class name.
(This can be overridden with the <code class="literal">--with-arg-count</code> option.
Command-line processing continues if there are any further arguments.)
</p>
      </section>
      <section class="sect2" title="General options" epub:type="division" id="idm139667880292032">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">General options</h3>
            </div>
          </div>
        </div>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">-e <em class="replaceable"><code>expr</code></em></code>
</dt>
            <dd>
              <p>Kawa evaluates <em class="replaceable"><code>expr</code></em>, which contains one or more Scheme expressions.
Does not cause the <code class="literal">~/.kawarc.scm</code> init file to be run.
</p>
            </dd>
            <dt class="term"><code class="literal">-c <em class="replaceable"><code>expr</code></em></code>
</dt>
            <dd>
              <p>Same as ‘<code class="literal">-e <em class="replaceable"><code>expr</code></em></code>’, except that it
does cause the <code class="literal">~/.kawarc.scm</code> init file to be run.
</p>
            </dd>
            <dt class="term"><code class="literal">-f <em class="replaceable"><code>filename-or-url</code></em></code>
</dt>
            <dd>
              <p>Kawa reads and evaluates expressions from the file named
by <em class="replaceable"><code>filename-or-url</code></em>.  If the latter is ‘<code class="literal">-</code>’,
standard input is read (with no prompting).  Otherwise,
it is equivalent to evaluating ‘<code class="literal">(load "<em class="replaceable"><code>filename-or-url</code></em>")</code>’.
The <em class="replaceable"><code>filename-or-url</code></em> is interpreted as a URL
if it is absolute - it starts with a "URI scheme" like <code class="literal">http:</code>.
</p>
            </dd>
            <dt class="term"><code class="literal">-s</code>
</dt>
            <dt class="term"><code class="literal">--</code>
</dt>
            <dd>
              <p>The remaining arguments (if any) are passed to ‘<code class="literal">command-line-arguments</code>’
and (the <code class="literal">cdr</code> of) <code class="literal">(command-line</code>),
and an interactive read-eval-print loop is started.
This uses the same "console" as where you started up Kawa;
use ‘<code class="literal">-w</code>’ to get a new window.
</p>
            </dd>
            <dt class="term"><code class="literal">--script <em class="replaceable"><code>filename-or-url</code></em></code>
</dt>
            <dt class="term"><code class="literal">--script<em class="replaceable"><code>N</code></em> <em class="replaceable"><code>filename-or-url</code></em></code>
</dt>
            <dd>
              <p>The global variable ‘<code class="literal">command-line-arguments</code>’ is set to the remaining
arguments (if any).
Kawa reads and evaluates expressions from the file named
by <em class="replaceable"><code>filename-or-url</code></em>.
If <code class="literal">script</code> is followed by an integer <em class="replaceable"><code>N</code></em>,
then <em class="replaceable"><code>N</code></em> lines are skipped first.
</p>
              <p>Skipping some initial lines is useful if you want to have a non-Kawa
preamble before the actual Kawa code.
One use for this is for Kawa shell scripts (see <a class="link" href="Scripts.xhtml" title="Running Command Scripts">Scripts</a>).
</p>
            </dd>
            <dt class="term"><code class="literal">-w</code>
</dt>
            <dt class="term"><code class="literal">-w<em class="replaceable"><code>sub-option</code></em></code>
</dt>
            <dd>
              <p>Creates a new top-level window, and runs an interactive read-eval-print
in the new window.  See <a class="link" href="REPL-Console.xhtml#New-Window">New-Window</a>.
Same as <code class="literal">-e (scheme-window #t)</code>.
You can specify multiple ‘<code class="literal">-w</code>’ options, and also use ‘<code class="literal">-s</code>’.
</p>
            </dd>
            <dt class="term"><code class="literal">--help</code>
</dt>
            <dd>
              <p>Prints out some help.
</p>
            </dd>
            <dt class="term"><code class="literal">--version</code>
</dt>
            <dd>
              <p>Prints out the Kawa version number, and then exits.
</p>
              <p>If Kawa was built with a <code class="literal">.git</code> repository present,
also prints the result of <code class="literal">git describe</code>.
<span id="browse-manual-option"/></p>
            </dd>
            <dt class="term"><code class="literal">--browse-manual</code>
</dt>
            <dt class="term"><code class="literal">--browse-manual=<em class="replaceable"><code>command</code></em></code>
</dt>
            <dd>
              <p>Browse a local copy of the documentation (this manual).
</p>
              <p>This creates a mini web-server that reads
from <code class="literal">doc/kawa-manual.epub</code>, which is
included in the binary distributions, but not built by default from source.
</p>
              <p>If no <em class="replaceable"><code>command</code></em> is specified, creates a new window or tab
in your default web browser.
If <em class="replaceable"><code>command</code></em> is a string containing <code class="literal">%U</code>,
then Kawa replaces <code class="literal">%U</code> with a URL that references itself,
and then executes the resulting command.
If <em class="replaceable"><code>command</code></em> does not contain <code class="literal">%U</code>, then
<em class="replaceable"><code>command</code></em> becomes <em class="replaceable"><code>command</code></em><code class="literal">" %U"</code>.
For example to use the Firefox browser to browse the manual do either of:
</p>
              <pre class="screen">kawa --browse-manual=firefox
kawa --browse-manual="firefox %U"
</pre>
            </dd>
            <dt class="term"><code class="literal">--server <em class="replaceable"><code>portnum</code></em></code>
</dt>
            <dd>
              <p>Start a server listening from connections on the specified <em class="replaceable"><code>portnum</code></em>.
Each connection using the Telnet protocol causes a new read-eval-print-loop
to start.  This option allows you to connect using any
Telnet client program to a remote "Kawa server".
</p>
            </dd>
            <dt class="term"><code class="literal">--with-arg-count=<em class="replaceable"><code>argc</code></em></code>
</dt>
            <dd>
              <p>This option is used before an action option (such as <code class="literal">-f</code>).
The <em class="replaceable"><code>argc</code></em> arguments after the action become the
value of the <code class="literal">command-line-arguments</code> during the action.
When the action is finished, command-line-processing resumes
after skipping the <em class="replaceable"><code>argc</code></em> arguments.
</p>
              <p>For example:
</p>
              <pre class="screen">$ kawa -f a.scm -f b.scm x y
</pre>
              <p>When evaluating <code class="literal">a.scm</code> the <code class="literal">command-line-arguments</code>
by default is <span class="emphasis"><em>all</em></span> the remaining arguments: <code class="literal">["-f" "b.scm" "x" "y"]</code>.
Then <code class="literal">b.scm</code> is evaluated with <code class="literal">command-line-arguments</code>
set to <code class="literal">["x" "y"]</code>
</p>
              <pre class="screen">$ kawa --with-arg-count=0 -f a.scm -f b.scm x y
</pre>
              <p>In this case <code class="literal">a.scm</code> is evaluated with <code class="literal">command-line-arguments</code>
set to the empty vector <code class="literal">[]</code>, and then <code class="literal">b.scm</code> is evaluated with <code class="literal">command-line-arguments</code>
set to <code class="literal">["x" "y"]</code>
</p>
              <pre class="screen">$ kawa --with-arg-count=4 -f a.scm -f b.scm x y
</pre>
              <p>In this case <code class="literal">a.scm</code> is evaluated with <code class="literal">command-line-arguments</code>
set to <code class="literal">["-f" "b.scm" "x" "y"]</code>. Since command-line processing
skips the arguments specified by <code class="literal">--with-arg-count=4</code>,
in this case <code class="literal">b.scm</code> is not evaluated.
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Options for language selection" epub:type="division" id="idm139667880239696">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for language selection</h3>
            </div>
          </div>
        </div>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--scheme</code>
</dt>
            <dd>
              <p>Set the default language to Scheme.
(This is the default unless you select another language,
or you name a file with a known extension on the command-line.)
</p>
            </dd>
            <dt class="term"><code class="literal">--r5rs</code>
</dt>
            <dt class="term"><code class="literal">--r6rs</code>
</dt>
            <dt class="term"><code class="literal">--r7rs</code>
</dt>
            <dd>
              <p>Provide better compatibility with the specified Scheme standards.
(This is a work-in-progress.)
For example <code class="literal">--r6rs</code> aims to disable Kawa extensions
that conflict with R6RS.  It does not aim to disable all extensions,
only incompatible extensions.
These extensions disable the colon operator and keyword literals,
as well as the use of initial ‘<code class="literal">@</code>’ as a splicing operator.
The “<code class="literal">l</code>” exponent suffix of a number literal creates a
floating-point double, rather than a <code class="literal">BigInteger</code>.
Selecting <code class="literal">--r5rs</code> makes symbols by default
case-insensitive.
</p>
            </dd>
            <dt class="term"><code class="literal">--elisp</code>
</dt>
            <dt class="term"><code class="literal">--emacs</code>
</dt>
            <dt class="term"><code class="literal">--emacs-lisp</code>
</dt>
            <dd>
              <p>Set the default language to Emacs Lisp.
(The implementation is quite incomplete.)
</p>
            </dd>
            <dt class="term"><code class="literal">--lisp</code>
</dt>
            <dt class="term"><code class="literal">--clisp</code>
</dt>
            <dt class="term"><code class="literal">--clisp</code>
</dt>
            <dt class="term"><code class="literal">--commonlisp</code>
</dt>
            <dt class="term"><code class="literal">--common-lisp</code>
</dt>
            <dd>
              <p>Set the default language to CommonLisp.
(The implementation is <span class="emphasis"><em>very</em></span> incomplete.)
</p>
            </dd>
            <dt class="term"><code class="literal">--krl</code>
</dt>
            <dd>
              <p>Set the default language to KRL.  See <a class="link" href="XML-beyond-Scheme.xhtml#KRL" title="KRL - The Kawa Report Language for generating XML/HTML">KRL</a>.
</p>
            </dd>
            <dt class="term"><code class="literal">--brl</code>
</dt>
            <dd>
              <p>Set the default language to KRL, in BRL-compatibility mode.  See <a class="link" href="XML-beyond-Scheme.xhtml#KRL" title="KRL - The Kawa Report Language for generating XML/HTML">KRL</a>.
</p>
            </dd>
            <dt class="term"><code class="literal">--xquery</code>
</dt>
            <dd>
              <p>Set the default language to the draft XML Query language.
See the <a class="ulink" href="http://www.gnu.org/software/qexo/" target="_top">Kawa-XQuery page</a>
for more information.
</p>
            </dd>
            <dt class="term"><code class="literal">--xslt</code>
</dt>
            <dd>
              <p>Set the default language to XSLT (XML Stylesheet Language Transformations).
(The implementation is <span class="emphasis"><em>very</em></span> incomplete.)
See the <a class="ulink" href="http://www.gnu.org/software/qexo/xslt.html" target="_top">Kawa-XSLT page</a>
for more information.
</p>
            </dd>
            <dt class="term"><code class="literal">--pedantic</code>
</dt>
            <dd>
              <p>Try to follow the approprate language specification to the letter,
even in corner cases, and even if it means giving up some
Kawa convenience features.  This flag so far only affects
the XQuery parser, but that will hopefully change.
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Options for warnings and errors" epub:type="division" id="idm139667880216944">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for warnings and errors</h3>
            </div>
          </div>
        </div>
        <div class="variablelist" epub:type="list">
          <a id="idm139667880215856" class="indexterm"/>
          <a id="idm139667880214656" class="indexterm"/>
          <a id="idm139667880213456" class="indexterm"/>
          <dl class="variablelist">
            <dt class="term"><code class="literal">--warn-undefined-variable</code>
</dt>
            <dd>
              <p>Emit a warning if the code references a variable which is neither in
lexical scope nor in the compile-time dynamic (global) environment.
This is useful for catching typos.
(A <code class="literal">define-variable</code> form can be used to silence warnings.
It declares to the compiler that a variable is to be resolved dynamically.)
This defaults to on;
to turn it off use the <code class="literal">--no-warn-undefined-variable</code> flag.
<a id="idm139667880210224" class="indexterm"/>
</p>
            </dd>
            <dt class="term"><code class="literal">--warn-unknown-member</code>
</dt>
            <dd>
              <p>Emit a warning if the code references a named member (field or method)
for which there is no match in the compile-time type of the receiver.
This defaults to on;
to turn it off use the <code class="literal">--no-warn-unknown-member</code> flag.
<a id="idm139667880207712" class="indexterm"/>
</p>
            </dd>
            <dt class="term"><code class="literal">--warn-invoke-unknown-method</code>
</dt>
            <dd>
              <p>Emit a warning if the <code class="literal">invoke</code> function calls a named method
for which there is no matching method in the compile-time type of the receiver.
This defaults to the value of <code class="literal">--warn-unknown-member</code>,
to turn it off use the <code class="literal">--no-warn-invoke-unknown-method</code> flag.
<a id="idm139667880204304" class="indexterm"/>
</p>
            </dd>
            <dt class="term"><code class="literal">--warn-unused</code>
</dt>
            <dd>
              <p>Emit a warning if a variable is unused or code never executed. This defaults
to on; to turn it off use the <code class="literal">--no-warn-unused</code> flag.
<a id="idm139667880201888" class="indexterm"/>
</p>
            </dd>
            <dt class="term"><code class="literal">--warn-unreachable</code>
</dt>
            <dd>
              <p>Emit a warning if the code can never be executed. This defaults to on;
to turn it off use the <code class="literal">--no-warn-unreachable</code> flag.
<a id="idm139667880199488" class="indexterm"/>
</p>
            </dd>
            <dt class="term"><code class="literal">--warn-void-used</code>
</dt>
            <dd>
              <p>Emit a warning if an expression depends on an expression
that is void (always has zero values), including call to <code class="literal">void</code>
functions and method.  Also warn if an expression depends on a
conditional (<code class="literal">if</code>) that has no “else” clause.
Examples include using the value of <code class="literal">set-car!</code> as
an argument to a function, or to initialize a variable.
This defaults to on;
to turn it off use the <code class="literal">--no-warn-void-used</code> flag.
<a id="idm139667880195456" class="indexterm"/>
</p>
            </dd>
            <dt class="term"><code class="literal">--warn-as-error</code>
</dt>
            <dd>
              <p>Treat a compilation warning as if it were an error and halt compilation.
</p>
            </dd>
          </dl>
        </div>
        <p>An option can be followed by a value, as
in <code class="literal">--warn-invoke-unknown-method=no</code>.
For boolean options, the values <code class="literal">yes</code>, <code class="literal">true</code>, <code class="literal">on</code>, or <code class="literal">1</code>
enable the option, while <code class="literal">no</code>, <code class="literal">false</code>, <code class="literal">off</code>,
or <code class="literal">0</code> disable it.
You can also negate an option by prefixing it with <code class="literal">no-</code>:
The option <code class="literal">--no-warn-unknown-member</code>
is the same as <code class="literal">--warn-unknown-member=no</code>.
</p>
        <p>These options can also be used in the module source, using
<code class="literal">module-compile-options</code> or <code class="literal">with-compile-options</code>.
(In that case they override the options on the command line.)
</p>
      </section>
      <section class="sect2" title="Options for setting variables" epub:type="division" id="idm139667880186288">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for setting variables</h3>
            </div>
          </div>
        </div>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal"><em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></code>
</dt>
            <dd>
              <p>Set the global variable with the specified <em class="replaceable"><code>name</code></em> to the given <em class="replaceable"><code>value</code></em>.
The type of the <em class="replaceable"><code>value</code></em> is currently unspecified; the plan is for it
to be like XQuery’s <em class="firstterm">untyped atomic</em> which can be coerced as needed.
</p>
            </dd>
            <dt class="term"><code class="literal">{<em class="replaceable"><code>namespace-uri</code></em>}<em class="replaceable"><code>local-name</code></em>=<em class="replaceable"><code>value</code></em></code>
</dt>
            <dd>
              <p>Set the global variable with the specified namespace uri and
namespace-local name to the given value.
</p>
            </dd>
          </dl>
        </div>
        <p>These options are processed when invoking the <code class="literal">kawa</code>
application (i.e. the <code class="literal">kawa.repl</code> application).
If you want a Kawa application compiled with <code class="literal">--main</code>
to process these these assignments, call the
<code class="literal">process-command-line-assignments</code> utility function.
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">-D<em class="replaceable"><code>variable-name</code></em>=<em class="replaceable"><code>variable-value</code></em></code>
</dt>
            <dd>
              <p>Sets the JVM property <em class="replaceable"><code>variable-name</code></em> to <em class="replaceable"><code>variable-value</code></em>,
using the <code class="literal">setProperty</code> method of <code class="literal">java.lang.System</code>.
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Options for the REPL console" epub:type="division" id="idm139667880172992">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for the REPL console</h3>
            </div>
          </div>
        </div>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--console</code>
</dt>
            <dt class="term"><code class="literal">--no-console</code>
</dt>
            <dd>
              <p>Usually Kawa can detect when the standard input port is a “console”
or “terminal”, but these are useful for overriding that detection.
The <code class="literal">--console</code> flag is useful when the standard input is a pipe,
but you want to direct Kawa to treat it as an interactive terminal.
The <code class="literal">--no-console</code> flag was useful for older pre-Java-6
implementations that did not have the <code class="literal">java.lang.Console</code> class.
</p>
            </dd>
            <dt class="term"><code class="literal">console:type=</code><em class="replaceable"><code>console-types</code></em>
</dt>
            <dt class="term"><code class="literal">console:use-jline=</code>[<code class="literal">yes</code>|<code class="literal">no</code>]
</dt>
            <dt class="term"><code class="literal">console:jline-mouse=</code>[<code class="literal">yes</code>|<code class="literal">no</code>]
</dt>
            <dd>
              <p>See the <a class="link" href="REPL-Console.xhtml" title="The REPL (read-eval-print-loop) console">REPL Console</a> section.
</p>
            </dd>
            <dt class="term"><code class="literal">console:prompt1=<em class="replaceable"><code>prompt1</code></em></code>
</dt>
            <dt class="term"><code class="literal">console:prompt2=<em class="replaceable"><code>prompt2</code></em></code>
</dt>
            <dd>
              <p>Initialize <a class="link" href="Ports.xhtml#input-prompt1"><code class="literal">input-promp1</code> and <code class="literal">input-prompt2</code></a>, respectively.
</p>
            </dd>
          </dl>
        </div>
        <p>See also the <code class="literal">--output-format</code> flag.
</p>
      </section>
      <section class="sect2" title="Options for controlling output formatting" epub:type="division" id="idm139667880159184">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for controlling output formatting</h3>
            </div>
          </div>
        </div>
        <a id="idm139667880158208" class="indexterm"/>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--output-format <em class="replaceable"><code>format</code></em></code>
</dt>
            <dt class="term"><code class="literal">--format <em class="replaceable"><code>format</code></em></code>
</dt>
            <dd>
              <p>Change the default output format to that specified by <em class="replaceable"><code>format</code></em>.
See <a class="link" href="Named-output-formats.xhtml" title="Named output formats">Named output formats</a> for more information and a list.
</p>
            </dd>
          </dl>
        </div>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">out:base=<em class="replaceable"><code>integer</code></em></code>
</dt>
            <dd>
              <p>The number base (radix) to use by default when printing rational numbers.
Must be an integer between 2 and 36, and the default is of course 10.
For example the option <code class="literal">out:base=16</code> produces hexadecimal output.
Equivalent to setting the <code class="literal">*print-base*</code> variable.
</p>
            </dd>
            <dt class="term"><code class="literal">out:radix=no|yes</code>
</dt>
            <dd>
              <p>If true, prints an indicator of the radix used when printing rational numbers.
The default is <code class="literal">no</code>.
Equivalent to setting the <code class="literal">*print-radix*</code> variable.
</p>
            </dd>
            <dt class="term"><code class="literal">out:doctype-system=<em class="replaceable"><code>system-identifier</code></em></code>
</dt>
            <dd>
              <p>If <code class="literal">out:doctype-system</code> is specified then a <code class="literal">DOCTYPE</code> declaration
is written before writing a top-level XML element, using
the specified <em class="replaceable"><code>system-identifier</code></em>.
</p>
            </dd>
            <dt class="term"><code class="literal">out:doctype-public=<em class="replaceable"><code>public-identifier</code></em></code>
</dt>
            <dd>
              <p>Ignored unless  <code class="literal">out:doctype-system</code> is also specified,
in which case the <em class="replaceable"><code>public-identifier</code></em> is written
as the public identifiers of the <code class="literal">DOCTYPE</code> declaration.
</p>
            </dd>
            <dt class="term"><code class="literal">out:xml-indent=<em class="replaceable"><code>kind</code></em></code>
</dt>
            <dd>
              <p>Controls whether extra line breaks and indentation are added
when printing XML.
If <em class="replaceable"><code>kind</code></em> is <code class="literal">always</code> or <code class="literal">yes</code> then newlines and
appropriate indentation are added before and after each element.
If <em class="replaceable"><code>kind</code></em> is <code class="literal">pretty</code> then the pretty-printer is used
to only add new lines when an element otherwise won’t fit on a single line.
If <em class="replaceable"><code>kind</code></em> is <code class="literal">no</code> (the default) then no extra line breaks
or indentation are added.
</p>
            </dd>
            <dt class="term"><code class="literal">out:line-length=<em class="replaceable"><code>columns</code></em></code>
</dt>
            <dt class="term"><code class="literal">out:right-margin=<em class="replaceable"><code>columns</code></em></code>
</dt>
            <dd>
              <p>Specifies the maximum number of number of columns in a line
when the pretty-printer decides where to break a line.
(The two options are equivalent.)
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Options for compiling and optimizing" epub:type="division" id="idm139667880136112">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for compiling and optimizing</h3>
            </div>
          </div>
        </div>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--target <em class="replaceable"><code>version</code></em></code>
</dt>
            <dd>
              <p>The <em class="replaceable"><code>version</code></em> can be a JDK or Java specification version:
<code class="literal">5</code>, <code class="literal">6</code>, or <code class="literal">7</code>.
The JDK versions <code class="literal">1.5</code> and <code class="literal">1.6</code> are equivalent to <code class="literal">5</code>
or <code class="literal">6</code>, respectively.
Specify a JVM (classfile) version to target.  This is useful
if (for example) you use Java 6, but want to create <code class="literal">.class</code> files
that can run on Java 5.  In that case specify <code class="literal">--target 5</code>.
</p>
            </dd>
          </dl>
        </div>
        <p>The following options control which calling conventions are used:
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--full-tailcalls</code>
</dt>
            <dd>
              <p>Use a calling convention that supports proper tail recursion.
</p>
            </dd>
            <dt class="term"><code class="literal">--no-full-tailcalls</code>
</dt>
            <dd>
              <p>Use a calling convention that does not support proper tail recursion.
Self-tail-recursion (i.e. a recursive call to the current function)
is still implemented correctly, assuming that the called function
is known at compile time.
</p>
            </dd>
            <dt class="term"><code class="literal">--no-inline</code>
</dt>
            <dd>
              <p>Disable inlining of known functions and methods.
The generated code runs slower, but you can more reliably trace procedures.
Normally Kawa will assume that a procedure <code class="literal">fn</code>
declared using a <code class="literal">(define (fn args) body)</code> form is constant,
assuming it isn’t modified in the current module.  However, it is
possible some other module might modify the binding of <code class="literal">fn</code>.
You can use the <code class="literal">--no-inline</code> to disable the assumption that <code class="literal">fn</code>
is constant.
</p>
            </dd>
          </dl>
        </div>
        <p>The default is currently <code class="literal">--no-full-tailcalls</code> because
it is usually faster.
It is also closer to the Java call model, so may be better for people
primarily interested in using Kawa for scripting Java systems.
</p>
        <p>Both calling conventions can co-exist:  Code compiled
with <code class="literal">--full-tailcalls</code> can call code compiled
with <code class="literal">--no-full-tailcalls</code> and vice versa.
</p>
        <p>These options can also be used in the module source, using
<code class="literal">module-compile-options</code> or <code class="literal">with-compile-options</code>.
(In that case they override the options on the command line.)
</p>
        <p>The options ‘<code class="literal">-C</code>’, ‘<code class="literal">-d</code>’, ‘<code class="literal">-T</code>’, ‘<code class="literal">-P</code>’, ‘<code class="literal">--main</code>’
‘<code class="literal">--applet</code>’, and <code class="literal">--servlet</code> are used to compile a Scheme file;
see <a class="link" href="Compiling.xhtml#Files-compilation" title="Compiling to a set of .class files">Files compilation</a>.
The options ‘<code class="literal">--module-static</code>’, <code class="literal">--module-nonstatic</code>,
<code class="literal">--no-module-static</code>, and <code class="literal">--module-static-run</code>
control how a module is mapped to a Java class; see <a class="link" href="Module-classes.xhtml#static-or-non-modules">static-or-non-modules</a>.
The option ‘<code class="literal">--connect <em class="replaceable"><code>portnum</code></em></code>’ is only used by
the ‘<code class="literal">kawa</code>’ front-end program.
</p>
      </section>
      <section class="sect2" title="Options for debugging" epub:type="division" id="idm139667880110352">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for debugging</h3>
            </div>
          </div>
        </div>
        <p>The following options are useful if you want to debug or understand
how Kawa works.
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--debug-dump-zip</code>
</dt>
            <dd>
              <p>Normally, when Kawa loads a source file, or evaluates a non-trivial expression,
it generates new internal Java classes but does not write them out.  This
option asks it to write out generated classes in a ‘<code class="literal">.zip</code>’ archive
whose name has the prefix ‘<code class="literal">kawa-zip-dump-</code>’.
</p>
            </dd>
            <dt class="term"><code class="literal">--debug-print-expr</code>
</dt>
            <dd>
              <p>Kawa translates source language forms into an internal <code class="literal">Expression</code>
data structure.  This option causes that data structure to be written out
in a readable format to the standard output.
</p>
            </dd>
            <dt class="term"><code class="literal">--debug-print-final-expr</code>
</dt>
            <dd>
              <p>Similar to the previous option, but prints out the <code class="literal">Expression</code> after
various transformations and optimizations have been done, and just before
code generation.
</p>
            </dd>
            <dt class="term"><code class="literal">--debug-syntax-pattern-match</code>
</dt>
            <dd>
              <p>Prints logging information to standard error when a <code class="literal">syntax-rules</code>
or <code class="literal">syntax-case</code> pattern matches.
</p>
            </dd>
            <dt class="term"><code class="literal">--debug-error-prints-stack-trace</code>
</dt>
            <dd>
              <p>Prints a stack trace with any error found during compilation.
</p>
            </dd>
            <dt class="term"><code class="literal">--debug-warning-prints-stack-trace</code>
</dt>
            <dd>
              <p>Prints a stack trace with any warning found during compilation.
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Options for web servers" epub:type="division" id="idm139667880098544">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for web servers</h3>
            </div>
          </div>
        </div>
        <p>JDK 6 (or later) includes a complete web server library.
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">--http-auto-handler <em class="replaceable"><code>context-path</code></em> <em class="replaceable"><code>appdir</code></em></code>
</dt>
            <dd>
              <p>Register a web application handler that uses files
in the directory <em class="replaceable"><code>appdir</code></em> to handle HTTP (web) requests
containing the given <em class="replaceable"><code>context-path</code></em>.  That is it handles
requests that start with <code class="literal">http://localhost:<em class="replaceable"><code>port</code></em><em class="replaceable"><code>context-path</code></em></code>.
(This assumes the <em class="replaceable"><code>context-path</code></em> starts with a <code class="literal">/</code>.)
See <a class="link" href="Self-configuring-page-scripts.xhtml" title="Self-configuring web page scripts">Self-configuring page scripts</a>.
</p>
            </dd>
            <dt class="term"><code class="literal">--http-start <em class="replaceable"><code>port</code></em></code>
</dt>
            <dd>
              <p>Start the web server, listing on the specified <em class="replaceable"><code>port</code></em>.
</p>
            </dd>
          </dl>
        </div>
      </section>
      <section class="sect2" title="Options for the JVM" epub:type="division" id="idm139667880089520">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title">Options for the JVM</h3>
            </div>
          </div>
        </div>
        <p>The <code class="literal">kawa</code> front-end can pass options to the <code class="literal">java</code> launcher,
using <code class="literal">-J</code> or <code class="literal">-D</code> options.
These must be given <span class="emphasis"><em>before</em></span> any other arguments.
For example:
</p>
        <pre class="screen">kawa -J-Xms48m -Dkawa.command.name=foo foo.scm
</pre>
        <p>is equivalent to (ignoring classpath issues):
</p>
        <pre class="screen">java -Xms48m -Dkawa.command.name=foo kawa.repl foo.scm
</pre>
        <p>You can also pass a <code class="literal">-D</code> option (but not a <code class="literal">-J</code> option) after the
class name, in which case it is processed by the Kawa command-line processor
rather than the <code class="literal">java</code> launcher.  The effect is normally the same.
</p>
        <div class="variablelist" epub:type="list">
          <dl class="variablelist">
            <dt class="term"><code class="literal">-J<em class="replaceable"><code>jvm-option</code></em></code>
</dt>
            <dd>
              <p>Passes the <em class="replaceable"><code>jvm-option</code></em> to the <code class="literal">java</code> command,
before the class-name (<code class="literal">kawa.repl</code>) and Kawa options.
</p>
            </dd>
            <dt class="term"><code class="literal">-D<em class="replaceable"><code>variable-name</code></em>=<em class="replaceable"><code>variable-value</code></em></code>
</dt>
            <dd>
              <p>Sets the JVM property <em class="replaceable"><code>variable-name</code></em> to <em class="replaceable"><code>variable-value</code></em>.
Equivalent to <code class="literal">-J-D<em class="replaceable"><code>variable-name</code></em>=<em class="replaceable"><code>variable-value</code></em></code>.
</p>
            </dd>
          </dl>
        </div>
      </section>
    </section>
    <footer>
      <div class="navfooter">
        <ul>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880304720">Argument processing</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880292032">General options</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880239696">Options for language selection</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880216944">Options for warnings and errors</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880186288">Options for setting variables</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880172992">Options for the REPL console</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880159184">Options for controlling output formatting</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880136112">Options for compiling and optimizing</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880110352">Options for debugging</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880098544">Options for web servers</a>
            </b>
          </li>
          <li>
            <b class="toc">
              <a href="Options.xhtml#idm139667880089520">Options for the JVM</a>
            </b>
          </li>
        </ul>
        <p>
          Up: <a accesskey="u" href="Running.xhtml">How to start up and run Kawa</a></p>
        <p>
        Next: <a accesskey="n" href="Scripts.xhtml">Running Command Scripts</a></p>
      </div>
    </footer>
  </body>
</html>