Argument processing

Kawa processes the command-line arguments in order. Options (which either start with ‘-’ or contain a ‘=’) may “use up” one or more command arguments. Some of the options (‘-c’, ‘-e’, ‘-f’, ‘-s’, ‘-C’, -w, ‘--’, --browse-manual) are action options; others set various properties.

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.)

If the next command-line argument is not an option (does not start with ‘-’ nor contains a ‘=’) then we’re done if we’ve seen an action option (and the last action option wasn’t preceded by --with-arg-count). (Presumably any remaining arguments were command-line-arguments used by the action option.)

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 -f 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 run method invoked. If the class was compiled from a Kawa Scheme module, then invoking run has the effect of evaluating the module body. The command-line-arguments vector is set to any remaining arguments after the file/class name. (This can be overridden with the --with-arg-count option. Command-line processing continues if there are any further arguments.)

General options

-e expr

Kawa evaluates expr, which contains one or more Scheme expressions. Does not cause the ~/.kawarc.scm init file to be run.

-c expr

Same as ‘-e expr’, except that it does cause the ~/.kawarc.scm init file to be run.

-f filename-or-url

Kawa reads and evaluates expressions from the file named by filename-or-url. If the latter is ‘-’, standard input is read (with no prompting). Otherwise, it is equivalent to evaluating ‘(load "filename-or-url")’. The filename-or-url is interpreted as a URL if it is absolute - it starts with a "URI scheme" like http:.

-s

--

The remaining arguments (if any) are passed to ‘command-line-arguments’ and (the cdr of) (command-line), and an interactive read-eval-print loop is started. This uses the same "console" as where you started up Kawa; use ‘-w’ to get a new window.

--script filename-or-url

--scriptN filename-or-url

The global variable ‘command-line-arguments’ is set to the remaining arguments (if any). Kawa reads and evaluates expressions from the file named by filename-or-url. If script is followed by an integer N, then N lines are skipped first.

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 Running Command Scripts).

-w

-wsub-option

Creates a new top-level window, and runs an interactive read-eval-print in the new window. See New-Window. Same as -e (scheme-window #t). You can specify multiple ‘-w’ options, and also use ‘-s’.

--help

Prints out some help.

--version

Prints out the Kawa version number, and then exits.

If Kawa was built with a .git repository present, also prints the result of git describe.

--browse-manual

--browse-manual=command

Browse a local copy of the documentation (this manual).

This creates a mini web-server that reads from doc/kawa-manual.epub, which is included in the binary distributions, but not built by default from source.

If no command is specified, creates a new mini-browser-window using JavaFX (if the JavaFX modules are available), or creates a new window or tab in your default web browser (otherwise). If command is a string containing %U, then Kawa replaces %U with a URL that references itself, and then executes the resulting command. If command does not contain %U, then command becomes command" %U". For example to use the Firefox browser to browse the manual do either of:

kawa --browse-manual=firefox
kawa --browse-manual="firefox %U"

--server portnum

Start a server listening from connections on the specified portnum. 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".

--with-arg-count=argc

This option is used before an action option (such as -f). The argc arguments after the action become the value of the command-line-arguments during the action. When the action is finished, command-line-processing resumes after skipping the argc arguments.

For example:

$ kawa -f a.scm -f b.scm x y

When evaluating a.scm the command-line-arguments by default is all the remaining arguments: ["-f" "b.scm" "x" "y"]. Then b.scm is evaluated with command-line-arguments set to ["x" "y"]

$ kawa --with-arg-count=0 -f a.scm -f b.scm x y

In this case a.scm is evaluated with command-line-arguments set to the empty vector [], and then b.scm is evaluated with command-line-arguments set to ["x" "y"]

$ kawa --with-arg-count=4 -f a.scm -f b.scm x y

In this case a.scm is evaluated with command-line-arguments set to ["-f" "b.scm" "x" "y"]. Since command-line processing skips the arguments specified by --with-arg-count=4, in this case b.scm is not evaluated.

Options for language selection

--scheme

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.)

--r5rs

--r6rs

--r7rs

Provide better compatibility with the specified Scheme standards. (This is a work-in-progress.) For example --r6rs 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 ‘@’ as a splicing operator. The “l” exponent suffix of a number literal creates a floating-point double, rather than a BigInteger. Selecting --r5rs makes symbols by default case-insensitive.

--elisp

--emacs

--emacs-lisp

Set the default language to Emacs Lisp. (The implementation is quite incomplete.)

--lisp

--clisp

--clisp

--commonlisp

--common-lisp

Set the default language to CommonLisp. (The implementation is very incomplete.)

--krl

Set the default language to KRL. See KRL - The Kawa Report Language for generating XML/HTML.

--brl

Set the default language to KRL, in BRL-compatibility mode. See KRL - The Kawa Report Language for generating XML/HTML.

--xquery

Set the default language to the draft XML Query language. See the Kawa-XQuery page for more information.

--xslt

Set the default language to XSLT (XML Stylesheet Language Transformations). (The implementation is very incomplete.) See the Kawa-XSLT page for more information.

--pedantic

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.

Options for warnings and errors

--warn-undefined-variable

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 define-variable 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 --no-warn-undefined-variable flag.

--warn-unknown-member

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 --no-warn-unknown-member flag.

--warn-invoke-unknown-method

Emit a warning if the invoke 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 --warn-unknown-member, to turn it off use the --no-warn-invoke-unknown-method flag.

--warn-unused

Emit a warning if a variable is unused or code never executed. This defaults to on; to turn it off use the --no-warn-unused flag.

--warn-uninitialized

Warn if accessing an uninitialized variable. This defaults to on; to turn it off use the --no-warn-uninitialized flag.

--warn-unreachable

Emit a warning if the code can never be executed. This defaults to on; to turn it off use the --no-warn-unreachable flag.

--warn-void-used

Emit a warning if an expression depends on an expression that is void (always has zero values), including call to void functions and method. Also warn if an expression depends on a conditional (if) that has no “else” clause. Examples include using the value of set-car! as an argument to a function, or to initialize a variable. This defaults to on; to turn it off use the --no-warn-void-used flag.

--warn-as-error

Treat a compilation warning as if it were an error and halt compilation.

--max-errors=value

Print no more than value errors or warnings (at a time). The value -1 removes the limit. The initial default is 20. (A single error may so confuse Kawa that it prints very many useless error messages.)

An option can be followed by a value, as in --warn-invoke-unknown-method=no. For boolean options, the values yes, true, on, or 1 enable the option, while no, false, off, or 0 disable it. You can also negate an option by prefixing it with no-: The option --no-warn-unknown-member is the same as --warn-unknown-member=no.

These options can also be used in the module source, using module-compile-options or with-compile-options. (In that case they override the options on the command line.)

Options for setting variables

name=value

Set the global variable with the specified name to the given value. The type of the value is currently unspecified; the plan is for it to be like XQuery’s untyped atomic which can be coerced as needed.

{namespace-uri}local-name=value

Set the global variable with the specified namespace uri and namespace-local name to the given value.

These options are processed when invoking the kawa application (i.e. the kawa.repl application). If you want a Kawa application compiled with --main to process these these assignments, call the process-command-line-assignments utility function.

-Dvariable-name=variable-value

Sets the JVM property variable-name to variable-value, using the setProperty method of java.lang.System.

Options for the REPL console

--console

--no-console

Usually Kawa can detect when the standard input port is a “console” or “terminal”, but these are useful for overriding that detection. The --console flag is useful when the standard input is a pipe, but you want to direct Kawa to treat it as an interactive terminal. The --no-console flag was useful for older pre-Java-6 implementations that did not have the java.lang.Console class.

console:type=console-types

console:use-jline=[yes|no]

console:jline-mouse=[yes|no]

See the The REPL (read-eval-print-loop) console section.

console:prompt1=prompt1

console:prompt2=prompt2

Initialize input-prompt1 and input-prompt2, respectively.

See also the --output-format flag.

Options for controlling output formatting

--output-format format

--format format

Change the default output format to that specified by format. See Named output formats for more information and a list.

out:base=integer

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 out:base=16 produces hexadecimal output. Equivalent to setting the *print-base* variable.

out:radix=no|yes

