| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: &key application
This function and its relatives, command-line-arguments and command-line-argument-count provide information about the command line that invoked Allegro CL. Their precise behavior depends on the value of the application keyword argument.
The command line includes the following, in the order specified:
/usr/local/acl/mlisp
) or may not (just
mlisp
).
--
(a
double dash).
See Command line arguments in startup.htm for a list of command-line arguments accepted by Allegro CL.
The application arguments are the executable name (number 1 in the
list above) and the ones which follow the double dash (number 5 in the
list above). Consider that those arguments are collected as strings in
a list called the
list-of-application-arguments
. When
application is true (it defaults to t
), the command-line argument information functions
behave as follows:
list-of-application-arguments
. It is an error
to specify a value for n equal to or greater than the length of
list-of-application-arguments
.
list-of-application-arguments
.
list-of-application-arguments
.
;; Lisp was started on UNIX with the command line ;; (we assume the mlisp executable is in a directory ;; included in the PATH environment variable): % mlisp -qq -- init 5 safe (sys:command-line-argument-count :application t) RETURNS 4 (sys:command-line-argument-count) ;; :application defaults to T RETURNS 4 (sys:command-line-arguments) RETURNS ("mlisp" "init" "5" "safe") ;; or perhaps (/usr/local/acl70/mlisp init 5 safe) ;; assuming mlisp is in /usr/local/acl70/: the directory ;; may or may not be included. (sys:command-line-argument 0) RETURNS "mlisp" ;; or perhaps "/usr/local/acl70/mlisp" (sys:command-line-argument 1) RETURNS "init" (sys:command-line-argument 2) RETURNS "5" (sys:command-line-argument 3) RETURNS "safe" (sys:command-line-argument 4) ERROR ;; the first argument to sys:command-line-argument ;; must be less than the number of arguments ;; as returned by sys:command-line-argument-count ;; Lisp was started on WINDOWS with the command line % mlisp.exe +co -qq -- init 5 safe ;; The values returned by the command-line argument functions are the ;; same as on UNIX (except "mlisp.exe" or ;; "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or ;; "/usr/local/acl70/mlisp".
All arguments except those beginning with + are considered
command-line arguments by these functions when
application is nil
. That
includes the executable name (number 1 in the list above), the -
arguments and their values (number 3 in the list above), the double
dash (number 4 in the queue above), and arguments which follow the
double dash (number 5 in the list above). Consider that those
arguments are collected as strings in a list called the
list-of-arguments
. When
application is nil
, the
command-line argument information functions behave as follows:
list-of-arguments
. It is an error to specify a
value for n equal to or greater than the length of
list-of-arguments
. Note the + arguments are ignored
and will not be returned for any value of n. The
double dash, if present, is considered and will be returned for some
value of n.
list-of-arguments
. Note the +
arguments are ignored and thus not included, while the double dash, if
present, is included.
list-of-arguments
. Note the +
arguments are ignored and thus not counted, while the double dash is
counted as an argument.
;; Lisp was started on UNIX with the command line ;; (we assume the mlisp executable is in a directory ;; included in the PATH environment variable): % mlisp -qq -- init 5 safe (sys:command-line-argument-count :application nil) RETURNS 6 (sys:command-line-arguments :application nil) RETURNS ("mlisp" -qq -- "init" "5" "safe") ;; or perhaps (/usr/local/acl70/mlisp -qq -- init 5 safe) ;; assuming mlisp is in /usr/local/acl70/: the directory ;; may or may not be included. (sys:command-line-argument 0) RETURNS "mlisp" ;; or perhaps "/usr/local/acl70/mlisp" (sys:command-line-argument 1) RETURNS "-qq" (sys:command-line-argument 2) RETURNS "--" (sys:command-line-argument 3) RETURNS "init" (sys:command-line-argument 4) RETURNS "5" (sys:command-line-argument 5) RETURNS "safe" (sys:command-line-argument 6) ERROR ;; the first argument to sys:command-line-argument ;; must be less than the number of arguments ;; as returned by sys:command-line-argument-count ;; Lisp was started on WINDOWS with the command line % mlisp.exe +co -qq -- init 5 safe ;; The values returned by the command-line argument functions are the ;; same as on UNIX (except "mlisp.exe" or ;; "C:\\Program Files\\acl70\\mlisp.exe" replaces "mlisp" or ;; "/usr/local/acl70/mlisp". The command-line argument functions ;; always ignore the + arguments.
If the Allegro CL image was created with dumplisp (or build-lisp-image or generate-application) with the
ignore-command-line-arguments argument
true (the default is nil
), then arguments are not processed by Allegro CL
when it starts up and all arguments (regardless of whether a `--'
appears on the command line) are handled by these functions and the
value of the application keyword argument has no
effect.
The system may tack on arguments in addition to those you
specified. In particular, when using the Emacs-Lisp interface, the
arguments -e (start-emacs-lisp-interface t)
may be
added (to start in connection between Lisp and Emacs). Do not be
surprised is you see these additional arguments. The system never adds
arguments after a -- (double dash).
Note that the zeroth argument is the name of the executable as entered in the command line, with or without path information. That is, the 0th argument may be, say, "mlisp" (without path information) or may be, say, "/usr/local/acl70/mlisp" (with path information). If path information is not provided and you need it, evaluating
(translate-logical-pathname (concatenate 'string "sys:" (sys:command-line-argument 0)))
will typically work. (But that form signals an error when path information is provided.)
You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in the initialization file .clinit.cl) which takes some action (such as loading specific files) based on the values of the arguments. Recall again that + arguments are ignored and so their presence or absence cannot be used to affect behavior once Lisp has started.
This function and its relatives, command-line-argument and command-line-argument-count, provide
information about the command line that invoked Allegro CL. Their
behavior depends on the value of the application
keyword argument. If the value of that argument is true (the default
is t), only the executable name and arguments appearing after the
first occurrence of `--', if there is one, in the command line are
considered. If the value of application is
nil
, all arguments except those beginning
with +, but including the `--', if there is one, are included.
As said above, + arguments, which are Windows specific and affect how the executable starts up on Windows, are discarded and not included in the information returned by this or any of the command-line argument functions.
See with-command-line-arguments, which is a macro that can be used to process command-line arguments. See Command line arguments in startup.htm for a list of command-line arguments accepted by Allegro CL.
command-line-argument returns the nth item on the command line. The item numbering is zero-based. If the value of the application keyword argument is true (the default), only the image name and the arguments after (and not including) the first occurrence of `--' in the command line are counted. If the value of application is nil, all arguments including the `--' are included. The executable name is argument 0. The argument is returned as a string.
command-line-arguments returns a list of strings indicating the arguments appearing on the command line used to start Allegro CL. If the value of the application keyword argument is true (the default), only the image name and the arguments appearing after the first occurrence of `--' are included. If the value of application is nil, all arguments including the `--', if there is one, are included.
command-line-argument-count returns the number of arguments on the Allegro CL command line. If the value of the application keyword argument is true (the default), only the image name and the arguments appearing after the first occurrence of `--', if there is one, are counted. If the value of application is nil, all arguments, including the `--', if there is one, are counted.
If the Allegro CL image was created with
dumplisp
(or
build-lisp-image
or
generate-application) with the
ignore-command-line-arguments argument
true (the default is
nil
),
then no argument is processed by Allegro
CL when it starts up and all arguments (regardless of whether a `--'
appears on the command line) are handled by these functions and the
value of the application keyword argument has no
effect.
The purpose of these functions is to allow you to customize the running of Lisp when the image is invoked. As a simple example, suppose you invoke Lisp (the example is on Windows) as follows:
mlisp.exe -qq -- foo -batch bar
Here, mlisp.exe is the name of the Allegro CL executable. No -I argument is specified (but one is inserted by the system) so the image is mlisp.dxl in the same directory as mlisp.exe. Note first that Lisp will not run in batch mode since the -batch appears after `--'. However, no initialization file will be read since the -qq argument appears before the `--'.
Here is what the various command line functions return given that command line:
(sys:command-line-arguments :application nil) [returns] ("C:\\Program Files\\acl70\\mlisp.exe" "-I" "C:\\Program Files\\acl70\\mlisp.dxl" "-qq" "--" "foo" "-batch" "bar") (sys:command-line-argument 0) [returns] "C:\\Program Files\\acl70\\mlisp.exe" (sys:command-line-argument 1) [returns] "foo" (sys:command-line-argument 3 :application nil) [returns] "-qq" (sys:command-line-arguments) [returns] ("C:\\Program Files\\acl70\\mlisp.exe" "foo" "-batch" "bar") (sys:command-line-argument-count) [returns] 4 (sys:command-line-argument-count :application nil) [returns] 8
Note that the zeroth argument is the name of the executable as entered in the command line, with or without (in the example, with) path information. If the path information is not provided and you need it, evaluating
(translate-logical-pathname (concatenate 'string "sys:" (sys:command-line-argument 0)))
will typically work.
You may use this information as you see fit. One possible use, for example, is to have some function defined and run (perhaps in the initialization file .clinit.cl) which takes some action (such as loading specific files) based on the values of the arguments.
Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |