suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

document mz/mr command-line arguments

Browse Source 
svn: r8047
This commit is contained in:
Matthew Flatt 2007-12-18 13:52:50 +00:00
parent 814ec3933c
commit 058d8dc77e
10 changed files with 381 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
collects/scribble/manual.ss
View File

@ -232,7 +232,7 @@
(provide image onscreen menuitem defterm
schemefont schemevalfont schemeresultfont schemeidfont schemevarfont
schemeparenfont schemekeywordfont schememetafont schememodfont
filepath exec envvar Flag DFlag
filepath exec envvar Flag DFlag PFlag DPFlag
indexed-file indexed-envvar
link procedure
idefterm)
@ -284,6 +284,10 @@
(make-element 'no-break (list (make-element 'tt (cons "-" (decode-content str))))))
(define (DFlag . str)
(make-element 'no-break (list (make-element 'tt (cons "--" (decode-content str))))))
(define (PFlag . str)
(make-element 'no-break (list (make-element 'tt (cons "+" (decode-content str))))))
(define (DPFlag . str)
(make-element 'no-break (list (make-element 'tt (cons "++" (decode-content str))))))
(define (envvar . str)
(make-element 'tt (decode-content str)))
(define (indexed-envvar . str)

9
collects/scribblings/reference/collects.scrbl
View File

@ -63,7 +63,8 @@ is initialized in @exec{mzscheme} to the result of
@scheme[(find-library-collection-paths)].
@defproc[(find-library-collection-paths) (listof path?)]{
@defproc[(find-library-collection-paths [extras (listof path-string?) null])
(listof path?)]{
Produces a list of paths as follows:
@ -74,10 +75,8 @@ Produces a list of paths as follows:
default collection path list, unless the value of the
@scheme[use-user-specific-search-paths] parameter is @scheme[#f].}
@item{If the executable embeds a list of search paths, they are
included (in order) after the first element in the default
collection path list. Embedded relative paths are included only when
the corresponding directory exists relative to the executable.}
@item{Extra directories provided in @scheme[extras] are included next,
converted to complete paths relative to the executable.}
@item{If the directory specified by @scheme[(find-system-path
'collects-dir)] is absolute, or if it is relative (to the

36
collects/scribblings/reference/contracts.scrbl
View File

@ -315,15 +315,11 @@ error.}
A @deftech{function contract} wraps a procedure to delay
checks for its arguments and results.
@deftogether[(
@defform[#:literals (any values)
(-> dom-exprs ... res-expr)]
@defform[#:literals (any values)
(-> dom-exprs ... (values res-expr ...))]
@defform/subs[#:literals (any values)
(-> dom-exprs ... any)
([dom-exprs expr (code:line keyword expr)])]
)]{
@defform*/subs[#:literals (any values)
[(-> dom ... res-expr)
(-> dom ... (values res-expr ...))
(-> dom ... any)]
([dom dom-expr (code:line keyword dom-expr)])]{
Produces a contract for a function that accepts a fixed
number of arguments and returns either a fixed number of
@ -348,26 +344,24 @@ produces a contract on functions of two arguments. The first argument
must be an integer, and the second argument must be a boolean. The
function must produce an integer.
The domain specification may contain be keywords. If so, the
functions must accept the same (mandatory) keyword arguments
and those keyword arguments must match the contracts that
follow them. For example:
A domain specification may include a keyword. If so, the function must
accept corresponding (mandatory) keyword arguments, and the values for
the keyword arguments must match the corresponding contracts. For
example:
@schemeblock[(integer? #:x boolean? . -> . integer?)]
is a contract on a function that accepts a single, integer
ordinary argument and the keyword argument @scheme[#:x]
whose values must be booleans.
is a contract on a function that accepts a by-position argument that
is an integer and a @scheme[#:x] argument is that a boolean.
If @scheme[any] is used as the last argument to @scheme[->], no
If @scheme[any] is used as the last sub-form for @scheme[->], no
contract checking is performed on the result of the function, and
tail-recursion is preserved. Note that the function may return
multiple values in that case.
If @scheme[(values res-expr ...)] is used as the last
argument to @scheme[->], the result must have single value
for each contract and the values must match their respective
contracts.}
If @scheme[(values res-expr ...)] is used as the last sub-form of
@scheme[->], the function must produce a result for each contract, and
each values must match its respective contract.}
@defform*[#:literals (any)
[(->* (expr ...) (res-expr ...))

21
collects/scribblings/reference/init.scrbl
View File

@ -1,10 +1,19 @@
#lang scribble/doc
@(require "mz.ss"
(for-label scheme/pretty))
(for-label scheme/pretty
scheme/gui/base))
@title{Initialization}
@title{Init Libraries}
@defmodule[scheme/init]{The @schememodname[scheme/init] library is the
default start-up library for @exec{mzscheme}. It re-exports the
@schememodname[scheme] and @schememodname[scheme/help] libraries, and
it sets @scheme[current-print] to use @scheme[pretty-print].}
See also @secref["init-actions"].
@defmodule*/no-declare[(scheme/init)]{The @schememodname[scheme/init]
library is the default start-up library for MzScheme. It re-exports
the @schememodname[scheme] and @schememodname[scheme/help] libraries,
and it sets @scheme[current-print] to use @scheme[pretty-print].}
@defmodule*/no-declare[(scheme/gui/init)]{The
@schememodname[scheme/gui/init] library is the default start-up
library for MrEd. It re-exports the @schememodname[scheme/init] and
@schememodname[scheme/gui/base] libraries, and it sets
@scheme[current-load] to use @scheme[text-editor-load-handler].}

1
collects/scribblings/reference/reference.scrbl
View File

@ -41,7 +41,6 @@ where @schememodname[scheme] includes all of
This chapter provides some temporary hyper-link targets.
@subsection[#:tag "running-sa"]{Running MzScheme}
@subsection[#:tag "async-channel"]{Asynchronous Channels}
@subsection[#:tag "honu"]{Honu}

3
collects/scribblings/reference/running.scrbl
View File

@ -5,6 +5,7 @@
@local-table-of-contents[]
@include-section["startup.scrbl"]
@include-section["collects.scrbl"]
@include-section["init.scrbl"]
@include-section["help.scrbl"]
@include-section["init.scrbl"]

301
collects/scribblings/reference/startup.scrbl Normal file
View File

@ -0,0 +1,301 @@
#lang scribble/doc
@(require "mz.ss"
scribble/bnf
(for-label scheme/pretty
scheme/gui/base))
@(define (FlagFirst n) (as-index (Flag n)))
@(define (DFlagFirst n) (as-index (DFlag n)))
@(define (PFlagFirst n) (as-index (PFlag n)))
@(define eventspace
@tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspace})
@title[#:tag "running-sa"]{Starting MzScheme or MrEd}
The core PLT Scheme run-time system is available in two main variants:
@itemize{
@item{MzScheme, which provides the primitives libraries on which
@schememodname[scheme/base] is implemented. Under Unix and Mac
OS X, the executable is called
@as-index{@exec{mzscheme}}. Under Windows, the executable is
called @as-index{@exec{MzScheme.exe}}.}
@item{MrEd, which extends @exec{mzscheme} with GUI primitives on
which @schememodname[scheme/gui/base] is implemented. Under
Unix, the executable is called @as-index{@exec{mred}}. Under
Windows, the executable is called
@as-index{@exec{MrEd.exe}}. Under Mac OS X, the @exec{mred}
script launches @as-index{@exec{MrEd.app}}.}
}
@; ----------------------------------------------------------------------
@section[#:tag "init-actions"]{Initialization}
On startup, the top-level environment contains no bindings---not even
for function application.
The first action of MzScheme or MrEd is to initialize
@scheme[current-library-collection-paths] to the result of
@scheme[(find-library-collection-paths _extras)], where
@scheme[_extras] are extra directory paths provided in order in the
command line with @Flag{S}/@DFlag{search}. An executable created from
the MzScheme or MrEd executable can embed additional paths that are
appended to @scheme[_extras].
MzScheme and MrEd next @scheme[require] @schememodname[scheme/init]
and @schememodname[scheme/gui/init], respectively, but only if the
command line does not specify a @scheme[require] flag
(@Flag{t}/@DFlag{require}, @Flag{l}/@DFlag{lib}, or
@Flag{u}/@DFlag{require-script}) before any @scheme[eval],
@scheme[load], or read-eval-print-loop flag (@Flag{e}/@DFlag{eval},
@Flag{f}/@DFlag{load}, @Flag{r}/@DFlag{script}, @Flag{m}/@DFlag{main},
@Flag{i}/@DFlag{repl}, or @Flag{z}/@DFlag{text-repl}).
After potentially loading the initialization module, expression
@scheme[eval]s, files @scheme[load]s, and module @scheme[require]s are
executed in the order that they are provided on the command line. If
any raises an uncaught exception, then the remaining @scheme[eval]s,
@scheme[load]s, and @scheme[require]s are skipped.
After running all command-line expressions, files, and modules,
MzScheme or MrEd then starts a read-eval-print loop for interactive
evaluation if no command line flags are provided. If any command-line
argument is provided, then the read-eval-print-loop is not started,
unless the @Flag{i}/@DFlag{repl} or @Flag{z}/@DFlag{text-repl} flag is
provided on the command line to specifically re-enable it. In
addition, just before the command line is started, MzScheme loads the
file @scheme[(find-system-path 'init-file)] and MrEd loads the file
@scheme[(find-graphical-system-path 'init-file)] is loaded, unless the
@Flag{q}/@DFlag{no-init-file} flag is specified on the command line.
Finally, before MrEd exists, it waits for all frames to class, all
timers to stop, @|etc| in the main @|eventspace| by evaluating
@scheme[(scheme 'yield)]. This waiting step can be suppressed with the
@Flag{V}/@DFlag{no-yield} command-line flag.
The exit status for the MzScheme or MrEd process indicates an error if
an error occurs during a command-line @scheme[eval], @scheme[load], or
@scheme[require] when no read-eval-print loop is started. Otherwise,
the exit status is @scheme[0] or determined by a call to
@scheme[exit].
@; ----------------------------------------------------------------------
@section{Command Line}
The MzScheme and MrEd executables recognize the following command-line
flags:
@itemize{
@item{File and expression options:
@itemize{
@item{@FlagFirst{e} @nonterm{expr} or @DFlagFirst{eval}
@nonterm{expr} : @scheme[eval]s @nonterm{expr}.}
@item{@FlagFirst{f} @nonterm{file} or @DFlagFirst{load}
@nonterm{file} : @scheme[load]s @nonterm{file}.}
@item{@FlagFirst{t} @nonterm{file} or @DFlagFirst{require}
@nonterm{file} : @scheme[require]s @nonterm{file}.}
@item{@FlagFirst{l} @nonterm{path} or @DFlagFirst{lib}
@nonterm{path} : @scheme[require]s @scheme[(lib
@nonterm{path})].}
@item{@FlagFirst{p} @nonterm{file} @nonterm{u} @nonterm{path} :
@scheme[require]s @scheme[(planet @nonterm{file}
@nonterm{user} @nonterm{pkg})].}
@item{@FlagFirst{r} @nonterm{file} or @DFlagFirst{script}
@nonterm{file} : @scheme[load]s @nonterm{file} as a
script. This flag is like @Flag{t} @nonterm{file} plus
@Flag{N} @nonterm{file} to set the program name and @Flag{-}
to cause all further command-line elements to be treated as
non-flag arguments.}
@item{@FlagFirst{u} @nonterm{file} or @DFlagFirst{require-script}
@nonterm{file} : @scheme[require]s @nonterm{file} as a script;
This flag is like @Flag{t} @nonterm{file} plus @Flag{N}
@nonterm{file} to set the program name and @Flag{-} to cause
all further command-line elements to be treated as non-flag
arguments.}
@item{@FlagFirst{k} @nonterm{n} @nonterm{m} : Loads code embedded in
the executable from file position @nonterm{n} to
@nonterm{m}. This option normally embedded in a stand-alone
binary that embeds Scheme code.}
@item{@FlagFirst{m} or @DFlagFirst{main} : Evaluates a call to
@scheme[main] in the top-level environment. All of the
command-line arguments that are not processed as options
(i.e., the arguments put into
@scheme[current-command-line-args]) are passed as arguments to
@scheme[main].}
}}
@item{Interaction options:
@itemize{
@item{@FlagFirst{i} or @DFlagFirst{repl} : Runs interactive read-eval-print
loop, using either @scheme[read-eval-print-loop] (MzScheme) or
@scheme[graphical-read-eval-print-loop] (MrEd) after showing
@scheme[(banner)] and loading @scheme[(find-system-path
'init-file)].}
@item{@FlagFirst{z} or @DFlagFirst{text-repl} : MrEd only; like
@Flag{i}/@DFlag{repl}, but uses @scheme[read-eval-print-loop]
instead of @scheme[graphical-read-eval-print-loop].}
@item{@FlagFirst{q} or @DFlagFirst{no-init-file} : Skips loading
@scheme[(find-system-path 'init-file)] for
@Flag{i}/@DFlag{repl} or @Flag{z}/@DFlag{text-repl}.}
@item{@FlagFirst{n} or @DFlagFirst{no-lib} : Skips requiring
@schememodname[scheme/init] or @schememodname[scheme/gui/init]
when not otherwise disabled.}
@item{@FlagFirst{v} or @DFlagFirst{version} : Shows
@scheme[(banner)].}
@item{@FlagFirst{K} or @DFlagFirst{back} : MrEd, Mac OS X only;
leave application in the background.}
@item{@FlagFirst{V} @DFlagFirst{no-yield} : Skips final
@scheme[(yield 'wait)] action, which normally waits until all
frames are closed, @|etc| in the main @|eventspace| before
exiting.}
}}
@item{Configuration options:
@itemize{
@item{@FlagFirst{c} or @DFlagFirst{no-compiled} : Disables loading
of compiled byte-code @filepath{.zo} files, by initializing
@scheme[current-compiled-file-paths] to @scheme[null].}
@item{@FlagFirst{X} @nonterm{dir} or @DFlagFirst{collects}
@nonterm{dir} : Sets @nonterm{dir} as the path to the main
collection of libraries by making @scheme[(find-system-path
'collects-dir)] produce @nonterm{dir}.}
@item{@FlagFirst{S} @nonterm{dir} or @DFlagFirst{search}
@nonterm{dir} : Adds @nonterm{dir} to the library collection
search path. The @scheme{dir} is added after a user-specific
directory, if any, and before the main collection directory.}
@item{@FlagFirst{U} or @DFlagFirst{no-user-path} : Omits
user-psecific paths in the search for collections, C
libraries, etc. by initializing the
@scheme[use-user-specific-search-paths] parameter to
@scheme[#f].}
@item{@FlagFirst{N} @nonterm{file} or @DFlagFirst{name}
@nonterm{file} : sets the name of the executable as reported
by @scheme[(find-system-path 'run-file)] to
@nonterm{file}.}
@item{@FlagFirst{j} or @DFlagFirst{no-jit} : Disables the
native-code just-in-time compiler by setting the
@scheme[eval-jit-enabled] parameter to @scheme[#f].}
@item{@FlagFirst{d} or @DFlagFirst{no-delay} : Disables on-demand
parsing of compiled code and syntax objects by setting the
@scheme[read-on-demand-source] parameter to @scheme[#f].}
@item{@FlagFirst{b} or @DFlagFirst{binary} : Requests binary mode,
instead of text mode, for the process's input, out, and error
ports. This flag currently has no effect, because binary mode
is always used.}
}}
@item{Meta options:
@itemize{
@item{@FlagFirst{-} : No argument following this flag is itself used
as a flag.}
@item{@FlagFirst{h} or @DFlagFirst{help} : Shows information about
the command-line flags and start-up process and exits,
ignoring all other flags.}
}}
}
If at least one command-line argument is provided, and if the first
one is not a flag, then a @Flag{u}/@DFlag{--require-script} flag is
implicitly added before the first argument.
For MrEd under X11, the follow flags are recognized when they appear
at the beginning of the command line, and they do not otherwise count
as command-line flags (i.e., they do not disable the read-eval-print
loop or prevent the insertion of @Flag{u}/@DFlag{require-script}):
@itemize{
@item{@FlagFirst{display} @nonterm{display} : Sets the X11 display
to use.}
@item{@FlagFirst{geometry} @nonterm{arg}, @FlagFirst{bg}
@nonterm{arg}, @FlagFirst{background} @nonterm{arg},
@FlagFirst{fg} @nonterm{arg}, @FlagFirst{foreground}
@nonterm{arg}, @FlagFirst{fn} @nonterm{arg}, @FlagFirst{font}
@nonterm{arg}, @FlagFirst{iconic}, @FlagFirst{name}
@nonterm{arg}, @FlagFirst{rv}, @FlagFirst{reverse},
@PFlagFirst{rv}, @FlagFirst{selectionTimeout} @nonterm{arg},
@FlagFirst{synchronous}, @FlagFirst{title} @nonterm{arg},
@FlagFirst{xnllanguage} @nonterm{arg}, or @FlagFirst{xrm}
@nonterm{arg} : Standard X11 arguments that are mostly ignored
but accepted for compatibility with other X11 programs. The
@Flag{synchronous} and @Flag{xrm} flags behave in the usual
way.}
@item{@FlagFirst{singleInstance} : If an existing MrEd is already
running on the same X11 display, if it was started on a
machine with the same hostname, and if it was started with the
same name as reported by @scheme[(find-system-path
'run-file)]---possibly set with the @Flag{N}/@DFlag{name}
command-line argument---then all non-option command-line
arguments are treated as filenames and sent to the existing
MrEd instance via the application file handler (see
@scheme[application-file-handler]).}
}
Under Mac OS X, a leading switch starting with @FlagFirst{psn_} is
treated specially. It indicates that Finder started the application,
so the current input, output, and error output are redirected to a GUI
window. It does not count as a command-line flag otherwise.
Multiple single-letter switches (the ones preceded by a single @litchar{-}) can
be collapsed into a single switch by concatenating the letters, as long
as the first switch is not @Flag{-}. The arguments for each switch
are placed after the collapsed switches (in the order of the
switches). For example,
@commandline{-ifve @nonterm{file} @nonterm{expr}}
and
@commandline{-i -f @nonterm{file} -v -e @nonterm{expr}}
are equivalent. If a collapsed @Flag{-} appears before other collapsed
switches in the same collapsed set, it is implicitly moved to the end
of the collapsed set.
Extra arguments following the last option are available from the
@indexed-scheme[current-command-line-arguments] parameter.

20
collects/scribblings/scribble/manual.scrbl
View File

@ -245,7 +245,7 @@ hovers the mouse over one of the bindings defined within the section.}
(keyword arg-id contract-expr-datum)
(keyword arg-id contract-expr-datum default-expr)])]{
Produces a sequence of flow elements (encaptured in a @scheme[splice])
Produces a sequence of flow elements (encapsulated in a @scheme[splice])
to document a procedure named @scheme[id]. The @scheme[id] is indexed,
and it also registered so that @scheme[scheme]-typeset uses of the
identifier (with the same for-label binding) are hyperlinked to this
@ -343,7 +343,13 @@ non-terminals shown with the @scheme[id] form. Each
@scheme[clause-datum] is preserved.}
@defform[(defform/none datum pre-flow ...)]{
@defform[(defform*/subs maybe-literals [(id . datum) ...]
pre-flow ...)]{
Like @scheme[defform/subs], but for multiple forms for @scheme[id].}
@defform[(defform/none maybe-literal datum pre-flow ...)]{
Like @scheme[defform], but without registering a definition.}
@ -431,6 +437,16 @@ Similar to @scheme[defform] or @scheme[defproc], but for a structure
definition.}
@defform[(deftogether [def-expr ...] pre-flow ...)]{
Combines the definitions created by the @scheme[def-expr]s into a
single definition box. Each @scheme[def-expr] should produce a
definition point via @scheme[defproc], @scheme[defform], etc. Each
@scheme[def-expr] should have an empty @scheme[pre-flow]; the
@tech{decode}d @scheme[pre-flow] sequence for the @scheme[deftogether]
form documents the collected bindings.}
@defform/subs[(schemegrammar maybe-literals id clause-datum ...+)
([maybe-literals code:blank
(code:line #:literals (literal-id ...))])]{

23
collects/scribblings/scribble/style.scrbl
View File

@ -8,20 +8,35 @@
In the descriptive body of @scheme[defform], @scheme[defproc], etc.,
do not start with ``This ...'' Instead, start with a sentence whose
implicit subject is the form or value being described. Thus, the
description will often start with ``Produces.'' Refer to arguments by
name.
description will often start with ``Produces.'' Refer to arguments and
sub-forms by name.
Use @schemeidfont{id} or something that ends @schemeidfont{-id} in
Do not use the word ``argument'' to describe a sub-form in a syntactic
form; use the term ``sub-form'' instead, reserving ``argument'' for
values or expressions in a function call. Refer to libraries and
languages as such, rather than as ``modules'' (even though the form to
typeset a library or language name is called @scheme[schememodname]).
Do not call an identifier (i.e., a syntactic element) a ``variable''
or a ``symbol.''
Use @schemeidfont{id} or a name that ends @schemeidfont{-id} in
@scheme[defform] to mean an identifier, not @schemeidfont{identifier},
@schemeidfont{variable}, @schemeidfont{name}, or
@schemeidfont{symbol}. Similarly, use @schemeidfont{expr} or something
that ends @schemeidfont{-expr} for an expression position within a
syntactic form. Use @schemeidfont{body} for a form (definition or
expression) in an internal-definition position. Never use
expression) in an internal-definition position. Do not use
@schemeidfont{expr} for something that isn't exactly an expression,
@scheme[id] for something that isn't exactly an identifier, etc.;
instead, use @scheme[defform/subs] to define a new non-terminal.
Beware of using @scheme[deftogether] to define multiple variants of a
syntactic form or procedure, because each @scheme[defform] or
@scheme[defproc] creates a definition point, but each form or
procedure should have a single definition point. (Scribble issues a
warning when a binding has multiple definition points.) Instead, use
@scheme[defproc*] or @scheme[defform*].
Pay attention to the difference between identifiers and meta-variables
when using @scheme[scheme], especially outside of @scheme[defproc] or
@scheme[defform]. Prefix a meta-variable with @litchar{_}; for

10
src/mzscheme/cmdline.inc
View File

@ -467,7 +467,6 @@ static int run_from_cmd_line(int argc, char *_argv[],
int alternate_rep = 0;
int no_front = 0;
#endif
int no_lib_path = 0;
int no_compiled = 0;
int init_ns = 0, no_init_ns = 0;
FinishArgs *fa;
@ -671,8 +670,6 @@ static int run_from_cmd_line(int argc, char *_argv[],
argv[0] = "-m";
else if (!strcmp("--name", argv[0]))
argv[0] = "-N";
else if (!strcmp("--no-lib-path", argv[0]))
argv[0] = "-x";
else if (!strcmp("--no-compiled", argv[0]))
argv[0] = "-c";
else if (!strcmp("--no-lib", argv[0]))
@ -755,15 +752,13 @@ static int run_from_cmd_line(int argc, char *_argv[],
collects_extra = scheme_make_pair(scheme_make_path(argv[0]),
collects_extra);
break;
case 'x':
no_lib_path = 1;
break;
case 'c':
no_compiled = 1;
break;
case 'm':
evals_and_loads[num_enl] = "";
eval_kind[num_enl++] = mzcmd_MAIN;
init_ns = 1;
break;
case 'r':
script_mode = 1;
@ -979,7 +974,7 @@ static int run_from_cmd_line(int argc, char *_argv[],
#ifndef NO_FILE_SYSTEM_UTILS
/* Setup path for "collects" collection directory: */
if (!no_lib_path) {
{
Scheme_Object *l, *r;
int len, offset;
@ -1091,7 +1086,6 @@ static int run_from_cmd_line(int argc, char *_argv[],
" -X <dir>, --collects <dir> : Main collects at <dir> relative to " PROGRAM "\n"
" -S <dir>, --search <dir> : More collects at <dir> relative to " PROGRAM "\n"
" -U, --no-user-path : Ignore user-specific collects, etc.\n"
" -x, --no-lib-path : Skip trying to set current-library-collection-paths\n"
" -N <file>, --name <file> : Sets `(find-system-path 'run-file)' to <file>\n"
# ifdef MZ_USE_JIT
" -j, --no-jit : Disable the just-in-time compiler\n"