If true, prints an indicator of the radix used when printing rational numbers. The default is no. Equivalent to setting the *print-radix* variable.

out:doctype-system=system-identifier

If out:doctype-system is specified then a DOCTYPE declaration is written before writing a top-level XML element, using the specified system-identifier.

out:doctype-public=public-identifier

Ignored unless out:doctype-system is also specified, in which case the public-identifier is written as the public identifiers of the DOCTYPE declaration.

out:xml-indent=kind

Controls whether extra line breaks and indentation are added when printing XML. If kind is always or yes then newlines and appropriate indentation are added before and after each element. If kind is pretty then the pretty-printer is used to only add new lines when an element otherwise won’t fit on a single line. If kind is no (the default) then no extra line breaks or indentation are added.

out:line-length=columns

out:right-margin=columns

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.)

Options for compiling and optimizing

--target version

The version can be a JDK or Java specification version: 5, 6, or 7. The JDK versions 1.5 and 1.6 are equivalent to 5 or 6, respectively. Specify a JVM (classfile) version to target. This is useful if (for example) you use Java 6, but want to create .class files that can run on Java 5. In that case specify --target 5.

The following options control which calling conventions are used:

--full-tailcalls

Use a calling convention that supports proper tail recursion.

--no-full-tailcalls

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.

--no-inline

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 fn declared using a (define (fn args) body) form is constant, assuming it isn’t modified in the current module. However, it is possible some other module might modify the binding of fn. You can use the --no-inline to disable the assumption that fn is constant.

The default is currently --no-full-tailcalls 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.

Both calling conventions can co-exist: Code compiled with --full-tailcalls can call code compiled with --no-full-tailcalls and vice versa.

These options can also be used in the module source, using module-compile-options or with-compile-options. (In that case they override the options on the command line.)

The options ‘-C’, ‘-d’, ‘-T’, ‘-P’, ‘--main’ ‘--applet’, and --servlet are used to compile a Scheme file; see Compiling to a set of .class files. The options ‘--module-static’, --module-nonstatic, --no-module-static, and --module-static-run control how a module is mapped to a Java class; see static-or-non-modules. The option ‘--connect portnum’ is only used by the ‘kawa’ front-end program.

Options for debugging

The following options are useful if you want to debug or understand how Kawa works.

--debug-dump-zip

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 ‘.zip’ archive whose name has the prefix ‘kawa-zip-dump-’.

--debug-print-expr

Kawa translates source language forms into an internal Expression data structure. This option causes that data structure to be written out in a readable format to the standard output.

--debug-print-final-expr

Similar to the previous option, but prints out the Expression after various transformations and optimizations have been done, and just before code generation.

--debug-syntax-pattern-match

Prints logging information to standard error when a syntax-rules or syntax-case pattern matches.

--debug-error-prints-stack-trace

Prints a stack trace with any error found during compilation.

--debug-warning-prints-stack-trace

Prints a stack trace with any warning found during compilation.

--langserver

Starts Kawa in server mode, responding to requests using the Language Server Protocol. This is used by editors and IDEs for on-the-fly syntax checking and more. Highly experimental.

Options for web servers

JDK 6 (or later) includes a complete web server library.

--http-auto-handler context-path appdir

Register a web application handler that uses files in the directory appdir to handle HTTP (web) requests containing the given context-path. That is it handles requests that start with http://localhost:portcontext-path. (This assumes the context-path starts with a /.) See Self-configuring web page scripts.

--http-start port

Start the web server, listing on the specified port.

Options for the JVM

The kawa front-end can pass options to the java launcher, using -J or -D options. These must be given before any other arguments. For example:

kawa -J-Xms48m -Dkawa.command.name=foo foo.scm

is equivalent to (ignoring classpath issues):

java -Xms48m -Dkawa.command.name=foo kawa.repl foo.scm

You can also pass a -D option (but not a -J option) after the class name, in which case it is processed by the Kawa command-line processor rather than the java launcher. The effect is normally the same.

-Jjvm-option

Passes the jvm-option to the java command, before the class-name (kawa.repl) and Kawa options.

-Dvariable-name=variable-value

Sets the JVM property variable-name to variable-value. Equivalent to -J-Dvariable-name=variable-value.