3 @c user.texi --- User manual
5 @c Copyright (C) 2010, 2011, 2012 Didier Verna.
7 @c Author: Didier Verna <didier@lrde.epita.fr>
8 @c Maintainer: Didier Verna <didier@lrde.epita.fr>
10 @c This file is part of Clon.
12 @c Permission to use, copy, modify, and distribute this software for any
13 @c purpose with or without fee is hereby granted, provided that the above
14 @c copyright notice and this permission notice appear in all copies.
16 @c THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
17 @c WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
18 @c MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
19 @c ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
20 @c WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
21 @c ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
22 @c OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
27 @c Contents management by FCM version 0.1.
30 @c ====================================================================
32 @c ====================================================================
34 @setfilename clon-user.info
35 @settitle The Clon User Manual
37 @documentencoding ISO-8859-1
42 @c ====================================================================
44 @c ====================================================================
45 @set VERSION 1.0 beta 20 "Michael Brecker"
46 @set COPYRIGHT_DATE 2010, 2011, 2012
47 @setchapternewpage odd
48 @setcontentsaftertitlepage
50 The Clon User Manual for version @value{VERSION}.
51 @end documentdescription
55 @c ====================================================================
57 @c ====================================================================
96 @option{--clon-\name\}
100 @c --------------------------------
101 @c Manuals cross-referencing macros
102 @c --------------------------------
103 @c The following 3 macros are here to circumvent the info filenames
104 @c changes, when referencing the end-user manual:
106 @macro pxenduserref{node}
108 @pxref{\node\, , , clon-enduser, The Clon End-User Manual}
111 @pxref{\node\, , , enduser, The Clon End-User Manual}
115 @macro xenduserref{node}
117 @xref{\node\, , , clon-enduser, The Clon End-User Manual}
120 @xref{\node\, , , enduser, The Clon End-User Manual}
124 @macro enduserref{node}
126 @ref{\node\, , , clon-enduser, The Clon End-User Manual}
129 @ref{\node\, , , enduser, The Clon End-User Manual}
143 @cindex @t{--clon-\opt\}
144 @cindex Built-In Options, @t{--clon-\opt\}
145 @cindex Options, built-in, @t{--clon-\opt\}
148 @c Common option properties
149 @macro copindex{prop}
150 @cindex Options, common properties, @t{\prop\}
151 @cindex Common Option Properties, @t{\prop\}
155 @c #### NOTE: not an alias because of argument syntax.
156 @macro oindex{name,class}
157 @cindex \name\ (@t{\class\})
158 @cindex Options, \name\ (@t{\class\})
163 @macro voindex{name,class}
164 @cindex \name\ (@t{\class\})
165 @cindex Valued Options, \name\ (@t{\class\})
166 @cindex Options, valued, \name\ (@t{\class\})
170 @c Common valued option properties
171 @macro cvopindex{prop}
172 @cindex Valued Options, common properties, @t{\prop\}
173 @cindex Common Valued Option Properties, @t{\prop\}
174 @cindex Options, valued, common properties, @t{\prop\}
177 @c Valued option properties
178 @macro vopindex{name,class,prop}
179 @cindex \name\ (@t{\class\}), properties, @t{\prop\}
180 @cindex Valued Options, \name\ (@t{\class\}), properties, @t{\prop\}
181 @cindex Options, valued, \name\ (@t{\class\}), properties, @t{\prop\}
184 @c Configuration options
186 @vindex com.dvlsoft.clon.configuration
187 @cindex Configuration Option, @t{\name\}
196 @macro foindex{func,opt}
197 @findex \func\@r{, options, }\opt\
201 @macro fiindex{func,item}
202 @findex \func\@r{, items, }\item\
206 @macro fkindex{func,key}
207 @findex \func\@r{, keys, }\key\
211 @macro fiaindex{func,arg}
212 @findex \func\@r{, initargs, }\arg\
215 @c Generic functions sub-index
216 @macro gfsubindex{func}
217 @findex @r{Generic Functions, }\func\
226 @c Generic function methods
227 @macro gfmindex{func,method}
228 @findex \func\@r{, methods, }\method\
229 @findex @r{Generic Functions, }\func\@r{, methods, }\method\
232 @c #### FIXME: I need this because when using @defun, the function is
233 @c referenced directly but not under the Constructors sub-index. This
234 @c sucks because what I would like is the ability to define my own
235 @c @defXXX macros, which apparently I can't. Besides, doing this
236 @c produces 2 separate index entries, instead of only one with two pagerefs.
237 @c This problem stands for @gfsubindex (see above), @rfsubindex (see
238 @c below) and @ecsubindex (see below) as well.
239 @c Constructor functions sub-index
240 @macro cfsubindex{func}
241 @findex @r{Constructors, }\func\
244 @c Constructor functions
250 @c Constructor function initargs
251 @macro cfiaindex{func,arg}
252 @fiaindex{\func\, \arg\}
253 @findex @r{Constructors, }\func\@r{, initargs, }\arg\
256 @c Reader functions subindex
257 @macro rfsubindex{func}
258 @findex @r{Readers, }\func\
271 @c Environment variables
274 @vindex @r{Environment, }\var\
277 @c Built-in environment variables
278 @macro bievindex{var}
289 @tpindex @r{Classes, }\cls\
293 @macro clssindex{cls,slot}
294 @tpindex \cls\@r{, slots, }\slot\
295 @tpindex @r{Classes, }\cls\@r{, slots, }\slot\
299 @macro clsiaindex{cls,arg}
300 @tpindex \cls\@r{, initargs, }\arg\
301 @tpindex @r{Classes, }\cls\@r{, initargs, }\arg\
307 @tpindex @r{Option Classes, }\cls\
310 @c Error conditions subindex
311 @macro ecsubindex{cond}
312 @tpindex @r{Error Conditions, }\cond\
321 @c Error condition slots
322 @macro ecsindex{cond,slot}
323 @tpindex \cond\@r{, slots, }\slot\
324 @tpindex @r{Error Conditions, }\cond\@r{, slots, }\slot\
328 @macro pkgindex{name}
330 @tpindex @r{Packages, }\name\
334 @macro sysindex{name}
336 @tpindex @r{Systems, }\name\
341 @c ====================================================================
342 @c Info Category and Directory
343 @c ====================================================================
344 @dircategory Common Lisp
346 * Clon User: (clon-user). The Clon User Manual.
351 @c ====================================================================
353 @c ====================================================================
356 Copyright @copyright{} @value{COPYRIGHT_DATE} Didier Verna
358 Permission is granted to make and distribute verbatim copies of this
359 manual provided the copyright notice and this permission notice are
360 preserved on all copies.
363 Permission is granted to process this file through TeX and print the
364 results, provided the printed document carries a copying permission
365 notice identical to this one except for the removal of this paragraph
366 (this paragraph not being relevant to the printed manual).
369 Permission is granted to copy and distribute modified versions of this
370 manual under the conditions for verbatim copying, provided also that the
371 section entitled ``Copying'' is included exactly as in the original.
373 Permission is granted to copy and distribute translations of this manual
374 into another language, under the above conditions for modified versions,
375 except that this permission notice may be translated as well.
381 @c ====================================================================
383 @c ====================================================================
385 @title The Clon User Manual
386 @subtitle The @CmdLine{} Options Nuker, Version @value{VERSION}
389 @author Didier Verna <@email{didier@@lrde.epita.fr}>
391 @vskip 0pt plus 1filll
394 @hfill Cover art by Alexis Angelidis.
399 @c ====================================================================
401 @c ====================================================================
406 @c ====================================================================
408 @c ====================================================================
410 @node Top, Copying, (dir), (dir)
411 @top The Clon User Manual
413 This is the @clon{} User Manual for @clon{} version @value{VERSION}:
414 it explains how to use @clon{} in your application.
417 * Copying:: The BSD license
418 * Introduction:: What Clon is all about
419 * Installation:: Library, documentation and sample code
420 * Quick Start:: For the brave and the impatient
421 * Using Clon:: Clonificating your application
422 * Extending Clon:: Creating your own option types
423 * Advanced Usage:: Things rarely needed
424 * Conclusion:: That's all folks
425 * Technical Notes:: Configuration, platforms and portability
426 * API Quick Reference:: The Complete protocols
427 * Indexes:: Concept, Function and Variable
428 * Acknowledgments:: Hall of Pride
436 @c ====================================================================
438 @c ====================================================================
439 @node Copying, Introduction, Top, Top
443 Permission to use, copy, modify, and distribute this software for any
444 purpose with or without fee is hereby granted, provided that the above
445 copyright notice and this permission notice appear in all copies.
447 THIS SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
448 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
449 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
450 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
451 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
452 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
453 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
458 @c ====================================================================
460 @c ====================================================================
461 @node Introduction, Installation, Copying, Top
462 @chapter Introduction
464 @clon{} is a library for managing @cmdline{} options in standalone @cl{}
465 applications. It provides a unified option syntax with both short and
466 long names, automatic completion of partial names and automatic
467 retrieval/conversion of option arguments from the @cmdline{}, associated
468 environment variables, fallback or default values. @clon{} comes with a
469 set of extensible option types (switches, paths, strings @etc{}).
470 @clon{} also provides automatic generation and formatting of help
471 strings, with support for highlighting on @tty{}'s through ISO/IEC 6429
472 SGR. This formatting is customizable through @emph{themes}.
474 Depending on the target audience, @clon{} stands for either ``The
475 @CmdLine{} Options Nuker'' or ``The @cl{} Options Nuker''. @clon{} also
476 has a recursive acronym: ``@clon{} Likes Options Nuking'', and a reverse
477 one: ``Never Omit to Link with @clon{}''. Other possible expansions of
478 the acronym are still being investigated.
480 This manual is for the @clon{} @emph{user}, that is, the developer of a
481 @cl{} application who wants to use @clon{} for @cmdline{} option
482 management@footnote{An application using @clon{} for its @cmdline{}
483 option management is said to be @emph{clonified}. It is also possible to
484 say @emph{clonfiscated}. However, we advise against using
485 @emph{clonistified}. The term @emph{clonificated} is also considered bad
486 style, and the use of @emph{clonificationated} is strictly prohibited.}.
487 As opposed to the user of the @emph{library}, the user of an
488 @emph{application} powered by @clon{} is called an @emph{end-user}.
489 @clon{} provides both a user manual (this one) and an end-user manual
490 (@pxenduserref{Top}). Everybody should read the end-user manual first.
492 @ref{Quick Start} provides a very short example in order to give an
493 overview of what's coming next. @ref{Using Clon} explains in detail how
494 to clonify your application, and @ref{Extending Clon} describe how to
495 extend @clon{} with your own option types.
499 @c ====================================================================
501 @c ====================================================================
502 @node Installation, Quick Start, Introduction, Top
503 @chapter Installation
504 @clon{} currently works on Unix platforms (MacOS X included) with SBCL,
505 CMUCL, CCL, ECL, CLISP and ABCL. @clon{} is provided as an ASDF 2
506 system, but has no mandatory dependency. CFFI may optionally be used
507 with CLISP. @xref{Supported Platforms}, for more information.
509 In addition to the library itself, the Clon distribution offers
510 documentation in the form of 3 different manuals, some data files that
511 are needed for it to work properly, and a couple of demonstration
512 programs. Because of that, some bits of manual installation are needed.
514 After unpacking somewhere in the ASDF 2 source registry, please perform
515 the following steps, in order.
519 Edit @file{Makefile.cnf} to your specific needs.
522 Type @command{make} to compile the documentation and the demo programs
523 (end-user manual, user manual and possibly reference manual). By
524 default, the documentation is built in info, PDF and HTML formats. If
525 you want other formats (DVI and PostScript are available), type
526 @command{make all-formats}. You can also type individually @command{make
527 dvi} and/or @command{make ps} in order to get the corresponding format.
530 As documented in @file{Makefile.cnf}, the reference manual is only
531 generated if you have SBCL and the Declt library at hand (see
532 @uref{http://www.lrde.epita.fr/~didier/software/lisp/misc.php#declt}).
535 Type @command{make install} to install both the documentation and the
536 data files. If you have compiled the documentation in DVI and PostScript
537 format, those will be installed as well. The same goes for the reference
538 manual. The demo programs are not installed anywhere.
541 Type @command{make uninstall} to uninstall the library.
545 @c ====================================================================
547 @c ====================================================================
548 @node Quick Start, Using Clon, Installation, Top
550 In this chapter, we assume that you have properly installed @clon{}
551 (@pxref{Technical Notes}), and we build a very short program to get you
552 started. Let's call it @file{quickstart.lisp}.
555 * Full Source:: The complete source code
556 * Explanation:: Step-by-step code walking
563 @node Full Source, Explanation, Quick Start, Quick Start
565 For cut'n paste convenience, the complete source code is given below.
566 For a slightly longer example, have a look at the demonstration program
567 called @file{simple} in the distribution.
571 (in-package :cl-user)
574 (asdf:load-system :com.dvlsoft.clon)
575 (use-package :com.dvlsoft.clon)
577 (defsynopsis (:postfix "FILES...")
578 (text :contents "A very short program.")
579 (group (:header "Immediate exit options:")
580 (flag :short-name "h" :long-name "help"
581 :description "Print this help and exit.")
582 (flag :short-name "v" :long-name "version"
583 :description "Print version number and exit.")))
586 "Entry point for our standalone application."
588 (when (getopt :short-name "h")
591 (do-cmdline-options (option name value source)
592 (print (list option name value source)))
596 (dump "quickstart" main)
604 @node Explanation, , Full Source, Quick Start
606 Let's examine this program step-by-step now.
608 @pkgindex{com.dvlsoft.clon}@c
609 @sysindex{com.dvlsoft.clon}@c
610 First, we put ourselves in the @cl{} user package, and load @clon{} from
611 its ASDF system @samp{com.dvlsoft.clon}. Next, we use the @clon{}
612 package, also named @samp{com.dvlsoft.clon}.
616 (in-package :cl-user)
619 (asdf:load-system :com.dvlsoft.clon)
620 (use-package :com.dvlsoft.clon)
624 In fact, using the @clon{} package directly is done here for simplicity,
625 but is not recommended. In case you find the package name too long to
626 prefix every symbol with, @clon{} provides a utility function that
627 allows you to add (and use) a shorter nickname instead (the
628 demonstration programs in the distribution show how to use it):
630 @cindex Package, nicknames
631 @defun nickname-package &optional NICKNAME
632 Add NICKNAME (:CLON by default) to the :COM.DVLSOFT.CLON package.
638 @cindex Text, in synopsis
639 @cindex Options, in synopsis
640 @cindex Groups, in synopsis
642 The next thing you want to do is to create a set of options, groups or
643 texts that your application will recognize and/or display in its help
644 string. The structure of your @cmdline{} is known to @clon{} as the
645 @dfn{synopsis}. In order to create it, use the macro @code{defsynopsis}.
647 @foindex{defsynopsis,:postfix}
648 @fiindex{defsynopsis,text}
649 @fiindex{defsynopsis,options}
650 @fiindex{defsynopsis,group}
653 (defsynopsis (:postfix "FILES...")
654 (text :contents "A very short program.")
655 (group (:header "Immediate exit options:")
656 (flag :short-name "h" :long-name "help"
657 :description "Print this help and exit.")
658 (flag :short-name "v" :long-name "version"
659 :description "Print version number and exit.")))
663 Note that the synopsis has a double role: it not only serves to define
664 the options recognized by your application, but also the order in which
665 every element appears in the help string. In that particular example, we
666 define a line of text and a group with a header and two flags.
669 @cfindex{make-context}
670 Now, we are going to define a function @code{main} for our standalone
671 application. The first thing that we need to do is create a
672 @dfn{context}. A context is an object that @clon{} uses to store various
673 things, including some state related to the parsing of the @cmdline{}.
674 You create a context with the function @code{make-context}.
679 "Entry point for our standalone application."
684 @cindex Options Retrieval, explicit
685 @cindex Retrieval, of options, explicit
687 @cindex Help String, display
689 At that point, @clon{} is ready to retrieve the options you want from
690 the @cmdline{}. Let's first see if the user has called the option
691 @option{-h}, and give him the help string. Option retrieval is done with
692 the function @code{getopt}, and automatic help string output with the
693 function @code{help}. Note that what we do here is @emph{not} process
694 the @cmdline{} in sequence, but look directly for a specific option by
695 name (this retrieval method is said to be @dfn{explicit}).
697 @fkindex{getopt,:short-name}
700 (when (getopt :short-name "h")
707 The @code{exit} function is a wrapper around an
708 implementation-dependent way to exit (shall I say quit?) the @cl{}
709 environment, hence the program. It takes an optional argument that
710 stands for the exit status.
712 @cindex Options Retrieval, sequential
713 @cindex Retrieval, of options, sequential
714 @findex do-cmdline-options
715 And now, we are going to retrieve the other options and simply print
716 them. This time however, we process the @cmdline{} sequentially (so this
717 retrieval method is said to be @dfn{sequential}). This is done with the
718 @code{do-cmdline-options} macro. We also close the @code{main} function.
722 (do-cmdline-options (option name value source)
723 (print (list option name value source)))
729 Finally, time to save the Lisp image.
735 (dump "quickstart" main)
739 The first argument to @code{dump} is the name of the executable to
740 produce, and the second argument is the name of the function to call
741 automatically at startup.
743 In order to get a standalone executable from this program, all you need
744 to do now is to type @samp{CC=gcc sbcl --script quickstart.lisp}. Note
745 that the actual way of dumping executables is compiler-dependent. For
746 more information on the proper way to do it and on the compilers
747 currently supported, see @ref{Dumping Executables}.
751 @c ====================================================================
753 @c ====================================================================
754 @node Using Clon, Extending Clon, Quick Start, Top
757 Using @clon{} in your application is a two stages process. In phase 1,
758 you create a @dfn{synopsis}, which is a description of your
759 application's @cmdline{} and a @dfn{context}, which describes this
760 specific execution of the program. In phase 2, you retrieve the option
761 values and possibly display help strings. Phase 1 is called the
762 @dfn{initialization phase}, while phase 2 is called the @dfn{runtime
766 * Synopsis Definition:: Describing your command-line
767 * Context Creation:: Instantiating your command-line
768 * Integrity Checks:: Verifying the Clon semantics
769 * Option Retrieval:: Getting the options values
770 * Help:: Generating the help string
774 @c -------------------
775 @c Synopsis Definition
776 @c -------------------
777 @node Synopsis Definition, Context Creation, Using Clon, Using Clon
778 @section Synopsis Definition
780 @cindex Initialization Phase
781 @cindex Phase, initialization
784 Step one of the @clon{} initialization phase consists in defining a
785 @dfn{synopsis}. A synopsis is essentially a description of your
786 application's @cmdline{}: it describes what are the available options,
787 whether your application has a postfix @etc{} The synopsis, however,
788 plays a second role: it also describes the contents of your
789 application's help string. When you create a synopsis, you describe the
790 @cmdline{} and the help string at the same time.
793 * Synopsis Items:: Defsynopsis and its contents
794 * Built-In Option Types:: The exhaustive list
795 * Advanced Synopsis Creation:: The non-declarative way
798 @node Synopsis Items, Built-In Option Types, Synopsis Definition, Synopsis Definition
799 @subsection Synopsis Items
800 Look again at the synopsis definition provided in @ref{Quick Start}.
804 (defsynopsis (:postfix "FILES...")
805 (text :contents "A very short program.")
806 (group (:header "Immediate exit options:")
807 (flag :short-name "h" :long-name "help"
808 :description "Print this help and exit.")
809 (flag :short-name "v" :long-name "version"
810 :description "Print version number and exit.")))
814 You define a synopsis with the @code{defsynopsis} macro.
816 @defmac defsynopsis ([OPTIONS@dots{}]) ITEMS@dots{}
817 Define a new synopsis and return it. @var{OPTIONS} are key/value pairs.
818 @var{ITEMS} are text, group or option descriptions.
820 The following @var{OPTIONS} are currently available.
824 @foindex{defsynopsis,:postfix}@c
825 @cindex Command-Line, remainder
826 @cindex Remainder, of command-line
827 A string which will appear at the end of the synopsis line in the help
828 string. When you provide a postfix, you also implicitely tell @clon{}
829 that your application accepts non-option arguments at the end of the
830 @cmdline{} (this is called the @dfn{remainder} of the @cmdline{}). See
831 @enduserref{Option Separator} for more information on the behavior of
832 @clon{} with respect to postfixes. Also, see @ref{Command-Line
833 Remainder} on how to access the @cmdline{} remainder.
837 We now examine the syntax for each possible @var{ITEM}.
839 * Text:: Adding arbitrary text
840 * Options:: Adding options
841 * Groups:: Adding groups
844 @node Text, Options, Synopsis Items, Synopsis Items
847 @cindex Text, in synopsis
848 @fiindex{defsynopsis,text}
849 In order to add arbitrary text to your help string, use the following
853 @t{(text} [@var{OPTIONS@dots{}}]@t{)}
855 @var{OPTIONS} are key/value pairs. The following @var{OPTIONS} are
859 @cindex Text, contents
860 The actual text string. Try to make proper sentences when adding
861 arbitrary text. You can use explicit newline characters in your text if
862 you really want to go next line, but in general, you should not worry
863 about the formatting because the themes are here to do so. In
864 particular, don't finish your text with a newline. This would break
865 potential theme specifications.
870 When non-@code{nil}, the text won't appear in the help string. Hidden
871 texts can still be displayed individually though (@pxref{Help}).
874 @node Options, Groups, Text, Synopsis Items
875 @subsubsection Options
877 @cindex Options, in synopsis
878 @fiindex{defsynopsis,options}
879 In order to add an option to your help string, you must provide a list
880 beginning with the option type and followed by key/value pairs
881 describing the option's properties. For instance, to add a flag with a
882 short name and a description, you could do this:
885 (flag :short-name "h" :description "Print this help and exit.")
888 Option properties vary depending on the option type. The exact list of
889 available option types, and the corresponding properties are described
890 in @ref{Built-In Option Types}.
892 @node Groups, , Options, Synopsis Items
893 @subsubsection Groups
895 @cindex Groups, in synopsis
896 @fiindex{defsynopsis,group}
897 In order to add a group to your help string, use the following form:
900 @t{(group} ([@var{OPTIONS@dots{}}]) @var{ITEMS@dots{}}@t{)}
902 @cindex Text, in groups
903 @cindex Options, in groups
904 @cindex Groups, in groups
905 @var{OPTIONS} are key/value pairs. @var{ITEMS} simply are arbitrary
906 text, option or sub-group descriptions as we've just seen.
908 The following @var{OPTIONS} are currently available.
912 @cindex Header, in group
913 @foindex{defgroup,:header}@c
914 A string which will be displayed above the group's contents in the help
915 string. The same formatting recommendations as for arbitrary text apply
918 @cindex Hidden Groups
919 @cindex Groups, hidden
920 @foindex{defgroup,:hidden}@c
922 @cindex Built-In Groups
923 @cindex Groups, built-in
925 When non-@code{nil}, the group won't appear in the help string. Hidden
926 groups can still be displayed individually though (@pxref{Help}). For
927 instance, the @clon{} built-in group is hidden in the regular help
928 string, but the @bioption{help} option still displays it individually.
931 @node Built-In Option Types, Advanced Synopsis Creation, Synopsis Items, Synopsis Definition
932 @subsection Built-In Option Types
933 @cindex Built-In Option Types
934 @cindex Options, built-in types
935 @cindex Option Types, built-in
936 In this section, we will review all the built-in option types that
937 @clon{} provides, along with their corresponding properties. You can use
938 them directly in your synopsis description. For adding personal option
939 types to @clon{}, see @ref{New Option Types}.
942 * Common Properties:: For all options
943 * Flags:: Built-in options without arguments
944 * Common Valued Option Properties:: For all valued options
945 * Built-In Valued Options:: Built-in options with arguments
948 @node Common Properties, Flags, Built-In Option Types, Built-In Option Types
949 @subsubsection Common Properties
950 @cindex Options, common properties
951 @cindex Common Option Properties
953 All option types in @clon{}, including those you define yourself
954 (@pxref{New Option Types}), have a set of basic, common properties. Here
959 @copindex{:short-name}
960 The option's short name. A string or @code{nil}.
962 @copindex{:long-name}
963 The option's long name. A string or @code{nil}.
965 @copindex{:description}
966 The option's descriptive text. A string or @code{nil}. The same
967 formatting recommendations as for arbitrary text apply (@pxref{Text}).
970 The option's associated environment variable. A string or @code{nil}.
973 @cindex Hidden Options
974 @cindex Options, hidden
976 When non-@code{nil}, the option won't appear in the help string. Hidden
977 options can still be displayed individually though (@pxref{Help}).
980 Note that an option is required to have at least one name (either short
981 or long). Non-@code{nil} but empty names are also prohibited, and of
982 course, a short name cannot begin with a dash (otherwise, it would be
983 mistaken for a long name, but did I really need to mention this?).
985 @node Flags, Common Valued Option Properties, Common Properties, Built-In Option Types
988 In @clon{}, options that don't take any argument are of type
989 @code{flag}. These options don't provide additional properties on top of
990 the common set described in @ref{Common Properties}. All properties
991 default to @code{nil}.
993 @node Common Valued Option Properties, Built-In Valued Options, Flags, Built-In Option Types
994 @subsubsection Common Valued Option Properties
995 @cindex Valued Options
996 @cindex Options, valued
997 @clsindex{valued-option}
998 All non-flag options in @clon{} are said to be @dfn{valued}. All valued
999 options, including those you define yourself (@pxref{New Option Types}),
1000 share a set of additional properties. Here is a list of them.
1002 @cindex Valued Options, common properties
1003 @cindex Common Valued Option Properties
1004 @cindex Options, valued, common properties
1006 @item :argument-name
1007 @cvopindex{:argument-name}
1008 The name of the option's argument, as it appears in the help string. It
1009 defaults to @code{"ARG"}, so that for instance, a @samp{name} option
1010 would appear like this: @samp{--name=ARG}.
1011 @item :argument-type
1012 @cvopindex{:argument-type}
1013 The status of the argument. Possible values are @code{:required} (the
1014 default) and @code{:mandatory} which are synonyms, or @code{:optional}.
1015 @item :fallback-value
1016 @cvopindex{:fallback-value}
1017 @cindex Values, source, fallback
1018 @item :default-value
1019 @cvopindex{:default-value}
1020 @cindex Values, source, default
1021 The option's fallback and default values. Remember that a fallback value
1022 only makes sense when the argument is optional. Besides, also when the
1023 argument is optional, you need to provide at least a fallback or a
1024 default value (or both of course; see @enduserref{Value Sources}).
1027 @node Built-In Valued Options, , Common Valued Option Properties, Built-In Option Types
1028 @subsubsection Built-In Valued Options
1029 @cindex Option Types, valued
1030 @cindex Built-In Option Types, valued
1031 @cindex Options, built-in types, valued
1032 @cindex Option Types, built-in, valued
1033 @clon{} currently defines 6 built-in valued option types. These option
1034 types may change the default value for some common properties, and / or
1035 provide additional properties of their own. All of this is described
1040 @voindex{Strings,stropt}@c
1041 @cvopindex{:argument-name}@c
1042 This option type is for options taking strings as their argument. String
1043 options don't provide any additional properties, but their default
1044 argument name is changed from @code{"ARG"} to @code{"STR"}.
1046 @voindex{Lisp Objects,lispobj}@c
1047 @cvopindex{:argument-name}@c
1048 @vopindex{Lisp Objects,lispobj,:typespec}@c
1049 @bioindex{line-width}@c
1050 This option type is for options taking any kind of Lisp object as their
1051 argument. @code{lispobj} options change their default argument name from
1052 @code{"ARG"} to @code{"OBJ"}. Also, they provide an additional property
1053 called @code{:typespec} which must be a @cl{} type specifier that the
1054 argument must satisfy. It defaults to @code{t}. Look at the
1055 @bioption{line-width} built-in option for an example.
1057 @voindex{Enumerations,enum}@c
1058 @cvopindex{:argument-name}@c
1059 @vopindex{Enumerations,enum,:enum}@c
1060 @bioindex{version}@c
1061 This option type is for options taking values from an enumerated set of
1062 keywords. @code{enum} options change their default argument name from
1063 @code{"ARG"} to @code{"TYPE"}. Also, they provide an additional property
1064 called @code{:enum} to store the list of @cl{} keywords enumerating the
1065 possible values. The end-user does not use a colon when providing an
1066 argument to an @code{enum} option. Only the keyword's name. The end-user
1067 also has the ability to abbreviate the possible values. An empty
1068 argument is considered as an abbreviation for the first element in the
1069 set. Look at the @bioption{version} built-in option for an example.
1071 @bioindex{search-path}@c
1073 @voindex{Paths,path}@c
1074 @cvopindex{:argument-name}@c
1075 @vopindex{Paths,path,:type}@c
1076 This option type is for options taking a colon-separated list of
1077 pathnames as argument. @code{path} options change their default argument
1078 name from @code{"ARG"} to @code{"PATH"}. Also, they provide an
1079 additional property called @code{:type} which specifies the kind of path
1080 which is expected. Possible values are: @code{:file}, @code{:directory},
1081 @code{:file-list}, @code{:directory-list} or @code{nil} (meaning that
1082 anything is allowed). Null paths are allowed, and may be provided by an
1083 empty argument. Look at the @bioption{search-path} and
1084 @bioption{theme} built-in options for examples.
1086 @voindex{Switches,switch}@c
1087 @cvopindex{:argument-name}@c
1088 @cvopindex{:argument-type}@c
1089 @vopindex{Switches,switch,:argument-style}@c
1090 This option type is for Boolean options. @code{switch} options change
1091 their default argument type from required to optional and provide a
1092 fallback value of @code{t} automatically for optional arguments.
1093 @code{switch} options provide a new property called
1094 @code{:argument-style}. Possible values are @code{:yes/no} (the
1095 default), @code{:on/off}, @code{:true/false}, @code{:yup/nope},
1096 @code{:yeah/nah}. This property affects the way the argument name and
1097 true or false values are advertized in help strings. However, all
1098 possible arguments forms (@pxenduserref{Switches}) are always available
1101 @voindex{Extended Switches,xswitch}@c
1102 @cvopindex{:argument-name}@c
1103 @cvopindex{:argument-type}@c
1104 @vopindex{Extended Switches,xswitch,:argument-style}@c
1105 @vopindex{Extended Switches,xswitch,:enum}@c
1106 @bioindex{highlight}@c
1107 This option type stands for @dfn{extended} switch. Extended switches
1108 result from the mating of a male switch and a female enumeration, or the
1109 other way around (elementary decency prevents me from describing this
1110 mating process in detail): their possible values are either Boolean or
1111 from an @code{:enum} property as in the case of @code{enum} options. As
1112 simple switches, @code{xswitch} options change their default argument
1113 type from required to optional and provide a fallback value of @code{t}
1114 automatically for optional arguments. They also provide the
1115 @code{:argument-style} property. Contrary to switches, however, this
1116 property does not affect the argument name. It only affects the way true
1117 or false values are displayed in help strings. Look at the
1118 @bioption{highlight} built-in option for an example.
1121 @node Advanced Synopsis Creation, , Built-In Option Types, Synopsis Definition
1122 @subsection Advanced Synopsis Creation
1124 The fact that @code{defsynopsis} lets you define things in a
1125 @emph{declarative} way has not escaped you. Declarative is nice but
1126 sometimes it gets in the way, so it is time to see how things work under
1127 the hood. Every item in a synopsis is in fact implemented as an object
1128 (an instance of some class), so it turns out that @code{defsynopsis}
1129 simply is a convenience wrapper around the corresponding constructor
1130 functions for all such objects. Instead of using @code{defsynopsis}, you
1131 can then use those constructor functions explicitely.
1134 * Constructors:: The expansion of defsynopsis
1135 * Advantages:: Yes, but why?
1136 * Group Definition:: The declarative way
1139 @node Constructors, Advantages, Advanced Synopsis Creation, Advanced Synopsis Creation
1140 @subsubsection Constructors
1141 Let's have a look at the expansion of @code{defsynopsis} from the quick
1142 start example (@pxref{Quick Start}).
1144 The original code is like this:
1148 (defsynopsis (:postfix "FILES...")
1149 (text :contents "A very short program.")
1150 (group (:header "Immediate exit options:")
1151 (flag :short-name "h" :long-name "help"
1152 :description "Print this help and exit.")
1153 (flag :short-name "v" :long-name "version"
1154 :description "Print version number and exit.")))
1158 And once the macro is expanded, it will look like this:
1160 @cfindex make-synopsis
1164 @findex defsynopsis@r{, expansion}
1167 (make-synopsis :postfix "FILES..."
1168 :item (make-text :contents "A very short program.")
1169 :item (make-group :header "Immediate exit options:"
1170 :item (make-flag :short-name "h"
1172 :description "Print this help and exit.")
1173 :item (make-flag :short-name "v"
1174 :long-name "version"
1175 :description "Print version number and exit.")))
1179 As you can see, every synopsis element has a corresponding
1180 @code{make-@var{SOMETHING}} constructor, and the keywords used here and
1181 there in @code{defsyopsis} are in fact initargs to those constructors.
1182 We now examine those constructors in greater detail.
1184 @cindex Options, creation
1185 @defun make-text [@code{:hidden} BOOL] @code{:contents} STRING
1186 @cfsubindex{make-text}
1187 @cfiaindex{make-text,:contents}
1188 @cfiaindex{make-text,:hidden}
1189 Create an arbitrary text object, possibly hidden, whose contents is
1193 @c #### FIXME: I would like an environment without indexing here.
1194 @defun make-@var{OPTION} :INITARG INITVAL@dots{}
1195 @cfsubindex{make-@var{OPTION}}
1197 @cfindex make-stropt
1198 @cfindex make-lispobj
1201 @cfindex make-switch
1202 @cfindex make-xswitch
1203 Create a new @var{OPTION} object, @var{OPTION} being any built-in option
1204 type (@code{flag}, @code{stropt} @etc{}, see @ref{Built-In Valued
1205 Options}) or user-defined one (@pxref{New Option Types}). For a list of
1206 available initialization arguments (depending on the option type), see
1207 @ref{Built-In Option Types}.
1210 @defun make-group [@code{:header} STRING @code{:hidden} BOOL] @
1211 @code{:item} ITEM1 @code{:item} ITEM2@dots{}
1212 @cfsubindex{make-group}
1213 @cfiaindex{make-group,:header}
1214 @cfiaindex{make-group,:hidden}
1215 @cfiaindex{make-group,:item}
1217 Create a group object, possibly hidden, whose header is @var{STRING}.
1218 Every @var{ITEM} is an arbitrary text object, option object or group
1219 object. The order is important as it determines the display of the help
1223 @defun make-synopsis [@code{:postfix} STRING] @
1224 @code{:item} ITEM1 @code{:item} ITEM2@dots{}
1225 @cfsubindex{make-synopsis}
1226 @cfiaindex{make-synopsis,:postfix}
1227 @cfiaindex{make-synopsis,:item}
1229 Create a synopsis object whose postfix is @var{STRING}. Every @var{ITEM} is
1230 an arbitrary text object, option object or group object. The order is
1231 important as it determines the display of the help string.
1234 In fact, the @code{defsynopsis} macro allows you to freely mix
1235 declarative forms, constructor calls or whatever Lisp code you may want
1236 to use. The way this works is as follows: if a synopsis @var{ITEM}
1237 (@pxref{Synopsis Items}) is a list whose @code{car} is @code{text},
1238 @code{group}, or any option type (inluding those you define yourselves;
1239 see @ref{New Option Types}), then the @var{ITEM} is expanded as
1240 explained earlier. Otherwise, it is just left @emph{as-is}.
1242 To sum up, here's a example of things you can do in @code{defsynopsis}.
1246 (com.dvlsoft.clon:defsynopsis ()
1249 (setq *another-option* (com.dvlsoft.clon:make-switch #| ... |#)))
1254 @node Advantages, Group Definition, Constructors, Advanced Synopsis Creation
1255 @subsubsection Advantages
1257 So, why would you want to use constructors directly or mix declarative
1258 and imperative forms in @code{defsynopsis}? There are several reasons
1262 Some people prefer to declare (or should I say, create) their arbitrary
1263 texts, options and groups locally, in files, modules or ASDF components
1264 where they belong. In such a case, you need to keep references to the
1265 corresponding objects in order to compute the synopsis in the end.
1267 Since using constructors explicitely allows you to keep references to
1268 the created objects, these objects can be @emph{reused}. For instance,
1269 you can use the same text at different places, you can also use a single
1270 option several times, or even a single group several times so that its
1271 items appear in different places @etc{} Note that @clon{} knows its way
1272 around multiple occurrences of the same object: even if you use the same
1273 option object several times in a synopsis, @clon{} only maintains a
1274 single option definition.
1277 @node Group Definition, , Advantages, Advanced Synopsis Creation
1278 @subsubsection Group Definition
1279 There is one last point we need to address in order to complete this
1280 section. There might be times when you need to manipulate an explicit
1281 group object, but the object itself can still be created in a
1282 declarative (or mixed) way because you don't need to keep references on
1283 its items. For this, @clon{} provides a macro called @code{defgroup}.
1285 @defmac defgroup (OPTIONS@dots{}) ITEMS@dots{}
1286 @cindex Groups, in synopsis
1287 @fiindex{defsynopsis,group}
1288 @foindex{defgroup,:header}
1289 @foindex{defgroup,:hidden}
1290 Define a new group and return it. This macro behaves exactly like the
1291 @code{group} form in a call to @code{defsynopsis} (@pxref{Groups}). In
1292 fact, an intermediate step in the expansion of the @code{defsynopsis}
1293 macro is to transform @code{group} forms into @code{defgroup} macro
1294 calls. As for @code{defsynopsis}, @code{defgroup} allows you to mix
1295 declarative forms, constructor calls or any kind of Lisp code.
1303 @node Context Creation, Integrity Checks, Synopsis Definition, Using Clon
1304 @section Context Creation
1306 @cindex Initialization Phase
1307 @cindex Phase, initialization
1309 Step two of the @clon{} initialization phase consists in creating a
1310 @dfn{context}. A context is an object representing a particular instance
1311 of your program, for example (and most notably) with an actual
1312 @cmdline{} as the user typed it.
1315 * Making A Context:: The Constructor function
1316 * Contextual Information:: Interesting context slots
1319 @node Making A Context, Contextual Information, Context Creation, Context Creation
1320 @subsection Making A Context
1322 @cfindex{make-context}
1323 You create a context with the @code{make-context} function.
1326 @cfsubindex{make-context}
1327 Create a new context. That's it.
1330 @node Contextual Information, , Making A Context, Context Creation
1331 @subsection Contextual Information
1333 Once a context object is created, you have access to some interesting
1334 contextual information.
1337 * Program Name:: As it appear on the command-line
1338 * Command-Line Remainder:: The non-options part
1339 * Command-Line Polling:: Whether something is left
1342 @node Program Name, Command-Line Remainder, Contextual Information, Contextual Information
1343 @subsubsection Program Name
1344 The application's program name, as it appears on the @cmdline{}, may be
1345 accessed from @clon{}. You may find it easier to do this way, as @clon{}
1346 wraps around implementation-dependent access methods to @code{argv[0]}.
1349 In order to retrieve @code{argv[0]}, use the @code{progname} function
1350 like this: @code{(progname)}.
1352 @node Command-Line Remainder, Command-Line Polling, Program Name, Contextual Information
1353 @subsubsection Command-Line Remainder
1354 @cindex Remainder, of command-line
1355 @cindex Command-Line, remainder
1356 In the case your @cmdline{} has a remainder (that is, a non-options
1357 part; see @enduserref{Option Separator} and @ref{Synopsis Items}), you
1358 may need to access it in order to process it independently from @clon{}.
1359 Since @clon{} is responsible for parsing the @cmdline{}, it is also in
1360 charge of figuring out where the remainder of the @cmdline{} begins.
1363 The @cmdline{} remainder is known to @clon{} as soon as a context is
1364 created. You can retrieve it by using the @code{remainder} function like
1365 this: @code{(remainder)}. The remainder is provided as a list of strings.
1367 @node Command-Line Polling, , Command-Line Remainder, Contextual Information
1368 @subsubsection Command-Line Polling
1369 @cindex Polling, of command-line
1370 @cindex Command-Line, polling
1372 @clon{} provides two utility functions to inquire on the current status
1375 @findex cmdline-options-p
1377 The function @code{cmdline-options-p} returns true if there are still
1378 unprocessed options on the @cmdline{}. The function @code{cmdline-p}
1379 returns true if there's @emph{anything} left on the @cmdline{}, that is,
1380 either unprocessed options, or a remainder. A potential use of
1381 @code{cmdline-p} at a very early stage of your application could be to
1382 automatically display a help string if the @cmdline{} is effectively
1389 @node Integrity Checks, Option Retrieval, Context Creation, Using Clon
1390 @section Integrity Checks
1392 @cfindex{make-context}
1393 At this point, you know about the two necessary steps to initialize
1394 @clon{}: defining a synopsis and creating a context. If you paid
1395 attention to the quick start application (@pxref{Quick Start}), you may
1396 have noticed that @code{defsynopsis} was called as a top-level form
1397 whereas @code{make-context} was called from the function @code{main}. So
1400 First, I hope that you see why a context cannot be created as a toplevel
1401 form. If you do that, you will end-up creating a context relevant to the
1402 Lisp environment from which the application is created, not run.
1404 The synopsis, on the other hand, could be defined either as a toplevel
1405 form, as done in the quick start and the demo programs, or in the
1406 function @code{main}, just before making a context. There is a very good
1407 reason to prefer a toplevel form however: that reason is called
1408 ``integrity checks''.
1410 When you define a synopsis (or any synopsis item, for that matter),
1411 @clon{} performs a number of checks to make sure that you're making a
1412 sensible use of the library. In fact, the number of semantic mistakes
1413 that you can make is quite puzzling. You could for instance define
1414 several options with identical names, forget to provide a fallback or
1415 default value when it is required, provide invalid fallback or default
1416 values, and the list goes on and on. These are just a few examples but
1417 there are many more, and @clon{} checks all of those (I think).
1419 Since those mistakes relate to the definition of the application itself,
1420 they do not depend on a particular execution of it. Consequently, the
1421 sooner @clon{} catches them, the better. If you define your
1422 application's synopsis as a toplevel form, @clon{} will be able to
1423 perform its integrity checks when the application is created, not only
1424 when it is used. In other words, you won't be able to get a working
1425 application until your use of @clon{} is semantically correct.
1427 This is why it is strongly recommended to create synopsis from toplevel
1428 forms, and this also explains why @clon{} chooses @emph{not} to provide
1429 an @code{initialize} function that would wrap around @code{defsynopsis}
1430 and @code{make-context} together.
1437 @node Option Retrieval, Help, Integrity Checks, Using Clon
1438 @section Option Retrieval
1439 @cindex Runtime Phase
1440 @cindex Phase, runtime
1441 @cindex Retrieval, of options
1442 @cindex Options Retrieval
1444 During the runtime phase of @clon{}, your main activity will be to
1445 retrieve options and their values. @clon{} provides two techniques for
1446 retrieving options: you can request the value for a specific option
1447 directly, or you can process the @cmdline{} sequentially, which is the
1448 more traditional approach.
1450 @cindex Command-Line
1452 Both of these techniques can be freely combined together at any time,
1453 because @clon{} keeps track of the current status of the @cmdline{}. In
1454 fact, @clon{} never works on the original @cmdline{}, but uses a mutable
1455 @emph{copy} of it after parsing. If you want to access the real
1456 @cmdline{} of your application, you may use the @code{cmdline} function,
1457 which is a wrapper around an implementation-dependent way to access it.
1460 Finally, remember that the @cmdline{} is scanned from left to right
1461 during option retrieval (@pxenduserref{Option Retrieval}).
1464 * Explicit Retrieval:: Accessing options by name
1465 * Sequential Retrieval:: Accessing options in order
1468 @node Explicit Retrieval, Sequential Retrieval, Option Retrieval, Option Retrieval
1469 @subsection Explicit Retrieval
1470 @cindex Options Retrieval, explicit
1471 @cindex Retrieval, of options, explicit
1472 Since @clon{} lets you retrieve options on demand (at any time), it
1473 makes sense to be able to request the value of a specific option
1474 explicitely. For instance, you might want to try the @samp{--help}
1475 option first, without looking at the rest of the @cmdline{} because the
1476 application will in fact quit immediately after having displayed the
1479 @defun getopt :KEY VALUE@dots{}
1480 Retrieve the value of a specific option. The following @var{:KEY}s are
1481 currently available.
1486 @fkindex{getopt,:short-name}
1487 @fkindex{getopt,:long-name}
1488 Use one of these 2 keys to specify the name of the option you wish to
1491 @fkindex{getopt,:option}
1492 Alternatively, you can use a reference to an option object
1493 (@pxref{Constructors}).
1496 This function return two values: the option's value and the value's
1497 source (@pxenduserref{Value Sources}).
1500 The value's source may have the following forms:
1502 @item (:cmdline @var{NAME})
1503 @cindex Values, source, @cmdline{}
1504 This is for options found on the @cmdline{}. @var{NAME} is the name used
1505 on the @cmdline{}. It can be the option's long or short name, or a
1506 completed long name if the option's name was abbreviated. A completed
1507 name displays the omitted parts in parentheses (@code{"he(lp)"} for
1509 @item (:fallback @var{NAME})
1510 @cvopindex{:fallback-value}
1511 @cindex Values, source, fallback
1512 The same but when the fallback value is used, that is, when an option is
1513 not provided with its (optional) argument.
1514 @item (:default @var{NAME})
1515 @cvopindex{:default-value}
1516 @cindex Values, source, default
1517 The same, but when the default value is used (because there is no
1519 @item (:environment @var{VAR})
1521 @cindex Values, source, environment
1522 This is for options not found on the @cmdline{} but for which there is
1523 an associated environment variable set in the application's environment.
1524 @var{VAR} is the name of the corresponding environment variable.
1526 @cvopindex{:default-value}
1527 @cindex Values, source, default
1528 This is for options not found anywhere, but for which a default value
1534 Note that because flags don't take any argument, @code{getopt} returns a
1535 virtual value of @code{t} when they are found or a corresponding
1536 environment variable exists in the environment. For the same reason, a
1537 flag's value source may ony be @code{(:cmdline @var{NAME})} or
1538 @code{(:environment @var{VAR})}.
1541 When an option is not found anywhere and there is no default value,
1542 @code{getopt} just returns nil (no second value). Also, note that when
1543 your option accepts @code{nil} as a value, you @emph{need} to handle the
1544 second retrun value to make the difference between an option not found,
1545 and an actual value of @code{nil}.
1548 @node Sequential Retrieval, , Explicit Retrieval, Option Retrieval
1549 @subsection Sequential Retrieval
1550 @cindex Options Retrieval, sequential
1551 @cindex Retrieval, of options, sequential
1552 The more traditional approach to option retrieval is to scan the
1553 @cmdline{} for options in their order of appearance. @clon{} supports
1554 this by providing you with one function and two macros, as explained
1557 @defun getopt-cmdline
1558 Get the @dfn{next} @cmdline{} option, that is, the first option on the
1559 @cmdline{} that has not been previously retrieved, either explicitely or
1562 When there are no more options on the @cmdline{}, this function returns
1563 @code{nil}. Otherwise, four values are returned: the corresponding
1564 option object from the synopsis definition (@pxref{Constructors}), the
1565 name used on the @cmdline{}, the option's value and the value source
1566 (@code{:cmdline}, @code{:fallback} or @code{:default}). As in the case
1567 of explicit retrieval (@pxref{Explicit Retrieval}), the option's name
1568 may be completed in case of abbreviation.
1570 @rfindex{short-name}
1572 @copindex{:short-name}
1573 @copindex{:long-name}
1574 Unless you keep references to all your option objects (and thus can
1575 compare them directly to the one returned by this function), you can
1576 still identify the retrieved option by using the @code{short-name} and
1577 @code{long-name} readers on it: simply use @code{(long-name
1578 @var{OPTION})} or @code{(short-name @var{OPTION})} and you will get the
1579 corresponding strings.
1582 @defmac multiple-value-getopt-cmdline (OPTION NAME VALUE SOURCE) BODY
1583 Evaluate @var{BODY} with @var{OPTION}, @var{NAME}, @var{VALUE} and
1584 @var{SOURCE} bound to the values returned by the @code{getopt-cmdline}
1585 function above. Note that @var{BODY} is not evaluated if there was no
1586 remaining option on the @cmdline{}, so you don't need to conditionalize
1587 on @var{OPTION} being @code{null} yourself.
1590 @defmac do-cmdline-options (OPTION NAME VALUE SOURCE) BODY
1591 As above, but loop over all @cmdline{} options.
1598 @node Help, , Option Retrieval, Using Clon
1601 One of the first motivations in the design of @clon{} was to automate
1602 the generation of the help string, which is a very boring maintenance
1603 task to do by hand. The application's synopsis contains all the
1604 necessary information to do so. In order to print your application's
1605 help string, use the @code{help} function.
1607 @defun help [@code{:item} ITEM]
1608 @bioindex{search-path}
1609 @bievindex{SEARCH_PATH}
1610 @bioindex{highlight}
1611 @bievindex{HIGHLIGHT}
1614 @bioindex{line-width}
1615 @bievindex{LINE_WIDTH}
1616 Print the application's help string. Printing honors the search path,
1617 theme, line width and highlight settings provided by the corresponding
1618 built-in options (@pxenduserref{Theme Mechanism}).
1621 @fkindex{help,:item}
1622 By default, @code{help} prints the whole application help string,
1623 excluding hidden items. However, if you have kept a reference to any
1624 synopsis item (option, text, group), you can pass it as the value of the
1625 @code{:item} key, and @clon{} will only print the help string for that
1626 particular item. In this case however, the hidden state of the item is
1627 discarded (but @emph{not} the ones of sub-items).
1630 @cindex Built-In Groups
1631 @cindex Groups, built-in
1632 @cindex Hidden Groups
1633 @cindex Groups, hidden
1634 For instance, the @clon{} built-in group is normally hidden, so it
1635 doesn't show up in the global help string, but the @bioption{help}
1636 option uses the @code{help} function on it explicitely, so it discards
1639 Here is a potentially useful application of hidden groups in conjunction
1640 with the @code{:item} key. Look at ImageMagick's @file{convert}
1641 program's help string for instance: it is 276 lines long. Gosh. The help
1642 string is decomposed into several categories: image settings, image
1643 operators, misc options @etc{}. If I were to implement this program, I
1644 would rather have the @option{--help} option display an overview of the
1645 program, advertise @option{--version} and a couple of others, and I
1646 would then implement @option{--help} as an enumeration for listing every
1647 option category individually (they would normally be stored in hidden
1648 groups). The user could then use @option{--help=settings},
1649 @option{--help=operators} and so on to display only the category she's
1652 Finally, here is potentially useful application of hidden options that
1653 are never ever displayed in any help string whatsoever, and I mean,
1654 like, ever. This is the perfect tool for backdoor'ing a program. For
1655 instance, if you ever need to implement a
1656 @option{--discard-all-security-measures-and-blow-the-nuke} option, then
1657 you'd better have it hidden@dots{}
1661 @c ====================================================================
1663 @c ====================================================================
1664 @node Extending Clon, Advanced Usage, Using Clon, Top
1665 @chapter Extending Clon
1667 As you know, @clon{} already provides seven built-in option types: flags
1668 and six other types for valued options (@pxref{Built-In Valued
1669 Options}). After using @clon{} for a while, you may find that however
1670 brilliant and perfectly designed it is, none of the provided built-in
1671 types fullfill your requirements exactly. There are two ways around
1672 this: the right way and the wrong way (hint).
1674 @voindex{Strings,stropt}
1675 The wrong, although perhaps quicker way would be to use the
1676 @code{stropt} option type to simply retrieve unprocessed string values,
1677 and then do whatever tweaking required on them. In doing so, you risk
1678 reinventing some of @clon{}'s wheels.
1680 The right way is to define a new option type. Properly defined option
1681 types are a good thing because they allow for reusability and also
1682 extensibility, since new option types can always be defined on top of
1684 @voindex{Enumerations,enum}
1685 In this chapter we explain how to extend @clon{} by providing new option
1686 types. We illustrate the process with the example of the built-in
1689 @cindex Valued Options
1690 @cindex Options, valued
1692 Oh, and I almost forgot. I hope it is obvious to everyone that new
1693 option types are always @emph{valued}. There's no point in extending
1694 @clon{} with options that don't take any arguments, since we already
1698 * New Option Types:: In four steps
1699 * Extension Tips:: Some advice
1706 @node New Option Types, Extension Tips, Extending Clon, Extending Clon
1707 @section New Option Types
1708 @cindex Option Types, in files
1709 @cindex Files, one per option type
1710 @pkgindex{com.dvlsoft.clon}
1711 From a software engineering point of view, it is better to implement new
1712 option types in a file of their own, preferably named after the option
1713 type itself, and to put this file in the @clon{} package, like this:
1717 (in-package :com.dvlsoft.clon)
1721 Creating your own option type involves 5 steps: providing a class for
1722 them, implementing three protocols related to argument/value tweaking,
1723 and providing a constructor function. We now review those 5 steps in
1727 * New Option Classes:: Step 1
1728 * Value Check Protocol:: Step 2
1729 * Argument Conversion Protocol:: Step 3
1730 * Error Management:: In-between steps coffee time!
1731 * Value Stringification Protocol:: Step 4
1732 * Constructor Functions:: Step 5
1735 @node New Option Classes, Value Check Protocol, New Option Types, New Option Types
1736 @subsection New Option Classes
1738 @clsindex{valued-option}
1739 @clon{} maintains a class hierarchy for all option types. The mother of
1740 all option types is the @code{option} abstract class. It handles the
1741 options'short and long names, description and associated environment
1742 variable (@pxref{Common Properties}). Valued options inherit from an
1743 abstract subclass of @code{option} called @code{valued-option}. This
1744 class handles the option's argument name and status (optional or
1745 mandatory), fallback and default values (@pxref{Common Valued Option
1748 @cindex User-Defined Option Classes
1749 @cindex Option Classes, user-defined
1750 In order to create a new option type, use the @code{defoption} macro.
1752 @defmac defoption CLASS SUPERCLASSES SLOTS &rest OPTIONS
1753 Create a new option CLASS and register it with @clon{}.
1754 Syntactically, thismacro behaves like @code{defclass}. Option types
1755 created like this implicitely inherit from @code{valued-option} and in
1756 turn @code{option}, so you don't need to put them explicitely in the
1757 @var{SUPERCLASSES} list.
1760 Let's look at the enumeration example now.
1764 (defoption enum (enum-base)
1765 ((argument-name ;; inherited from the VALUED-OPTION class
1767 (:documentation "The ENUM class.
1768 This class implements options whose values belong to a set of keywords."))
1772 @voindex{Enumerations,enum}
1773 @vopindex{Enumerations,enum,:enum}
1774 @voindex{Extended Switches,xswitch}
1775 @vopindex{Extended Switches,xswitch,:enum}
1776 @clsindex{enum-base}
1777 As you can see, this class inherits from @code{enum-base}, which is the
1778 class handling the @code{:enum} property. The reason for this split is
1779 that there are currently two option types providing enumeration-like
1780 facility: @code{enum} and @code{xswitch}, so @code{xswitch} also
1781 inherits from @code{enum-base}.
1783 @clsindex{valued-option}
1784 @cvopindex{:argument-name}
1785 There are no new slots in this class, but the @code{argument-name} slot
1786 provided by the @code{valued-option} class has its initform changed from
1787 @code{"ARG"} to @code{"TYPE"}.
1789 @node Value Check Protocol, Argument Conversion Protocol, New Option Classes, New Option Types
1790 @subsection Value Check Protocol
1791 @cindex Value Check Protocol
1792 @cindex Protocols, value check
1793 Now that we have our new option class, we need to implement the
1794 so-called @dfn{value check} protocol. This protocol is used to make sure
1795 that values provided for options of your new type actually comply with
1796 the type in question. Values going through this protocol are fallback
1797 values, default values, and values provided from a debugger restart
1798 (@pxenduserref{Error Management}). In the case of fallback and default
1799 values (which, by the way, are provided by @emph{you}, the @clon{}
1800 user), the check is performed only once, when the option object is
1801 created. Values provided from a debugger restart come from the
1802 application end-user, and hence are checked every time.
1804 The value check protocol is implemented through a @code{check} generic
1805 function for which you must provide a method.
1807 @deffn {Generic Function} check OPTION VALUE
1809 @ecindex invalid-value
1810 Check that @var{VALUE} is valid for @var{OPTION}. If @var{VALUE} is
1811 valid, return it. Otherwise, raise an @code{invalid-value} error.
1814 As you can see, you need to provide a method with the first argument
1815 specialized to your new option type. This method must return @var{VALUE}
1816 if it is okay, and raise an @code{invalid-value} error otherwise.
1818 @ecindex invalid-value
1819 @clon{} maintains a hierarchy of error conditions. The
1820 @code{invalid-value} error condition is defined like this:
1824 (define-condition invalid-value (option-error)
1825 ((value :documentation "The invalid value."
1828 (comment :documentation "An additional comment about the error."
1832 (:report (lambda (error stream)
1833 (format stream "Option ~A: invalid value ~S.~@[~%~A~]"
1834 (option error) (value error) (comment error))))
1835 (:documentation "An invalid value error."))
1839 @ecindex invalid-value
1840 @ecsindex{invalid-value,value}
1841 @ecsindex{invalid-value,comment}
1842 When the error is raised, you must fill in the @code{value} and
1843 @code{comment} slots appropriately.
1844 @ecindex option-error
1845 @ecsindex{option-error,option}
1846 The super-condition @code{option-error} provides an additional
1847 @code{option} slot that you must also fill in when the error is raised.
1849 @gfmindex{check,@r{Enumerations (}enum@r{)}}
1850 @voindex{Enumerations,enum}
1851 @vopindex{Enumerations,enum,:enum}
1852 @findex list-to-string
1853 Let's look at the enumeration example now.
1857 (defmethod check ((enum enum) value)
1858 "Check that VALUE is a valid ENUM."
1859 (unless (member value (enum enum))
1860 (error 'invalid-value
1863 :comment (format nil "Valid values are: ~A."
1864 (list-to-string (enum enum)
1865 :key #'prin1-to-string))))
1870 This code should be self-explanatory. We check that the value we got
1871 belongs to the enumeration. @code{list-to-string} is a utility function
1872 that will separate every element with comas in the resulting string.
1874 @node Argument Conversion Protocol, Error Management, Value Check Protocol, New Option Types
1875 @subsection Argument Conversion Protocol
1876 @cindex Argument Conversion Protocol
1877 @cindex Protocols, argument conversion
1878 The next protocol we need to implement is the so-called @dfn{argument
1879 conversion} protocol. This protocol is used to convert option arguments
1880 (that is, strings) to an actual value of the proper type. Arguments
1881 going through this protocol come from the @cmdline{}, the value of an
1882 environment variable or a debugger restart (@pxenduserref{Error
1883 Management}). Also, note that @clon{} assumes that you implement this
1884 protocol correctly, so no value check is performed on values coming from
1885 the conversion of an argument.
1887 The conversion protocol is implemented through a @code{convert} generic
1888 function for which you must provide a method.
1890 @deffn {Generic Function} convert OPTION ARGUMENT
1891 @gfsubindex{convert}
1892 @ecindex invalid-argument
1893 Convert @var{ARGUMENT} to @var{OPTION's} value. If @var{ARGUMENT} is
1894 invalid, raise an @code{invalid-argument} error.
1897 As you can see, you need to provide a method with the first argument
1898 specialized to your new option type. This method must return the
1899 conversion of @var{ARGUMENT} to the appropriate type if it is valid, and
1900 raise an @code{invalid-argument} error otherwise.
1902 @ecindex invalid-argument
1903 The @code{invalid-argument} error condition is defined like this:
1907 (define-condition invalid-argument (option-error)
1908 ((argument :documentation "The invalid argument."
1912 (comment :documentation "An additional comment about the error."
1916 (:report (lambda (error stream)
1917 (format stream "Option ~A: invalid argument ~S.~@[~%~A~]"
1918 (option error) (argument error) (comment error))))
1919 (:documentation "An invalid argument error."))
1923 @ecindex invalid-argument
1924 @ecsindex{invalid-argument,argument}
1925 @ecsindex{invalid-argument,comment}
1926 When the error is raised, you must fill in the @code{argument} and
1927 @code{comment} slots appropriately.
1928 @ecindex option-error
1929 @ecsindex{option-error,option}
1930 As before, the super-condition @code{option-error} provides an
1931 additional @code{option} slot that you must also fill in when the error
1934 @gfmindex{convert,@r{Enumerations (}enum@r{)}}
1935 @voindex{Enumerations,enum}
1936 @vopindex{Enumerations,enum,:enum}
1937 @findex closest-match
1938 Let's look at the enumeration example now.
1942 (defmethod convert ((enum enum) argument)
1943 "Convert ARGUMENT to an ENUM value."
1944 (or (closest-match argument (enum enum) :ignore-case t :key #'symbol-name)
1945 (error 'invalid-argument
1948 :comment (format nil "Valid arguments are: ~A."
1949 (list-to-string (enum enum)
1950 :key (lambda (value)
1951 (stringify enum value)))))))
1956 Since enumerations allow their arguments to be abbreviated, a utility
1957 function named @code{closest-match} is used to find the closest match
1958 between an argument and the possible values. Otherwise, an
1959 @code{invalid-argument} error is raised. For an explanation of
1960 @code{stringify}, @xref{Value Stringification Protocol}.
1962 @node Error Management, Value Stringification Protocol, Argument Conversion Protocol, New Option Types
1963 @subsection Error Management
1965 @cindex Debugger restarts
1966 Let's take a short break in our @clon{} extension process. We have seen
1967 that @clon{} may throw errors in different situations, including invalid
1968 arguments or values. The end-user manual advertises that the interactive
1969 error handler offers a set of ``options to fix problems'' (if you don't
1970 know what I'm talking about, please read @enduserref{Error Management}
1971 and you will know). Well, you may have guessed that these options are
1972 simply ``restarts'' (of course, we don't use that term there, as we
1973 wouldn't want to frighten the casual user, or would we?).
1975 When you ship your application, you are encouraged to disable the
1976 debugger in the standalone executable because that also might scare the
1977 casual user a little bit (the end-user manual only mentions the
1978 @code{none} error-handler to explain that people shouldn't use it). The
1979 way error handling is done in @cl{} standalone executables is
1980 implementation-dependent, so please refer to your favorite compiler's
1981 documentation. More generally, the behavior of @cl{} standalone
1982 executables may depend on:
1986 the state of the Lisp environment when the application was dumped, which
1987 may in turn depend on command-line options passed to the Lisp itself
1988 (@pxref{Dumping Executables}),
1991 the arguments passed to the dumping function (look at @clon{}'s
1992 @code{dump} macro to see what it does),
1997 No, really, @cl{} is no fun at all.
1999 @node Value Stringification Protocol, Constructor Functions, Error Management, New Option Types
2000 @subsection Value Stringification Protocol
2001 Okay, back to implementing our new option type.
2003 @cindex Value Stringification Protocol
2004 @cindex Protocols, value stringification
2005 The third and last protocol we need to implement is called the
2006 @dfn{value stringification} protocol. This protocol can be seen as the
2007 reverse protocol for argument conversion (@pxref{Argument Conversion
2008 Protocol}): its purpose is to transform an option's value into a
2009 corresponding argument that the end-user could have provided in order to
2013 @cvopindex{:fallback-value}
2014 @cindex Values, source, fallback
2015 @cvopindex{:default-value}
2016 @cindex Values, source, default
2017 @gfmindex{convert,@r{Enumerations (}enum@r{)}}
2018 The main use for this protocol is to advertise the fallback and default
2019 values correctly in help strings: the end-user does not want to see
2020 those @emph{values}, but rather the @emph{argument} that would lead to
2021 them. However, you are free to use it wherever you like (see the
2022 @code{convert} method for @code{enum} options for instance).
2024 The value stringification protocol is implemented through a
2025 @code{stringify} generic function for which you must provide a method.
2027 @deffn {Generic Function} stringify OPTION VALUE
2028 @gfsubindex{stringify}
2029 Transform OPTION's @var{VALUE} into an argument.
2032 I admit that this function could also have been called
2033 @code{argumentize} or even @code{deconvertify}. As you can see, you need
2034 to provide a method with the first argument specialized to your new
2035 option type. You can assume that @var{VALUE} is a valid value for your
2036 option, so no checking is necessary and no error needs to be raised.
2038 @gfmindex{stringify,@r{Enumerations (}enum@r{)}}
2039 @voindex{Enumerations,enum}
2040 Let's look at the enumeration example now.
2044 (defmethod stringify ((enum enum) value)
2045 "Transform ENUM's VALUE into an argument."
2046 (string-downcase (symbol-name value)))
2050 Pretty straightforward, right?
2053 @node Constructor Functions, , Value Stringification Protocol, New Option Types
2054 @subsection Constructor Functions
2055 @cindex Constructors, for options objects
2056 @cindex Option Constructors
2057 The last required step to complete our new option type extension is to
2058 provide a @dfn{constructor} function that wraps around
2059 @code{make-instance} on the corresponding option class. I won't insult
2060 you by explaining how to write a constructor. Let me just give four good
2061 reasons why providing constructors is important.
2063 Providing a constructor for every new option type is important because:
2068 it is a good software engineering practice,
2074 and above all, it makes your new option type automatically available in
2075 calls to @code{defsynopsis} and @code{defgroup} (@pxref{Synopsis Items}
2076 and @ref{Group Definition}).
2080 @voindex{Enumerations,enum}
2082 Let's look at the enumeration example now.
2086 (defun make-enum (&rest keys
2087 &key short-name long-name description
2088 argument-name argument-type
2089 enum env-var fallback-value default-value
2091 "Make a new enum option.
2092 - SHORT-NAME is the option's short name (without the dash).
2094 - LONG-NAME is the option's long name (without the double-dash).
2096 - DESCRIPTION is the option's description appearing in help strings.
2098 - ARGUMENT-NAME is the option's argument name appearing in help strings.
2099 - ARGUMENT-TYPE is one of :required, :mandatory or :optional (:required and
2100 :mandatory are synonyms).
2101 It defaults to :optional.
2102 - ENUM is the set of possible values.
2103 - ENV-VAR is the option's associated environment variable.
2105 - FALLBACK-VALUE is the option's fallback value (for missing optional
2107 - DEFAULT-VALUE is the option's default value, if any.
2108 - When HIDDEN, the option doesn't appear in help strings."
2109 (declare (ignore short-name long-name description
2110 argument-name argument-type
2111 enum env-var fallback-value default-value
2113 (apply #'make-instance 'enum keys))
2117 Woah, what a mouthful for a single line of code@dots{} Yeah, I'm a
2118 maniac and I like redundancy. I always restate all the available keys
2119 explicitely, and everything again in the docstring so that all the
2120 interesting information is directly available (I might change my mind as
2121 I grow older though).
2127 @node Extension Tips, , New Option Types, Extending Clon
2128 @section Extension Tips
2129 So that's it. Now you know how to extend @clon{} with your own option
2130 types. Here is some piece of advice that you might find useful in the
2134 * Incremental Option Types:: Doing without defoption
2135 * Lisp Option Abuse:: Thinking in end-user terms
2138 @node Incremental Option Types, Lisp Option Abuse, Extension Tips, Extension Tips
2139 @subsection Incremental Option Types
2141 If one of the built-in options is almost what you need, you may be
2142 tempted to subclass it directly instead of using @code{defoption}, and
2143 only change what's needed, After all, it's Lisp. Lisp is a world of
2144 mess@t{^D^D^D^D}freedom.
2150 @code{defoption} is not @emph{only} a convenience wrapper around
2151 @code{defclass}. It also arranges for @code{defsynopsis} and
2152 @code{defgroup} to recognize your new option type. So please, do use it
2155 @node Lisp Option Abuse, , Incremental Option Types, Extension Tips
2156 @subsection Lisp Option Abuse
2157 @voindex{Lisp Objects,lispobj}
2158 @vopindex{Lisp Objects,lispobj,:typespec}
2159 Along with the same lines, you may find that the @code{lispobj} type is
2160 all you need in many situations. Let's take an example. Suppose you want
2161 to implement a @code{--stars} option to assign a rank to a movie, from 0
2162 to 5. The lazy approach is to simply create a @code{lispobj} option with
2163 a @code{:typespec} (type specifier) of @code{(integer 0 5)} and you're
2166 But now, remember that the end-user of your application is probably not
2167 a Lisper (in fact, I would hope that @clon{} contributes to increasing
2168 the number of standalone @cl{} applications out there@dots{}). What do
2169 you think would be her reaction, if, after providing a bogus value to
2170 the @code{--stars} option, she get the following error message:
2173 Option 'stars': invalid argument "6".
2174 Argument "6" must evaluate to (integer 0 5).
2177 or worse, a @code{"Cannot parse argument"} error message because of a
2180 Not very friendly, right? In other words, you need to think in terms of
2181 what the end-user of your application will expect. In that particular
2182 situation, you might want to subclass @code{lispobj} (with
2183 @code{defoption}!) only to provide friendlier error messages.
2187 @c ====================================================================
2189 @c ====================================================================
2190 @node Advanced Usage, Conclusion, Extending Clon, Top
2191 @chapter Advanced Usage
2193 This chapter contains information about different features that are
2194 present in @clon{} because of design decisions, but that I expect to be
2195 used only rarely, if at all.
2198 * Multiple Clon Instances:: Different command-lines, synopsis or contexts
2199 * Programmatic Help Strings:: Beyond the --help option
2200 * Version Numbering:: In case you need to conditionalize
2204 @c -----------------------
2205 @c Multiple Clon Instances
2206 @c -----------------------
2207 @node Multiple Clon Instances, Programmatic Help Strings, Advanced Usage, Advanced Usage
2208 @section Multiple @clon{} Instances
2210 It is possible to use different instances of @clon{} in parallel in a
2211 single application, by using a virtual @cmdline{} instead of the real
2212 one, different synopsis and multiple contexts simultaneously.
2215 * Using Different Synopsis:: The default one, and the others
2216 * Using Different Command-Lines:: The real one, and the others
2217 * Using Multiple Contexts:: The current one, and the others
2218 * Potential Uses:: What to do with all that
2221 @node Using Different Synopsis, Using Different Command-Lines, Multiple Clon Instances, Multiple Clon Instances
2222 @subsection Using Different Synopsis
2223 @cindex Synopsis, default
2224 Did you notice that after defining a synopsis, there is actually never
2225 any explicit reference to it anymore? So where is the magick? In fact,
2226 there's no magick at all involved here.
2228 @vindex *default-synopsis*
2229 @foindex{defsynopsis,:make-default}
2230 @cfiaindex{make-synopsis,:make-default}
2231 @clon{} has a global variable named @code{*default-synopsis*} which
2232 holds the@dots{} default synopsis, yeah. When you define/create a
2233 synopsis with either @code{defsynopsis} or @code{make-synopsis}, it is
2234 automatically made the default one, unless you use the
2235 @code{:make-default} option/initarg with a value of @code{nil}, like
2239 (defsynopsis (:make-default nil) ...)
2245 (make-synopsis :make-default nil ...)
2248 @cfindex{make-context}
2249 When you create a context with @code{make-context}, the default synopsis
2250 is used implicitely, but you have two ways to avoid this.
2254 @vindex *default-synopsis*
2255 At any time in your program, you may change the value of
2256 @code{*default-synopsis*}. All subsequent calls to @code{make-context}
2257 will hence use this other synopsis.
2259 @cfiaindex{make-context,:synopsis}@c
2260 If you prefer to use another synopsis only temporarily, you can use the
2261 @code{:synopsis} initarg to @code{make-context} instead.
2264 @node Using Different Command-Lines, Using Multiple Contexts, Using Different Synopsis, Multiple Clon Instances
2265 @subsection Using Different Command-Lines
2266 In @ref{Context Creation}, we saw that a context object describes a
2267 particular instance of your application, most notably depending on the
2268 actual @cmdline{} the end-user provided. It turns out, however that the
2269 @cmdline{} doesn't need to be the actual program's @cmdline{}, as the
2270 user typed it. Any list of strings can act as a @cmdline{}.
2272 @cfiaindex{make-context,:cmdline}
2273 The function @code{make-context} has a @code{:cmdline} key that allows
2274 you to provide any list of strings that will act as the @cmdline{}. Of
2275 course, the default is to use the actual program's one.
2277 @node Using Multiple Contexts, Potential Uses, Using Different Command-Lines, Multiple Clon Instances
2278 @subsection Using Multiple Contexts
2279 @cindex Context, current
2280 Did you also notice that after creating a context, there is actually
2281 never any explicit reference to it anymore? So again, where is the
2282 magick? In fact, there's no magick at all involved here either.
2284 @vindex *current-context*
2285 @cfiaindex{make-context,:make-current}
2286 @clon{} has a global variable named @code{*current-context*} which holds
2287 the@dots{} current context, yeah. When you create a context with
2288 @code{make-context}, it is automatically made current, unless you use
2289 the @code{:make-current} initarg with a value of @code{nil}.
2291 @cindex Runtime Phase
2294 @findex cmdline-options-p
2297 @findex getopt-cmdline
2298 @findex multiple-value-getopt-cmdline
2299 @findex do-cmdline-options
2301 The whole runtime phase API of @clon{} uses a context implicitely. This
2302 involves @code{progname}, @code{remainder}, @code{cmdline-options-p},
2303 @code{cmdline-p}, @code{getopt}, @code{getopt-cmdline},
2304 @code{multiple-value-getopt-cmdline}, @code{do-cmdline-options} and
2305 @code{help}. As a consequence, it is possible to use @clon{} with
2306 multiple contexts at the same time. There are in fact three ways to
2311 @vindex *current-context*
2312 At any time in your program, you may change the value of
2313 @code{*current-context*}. All subsequent calls to the runtime phase API
2314 will hence use this other context.
2316 @clon{} also provides a macro which changes the current context for you.
2317 @defun with-context CONTEXT &body BODY
2318 Execute @var{BODY} with @code{*current-context*} bound to @var{CONTEXT}.
2321 @fkindex{progname,:context}@c
2322 @fkindex{remainder,:context}@c
2323 @fkindex{cmdline-options-p,:context}@c
2324 @fkindex{cmdline-p,:context}@c
2325 @fkindex{getopt,:context}@c
2326 @fkindex{getopt-cmdline,:context}@c
2327 @fkindex{help,:context}@c
2328 @foindex{multiple-value-getopt-cmdline,:context}@c
2329 @foindex{do-cmdline-options,:context}@c
2330 If you prefer to use another context only once, you can use the
2331 @code{:context} key instead. The whole runtime phase API of @clon{}
2332 understands it. For the functions @code{getopt}, @code{getopt-cmdline}
2333 and @code{help}, it's just another key in addition to those we've
2334 already seen. For the macros @code{multiple-value-getopt-cmdline} and
2335 @code{do-cmdline-options}, the key must appear at the end of the first
2336 (list) argument, like this:
2339 (multiple-value-getopt-cmdline (option name value :context ctx) ...)
2340 (do-cmdline-options (option name value :context ctx) ...)
2344 @node Potential Uses, , Using Multiple Contexts, Multiple Clon Instances
2345 @subsection Potential Uses
2346 By combining @clon{}'s ability to use a virtual @cmdline{}, different
2347 synopsis and multiple contexts, you can achieve very neat (read: totally
2348 useless) things. For instance, you could write an application that takes
2349 an option providing @cmdline{} arguments for an external program to be
2350 forked. Some revision control systems do that for controlling external
2351 @code{diff} programs for instance, so no big deal. The big deal is that
2352 you can completely control the validity of the external program's
2353 @cmdline{}, before it is forked, from your original one.
2355 Here is another idea, again related to revision control systems. Some of
2356 them feature a @cmdline{} syntax like the following:
2359 prog [global options] command [command-specific options]
2363 @cindex Command-Line, remainder
2364 @cindex Remainder, of command-line
2365 You can achieve this with @clon{} quite easily. In fact, the
2366 demonstration program called @file{advanced} in the distribution shows
2367 you how to do it. First, define a synopsis which only handles the global
2368 options, and provide a postfix of @code{"command [command-specific
2369 option]"} or something like that. This will authorize a @cmdline{}
2370 remainder which will start with the command name.
2372 Now, for every command in your program, define a specific synopsis with
2373 only the command-specific options. Get the remainder of the original
2374 @cmdline{} (@pxref{Command-Line Remainder}) and figure out which command
2375 was used. Depending on it, create a new context with the appropriate
2376 synopsis and the original @cmdline{}'s remainder as the new, virtual,
2377 @cmdline{}. You're done: retrieve global options from the first context,
2378 and command-specific ones from the second one.
2380 @cindex Help String, display
2382 What's even cooler is that you can display the command-specific options
2383 on demand quite easily as well (like what @file{git} does when you call
2384 it like this: @code{git commit --help} for instance): calling the
2385 @code{help} function on the original context gives you the global
2386 options's help string while calling it on the command-specific one will
2387 display the command-specific usage.
2389 @bioindex{search-path}
2390 @bievindex{SEARCH_PATH}
2391 @bioindex{highlight}
2392 @bievindex{HIGHLIGHT}
2395 @bioindex{line-width}
2396 @bievindex{LINE_WIDTH}
2397 One thing to remember here is that every context/synopsis duet you
2398 create gets its own set of built-in @clon{} options. As a consequence,
2399 there is currently no simple way to have a single set of built-in
2400 options apply to the whole application, for instance, to both a global
2401 and a command-specific context. Let me make this clearer: if your
2402 end-user calls @code{prog --clon-theme=foo command -h}, then the theme
2403 option will have no effect because it would only affect the global help
2404 option. In order to actually use the expected theme, your end-user would
2405 need to use @code{prog command --clon-theme=foo -h}. Depending on which
2406 cerebral emisphere (s)he prefers to use, this may seem logical or not.
2408 Finally, note that you can use the virtual @cmdline{} / specific
2409 synopsis technique recursively to manage complicated @cmdline{} syntax,
2410 for instance alternating options and non-options parts several times.
2412 In the future, @clon{} may provide better ways to achieve this kind of
2413 things (a notion of ``sub-context'' may be in order).
2417 @c -------------------------
2418 @c Programmatic Help Strings
2419 @c -------------------------
2420 @node Programmatic Help Strings, Version Numbering, Multiple Clon Instances, Advanced Usage
2421 @section Programmatic Help Strings
2426 @cindex Themes, standard, @t{refcard}
2427 @cindex Standard Themes, @t{refcard}
2428 So far, we've seen how to use the @code{help} function to implement a
2429 typical @code{--help} option. This is mostly intended for the end-user.
2430 There are also times when this function could be useful to @emph{you},
2431 the application developer. For instance, one could imagine that part of
2432 the compilation phase would involve generating the help string in order
2433 to include it in the manual. Another idea would be that @samp{make
2434 install} creates a @file{REFCARD} file in
2435 @file{/usr/local/share/doc/my-app/} which contains the help string
2436 formatted with the @code{refcard} theme, @etc{}.
2440 @bioindex{search-path}
2441 @bievindex{SEARCH_PATH}
2442 @bioindex{line-width}
2443 @bievindex{LINE_WIDTH}
2444 @bioindex{highlight}
2445 @bievindex{HIGHLIGHT}
2446 In such situations, calling the @code{help} function might not be
2447 directly associated with an end-user level option, or at least not
2448 @code{--help}, and you might not want to honor the end-user level
2449 settings for theme, search path, line-width, or highlighting either
2450 (remember that these settings might come from the environment variables
2451 associated with @bioption{theme}, @bioption{search-path},
2452 @bioption{line-width} and @bioption{highlight}).
2454 @fkindex{help,:theme}
2455 @fkindex{help,:search-path}
2456 @fkindex{help,:line-width}
2457 @fkindex{help,:highlight}
2458 Because of this, the @code{help} function provides additional keys that
2459 allow you to override those settings (they are in fact stored in the
2460 context object). The keys in question are: @code{:theme},
2461 @code{:search-path}, @code{:line-width} and @code{:highlight}.
2463 @fkindex{help,:output-stream}
2464 @vindex *standard-output*
2465 In addition to that, there is an @code{:output-stream} key which
2466 defaults to @code{*standard-output*} which you could use for instance to
2467 write directly to a file. Note that there is no end-user level access to
2472 @c -----------------
2473 @c Version Numbering
2474 @c -----------------
2475 @node Version Numbering, , Programmatic Help Strings, Advanced Usage
2476 @section Version Numbering
2479 As @clon{} evolves over time, you might one day feel the need for
2480 conditionalizing your code on the version of the library. While the
2481 end-user of your application has limited means to access the current
2482 version number of @clon{} (see @enduserref{Clonification} and the
2483 built-in option @bioption{version}), you, the application programmer
2484 and @clon{} user, have a finer grained access to it.
2486 The first thing you can do to access the current version number of
2487 @clon{} is use the @code{version} function (this is in fact the function
2488 bound to the @bioption{version} option).
2490 @defun version &optional (TYPE :number)
2491 Return the current version number of @clon{}. @var{TYPE} can be one of
2492 @code{:number}, @code{:short} or @code{:long}. For @code{:number}, the
2493 returned value is a fixnum. Otherwise, it is a string.
2496 A @clon{} version is characterized by 4 elements as described below.
2499 @vindex +release-major-level+
2500 A major version number stored in the constant
2501 @code{+release-major-level+}.
2503 @vindex +release-minor-level+
2504 A minor version number, stored in the constant
2505 @code{+release-minor-level+}.
2507 @vindex +release-status+
2508 A release status stored in the constant @code{+release-status+}. The
2509 status of a release can be @code{:alpha}, @code{:beta}, @code{:rc}
2510 (standing for ``release candidate'') or @code{:patchlevel}. These are in
2511 effect 4 levels of expected stability.
2513 @vindex +release-status-level+
2514 A status-specific version number stored in the constant
2515 @code{+release-status-level+}. Status levels start at 1 (alpha 1, beta 1
2516 and release candidate 1) except for stable versions, in which case patch
2517 levels start at 0 (@eg{} 2.4.0).
2520 @vindex +release-name+
2521 In addition to that, each version of @clon{} (in the sense
2522 @emph{major.minor}, regardless of the status) has a name, stored in the
2523 constant @code{+release-name+}. The general theme for @clon{} is ``Great
2524 Jazz Musicians'', and specifically for the 1.x series: ``Great Saxophone
2525 Players''. Anyone daring to mention Kenny G at that point will be shot
2528 Here is how the @code{version} function computes its value.
2531 A version @code{:number} is computed as @emph{major . 10000 + minor .
2532 100 + patchlevel}, effectively leaving two digits for each level. Note
2533 that alpha, beta and release candidate status are ignored in version
2534 numbers (this is as if the corresponding status level was considered to
2535 be always 0). Only stable releases have their level taken into account.
2537 A @code{:short} version will appear like this for unstable releases:
2538 1.3a4, 2.5b8 or 4.2rc1. Remember that alpha, beta or release candidate
2539 levels start at 1. Patchlevels for stable releases start at 0 but 0 is
2540 ignored in the output. So for instance, version 4.3.2 will appear as-is,
2541 while version 1.3.0 will appear as just 1.3.
2543 A @code{:long} version is expanded from the short one, and includes the
2544 release name. For instance, 1.3 alpha 4 "Bill Evans", 2.5 beta 8 "Scott
2545 Henderson", 4.2 release candidate 1 "Herbie Hancock" or 4.3.2 "Chick
2546 Corea". As for the short version, a patchlevel of 0 is ignored in the
2547 output: 1.3 "Bill Evans".
2552 @c ====================================================================
2554 @c ====================================================================
2555 @node Conclusion, Technical Notes, Advanced Usage, Top
2558 So that's it I guess. You know all about @clon{} now. The next step is
2559 to actually use it to clonify your favorite application, write new
2560 applications using it and contaminate the world with standalone @cl{}
2561 programs, featuring unprecedented @cmdline{} power and thrill-a-minute
2564 Now, go Luke. The Attack of the @clon{} is ready to begin.
2568 @c ====================================================================
2570 @c ====================================================================
2571 @node Technical Notes, API Quick Reference, Conclusion, Top
2572 @appendix Technical Notes
2574 This chapter contains important information about the library's
2575 configuration, supported platforms, non-ANSI features and
2576 portability concerns.
2579 * Configuration:: Pre-loading parameters
2580 * Non-ANSI Features:: Requiring operating system access
2581 * Supported Platforms:: Systems, compilers and dependencies
2582 * Dumping Executables:: Convenience wrappers
2589 @node Configuration, Non-ANSI Features, Technical Notes, Technical Notes
2590 @section Configuration
2591 @cindex Configuration
2592 @vindex com.dvlsoft.clon.configuration
2593 Some aspects of @clon{}'s behavior can be configured @emph{before} the
2594 ASDF system is actually loaded. @clon{} looks for configuration options
2595 in a variable called @code{com.dvlsoft.clon.configuration} in the
2596 @code{cl-user} package. If set, this variable should contain a property
2597 list of configuration options and their corresponding values. Currently,
2598 the following options are provided.
2601 @item :swank-eval-in-emacs
2602 @coindex{:swank-eval-in-emacs}@c
2603 @vindex slime-enable-evaluate-in-emacs
2604 This option is only useful if you use Slime, and mostly if you plan on
2605 hacking @clon{} itself. The library provides indentation information for
2606 some of its functions directly embedded in the code. This information
2607 can be automatically transmitted to (X)Emacs when the ASDF system is
2608 loaded if you set this option to @code{t}. However, note that for this
2609 to work, the Slime variable @code{slime-enable-evaluate-in-emacs} must
2610 also be set to @code{t} in your (X)Emacs session. If you're interested
2611 to know how this process works, I have described it in the following
2613 @uref{http://www.didierverna.com/sciblog/index.php?post/2011/07/20/One-more-indentation-hack}.
2616 This option is only used by the ABCL port. @ref{Dumping Executables},
2617 provides more information on its use.
2621 @c -----------------
2622 @c Non-ANSI Features
2623 @c -----------------
2624 @node Non-ANSI Features, Supported Platforms, Configuration, Technical Notes
2625 @section Non-ANSI Features
2626 One feature of @clon{} that is beyond the ANSI standard is terminal
2627 autodetection (it requires an @code{ioctl} call and hence a foreign
2628 function interface). Terminal autodetection is used in several
2629 situations, for turning on highlighting automatically and for detecting
2630 a terminal line width.
2632 @cindex Restricted Mode
2633 If, for some reason, terminal autodetection is not available, @clon{}
2634 will work in so-called @emph{restricted mode}. This means that
2635 @bioption{highlight=auto} won't work (highlighting will @emph{not} be
2636 turned on automatically on a @tty{}). For the same reason, unless
2637 otherwise specified via either the @code{COLUMNS} environment variable
2638 or the @bioption{line-width} option, terminal output will be formatted
2639 for 80 columns regardless of the actual terminal width
2640 (@pxenduserref{Global Control}).
2643 @c ----------------------
2644 @c Supported Platforms
2645 @c ----------------------
2646 @node Supported Platforms, Dumping Executables, Non-ANSI Features, Technical Notes
2647 @section Supported Platforms
2648 @clon{} currently works on Unix systems (including MacOS X) and has been
2649 ported to 6 @cl{} implementations. I have no idea about Windows right
2650 now. The following table lists the supported platforms.
2652 @multitable {Compiler} {Minimum Version} {@code{cffi} (optional)}
2653 @headitem Compiler @tab Minimum Version @tab Dependencies
2664 @tab 11.1.2@footnote{more precisely, git revision
2665 3e2e5f9dc3c5176ef6ef8d7794bfa43f1af8f8db}
2669 @tab @code{cffi} (optional)
2671 @tab 0.24.0@footnote{more precisely, svn trunk revision 13156}
2675 @unnumberedsubsec ABCL specificities
2676 @clon{}'s ABCL port currently has two limitations:
2679 @bioindex{highlight}@c
2680 @bioindex{line-width}@c
2682 @cindex Restricted Mode
2683 It only works in restricted mode (@pxref{Non-ANSI Features}).
2685 Since Java doesn't have a @code{putenv} or @code{setenv} function (!!),
2686 the @code{modify-environment} restart, normally proposed when an
2687 environment variable is set to a bogus value, is unavailable
2688 (@pxenduserref{Error Management}).
2691 @unnumberedsubsec CLISP specificities
2692 @cindex Restricted Mode
2693 As mentioned in the above table, CLISP's dependency on @code{cffi} is
2694 optional. CLISP needs @code{cffi} in order to implement terminal
2695 autodetection only (note that many other implementations come with their
2696 own foreign function interface). If @code{cffi} cannot be found when the
2697 ASDF system is loaded, you get a big red blinking light and a warning
2698 but that's all. @clon{} will still work, although in restricted mode.
2701 @c -------------------
2702 @c Dumping Executables
2703 @c -------------------
2704 @node Dumping Executables, , Supported Platforms, Technical Notes
2705 @section Dumping Executables
2707 Creating standalone executables is orthogonal to @clon{}. @clon{} is
2708 just a library that you might want to use, and in fact, it is also
2709 possible to use it without dumping executables at all.
2713 Unfortunately, there is no standard way to dump executables from Lisp.
2714 We're entering the portability mine field here. @clon{}, however, wants
2715 to help. We've already seen that it provides utility wrappers like
2716 @code{exit} and @code{dump} to make your life easier (I mean, more
2717 portable) in @ref{Quick Start}. If you're not interested in portability
2718 or if you prefer to do it your own way, you don't @emph{need} to use
2719 those wrappers. If you do, however, please read on.
2721 Continuing on the quickstart example, the table below provides
2722 ready-to-use @cmdline{} samples for dumping the program with the
2723 compilers currently supported. Remember that they work in conjunction
2724 with the @code{dump} macro mentionned above.
2728 @code{CC=gcc sbcl --script quickstart.lisp}@*
2729 The @code{CC=gcc} bit is needed for the @code{sb-grovel} contrib module
2732 @code{lisp -noinit -nositeinit -load quickstart.lisp}
2734 @code{ccl --no-init --load quickstart.lisp}
2736 ECL doesn't work like the other Lisp compilers. In particular, creating
2737 an executable does not involve dumping a Lisp image, but compiling the
2738 source into separate object files and then linking them. The consequence
2739 is that there is no simple @cmdline{} recipe to show here. Instead, you
2740 might want to look at the file @file{demos/dump.lisp} in the
2741 distribution for an example.
2743 Because the dumping scheme is different with ECL, it is also less
2744 straightforward to write portable code for standalone applications. The
2745 demo programs in the distribution both contain comments that are worth
2746 reading at the top of them.
2749 One specific difference between ECL and the other Lisp compilers is that
2750 it doesn't require you to specify a particular function as the entry
2751 point for your executable, but instead relies on having code to execute
2752 directly at the toplevel of some file. @clon{}'s @code{dump} macro helps
2753 you with this: it normally expands to a compiler-specific function which
2754 saves the current Lisp image, but for ECL, it simply expands to the
2755 ``main'' function call, hence consituting the entry point to the code
2758 @code{CC=gcc clisp -norc -i quickstart.lisp}@*
2759 The @code{CC=gcc} bit lets you choose your preferred C compiler for
2760 @code{cffi}. Please note that executables dumped (the @clon{} way) by
2761 CLISP still understand lisp-specific command-line options when they are
2762 prefixed with @code{--clisp-}, so you should obviously avoid defining
2763 options by those names.
2765 ABCL is a totally different beast because it's a Java-based @cl{}
2766 implementation. Most notably, you don't create standalone executables in
2767 Java, so the normal way of running ABCL is by telling it to load some
2768 lisp code. If you want to run the quickstart program in the usual way,
2769 you will typically type this:
2771 abcl --noinform --noinit --nosystem --load quickstart.lisp
2773 Note that for this to work, the @code{dump} macro expands to the
2774 ``main'' function call for ABCL, just as for ECL.
2776 There's more to it than that though. It is possible to get closer to
2777 standalone executables with ABCL by 1/ providing your whole application
2778 in a @code{jar} file directly, and 2/ overriding ABCL's entry point by
2779 providing your own interpreter which runs your main function
2780 automatically. I have described this process in more details in the
2781 following blog entry:
2782 @uref{http://www.didierverna.com/sciblog/index.php?post/2011/01/22/Towards-ABCL-Standalone-Executables}.
2785 @clon{} helps you to do this to some extend. If the @code{:dump}
2786 configuration option is set (@pxref{Configuration}), then the
2787 @code{dump} macro doesn't expand to a call to the ``main'' function, but
2788 instead dumps a Java file containing an alternate ABCL interpreter that
2789 you can compile and add to the original ABCL @code{jar} file, along with
2790 @file{quickstart.lisp}. If you want more details on this, you will need
2791 to look at the @file{Makefile} in the @code{demo} directory and also at
2792 the file @file{Makefile.inc} at the toplevel.
2797 @c ====================================================================
2798 @c API Quick Reference
2799 @c ====================================================================
2800 @node API Quick Reference, Indexes, Technical Notes, Top
2801 @appendix API Quick Reference
2804 * Utilities:: Miscellaneous stuff
2805 * Initialization Phase API:: Synopsis, items and context creation
2806 * Runtime Phase API:: Option retrieval and help formatting
2807 * Extension API:: New option types
2808 * Versioning API:: Release identification
2815 @node Utilities, Initialization Phase API, API Quick Reference, API Quick Reference
2818 @defmac dump NAME FUNCTION
2819 See @ref{Quick Start}.
2822 @defun exit &optional (STATUS 0)
2823 See @ref{Quick Start}.
2826 @cindex Command-Line
2828 See @ref{Option Retrieval}.
2831 @cindex Package, nicknames
2832 @defun nickname-package &optional NICKNAME
2833 See @ref{Quick Start}.
2837 @c ------------------------
2838 @c Initialization Phase API
2839 @c ------------------------
2840 @node Initialization Phase API, Runtime Phase API, Utilities, API Quick Reference
2841 @section Initialization Phase API
2843 @defun make-text &key CONTENTS HIDDEN
2844 @cfsubindex{make-text}
2845 @cfiaindex{make-text,:contents}
2846 @cfiaindex{make-text,:hidden}
2847 @defunx make-@var{OPTION} :INITARG INITVAL@dots{}
2848 @cfsubindex{make-@var{OPTION}}
2850 @cfindex make-stropt
2851 @cfindex make-lispobj
2854 @cfindex make-switch
2855 @cfindex make-xswitch
2856 @defunx make-group &key HEADER HIDDEN ITEM
2857 @cfsubindex{make-group}
2858 @cfiaindex{make-group,:header}
2859 @cfiaindex{make-group,:hidden}
2860 @cfiaindex{make-group,:item}
2861 @defunx make-synopsis &key POSTFIX ITEM (MAKE-DEFAULT t)
2862 @cfsubindex{make-synopsis}
2863 @cfiaindex{make-synopsis,:postfix}
2864 @cfiaindex{make-synopsis,:item}
2865 @cfiaindex{make-synopsis,:make-default}
2866 See @ref{Constructors} and @ref{Using Different Synopsis}.
2869 @defmac defgroup (&key HEADER HIDDEN) &body FORMS
2870 @foindex{defgroup,:header}
2871 @foindex{defgroup,:hidden}
2872 @xref{Group Definition}.
2875 @defmac defsynopsis (&key POSTFIX MAKE-DEFAULT) &body FORMS
2876 @foindex{defsynopsis,:postfix}
2877 @foindex{defsynopsis,:make-default}
2878 @fiindex{defsynopsis,text}
2879 @fiindex{defsynopsis,options}
2880 @fiindex{defsynopsis,group}
2881 See @ref{Synopsis Definition} and @ref{Using Different Synopsis}.
2884 @defopt *default-synopsis*
2885 @xref{Using Different Synopsis}.
2888 @defun make-context &key (SYNOPSIS *default-synopsis*) CMDLINE @
2890 @cfsubindex{make-context}
2891 @cfiaindex{make-context,:synopsis}
2892 @cfiaindex{make-context,:cmdline}
2893 @cfiaindex{make-context,:make-current}
2894 @xref{Context Creation}, @ref{Using Different Synopsis} and @ref{Using
2895 Different Command-Lines}.
2900 @c -----------------
2901 @c Runtime Phase API
2902 @c -----------------
2903 @node Runtime Phase API, Extension API, Initialization Phase API, API Quick Reference
2904 @section Runtime Phase API
2906 @defopt *current-context*
2907 @xref{Using Multiple Contexts}.
2910 @defun with-context CONTEXT &body BODY
2911 @xref{Using Multiple Contexts}.
2914 @defun progname &key (CONTEXT *current-context*)
2915 @fkindex{progname,:context}
2916 See @ref{Contextual Information} and @ref{Using Multiple Contexts}.
2919 @defun remainder &key (CONTEXT *current-context*)
2920 @fkindex{remainder,:context}
2921 See @ref{Contextual Information} and @ref{Using Multiple Contexts}.
2924 @defun cmdline-options-p &key (CONTEXT *current-context*)
2925 @fkindex{cmdline-options-p,:context}
2926 See @ref{Command-Line Polling} and @ref{Using Multiple Contexts}.
2929 @defun cmdline-p &key (CONTEXT *current-context*)
2930 @fkindex{cmdline-p,:context}
2931 See @ref{Command-Line Polling} and @ref{Using Multiple Contexts}.
2934 @defun getopt &key (CONTEXT *current-context*) SHORT-NAME LONG-NAME @
2936 @fkindex{getopt,:context}
2937 @fkindex{getopt,:short-name}
2938 @fkindex{getopt,:long-name}
2939 @fkindex{getopt,:option}
2940 @vindex *current-context*
2941 See @ref{Explicit Retrieval} and @ref{Using Multiple Contexts}.
2944 @defun getopt-cmdline &key (CONTEXT *current-context*)
2945 @fkindex{getopt-cmdline,:context}
2946 @vindex *current-context*
2947 See @ref{Sequential Retrieval} and @ref{Using Multiple Contexts}.
2950 @defmac multiple-value-getopt-cmdline (OPTION NAME VALUE SOURCE &key CONTEXT) @
2952 @defmacx do-cmdline-options (OPTION NAME VALUE SOURCE &key CONTEXT) @
2954 @foindex{multiple-value-getopt-cmdline,:context}
2955 @foindex{do-cmdline-options,:context}
2956 See @ref{Sequential Retrieval} and @ref{Using Multiple Contexts}.
2959 @deffn Reader short-name OPTION
2960 @rfsubindex{short-name}
2961 @deffnx Reader long-name OPTION
2962 @rfsubindex long-name
2963 @xref{Sequential Retrieval}.
2966 @defun help &key (CONTEXT *current-context*) @
2967 (ITEM (synopsis context)) @
2968 (OUTPUT-STREAM *standard-output*) @
2969 (SEARCH-PATH (search-path context)) @
2970 (THEME (theme context)) @
2971 (LINE-WIDTH (line-width context)) @
2972 (HIGHLIGHT (highlight context)))
2973 @fkindex{help,:context}
2974 @fkindex{help,:item}
2975 @fkindex{help,:output-stream}
2976 @fkindex{help,:theme}
2977 @fkindex{help,:search-path}
2978 @fkindex{help,:line-width}
2979 @fkindex{help,:highlight}
2980 @vindex *current-context*
2981 @vindex *standard-output*
2982 @xref{Help}, @ref{Using Multiple Contexts} and @ref{Programmatic Help
2990 @node Extension API, Versioning API, Runtime Phase API, API Quick Reference
2991 @section Extension API
2993 @defmac defoption CLASS SUPERCLASSES SLOTS &rest OPTIONS
2994 @pxref{New Option Classes}
2997 @deffn {Generic Function} check OPTION VALUE
2999 @xref{Value Check Protocol}.
3002 @deftp {Error Condition} option-error OPTION
3003 @ecsubindex{option-error}
3004 @ecsindex{option-error,option}
3005 @deftpx {Error Condition} invalid-value VALUE COMMENT
3006 @ecsubindex{invalid-value}
3007 @ecsindex{invalid-value,value}
3008 @ecsindex{invalid-value,comment}
3009 @xref{Value Check Protocol}.
3012 @deffn {Generic Function} convert OPTION ARGUMENT
3013 @gfsubindex{convert}
3014 @xref{Argument Conversion Protocol}.
3017 @deftp {Error Condition} invalid-argument ARGUMENT COMMENT
3018 @ecsubindex{invalid-argument}
3019 @ecsindex{invalid-argument,argument}
3020 @ecsindex{invalid-argument,comment}
3021 @xref{Argument Conversion Protocol}.
3024 @deffn {Generic Function} stringify OPTION VALUE
3025 @gfsubindex{stringify}
3026 @xref{Value Stringification Protocol}.
3033 @node Versioning API, , Extension API, API Quick Reference
3034 @section Versioning API
3036 @defun version &optional (TYPE :number)
3037 @xref{Version Numbering}.
3040 @defvr Constant +release-major-level+
3041 @defvrx Constant +release-minor-level+
3042 @defvrx Constant +release-status+
3043 @defvrx Constant +release-status-level+
3044 @defvrx Constant +release-name+
3045 @xref{Version Numbering}.
3050 @c ====================================================================
3052 @c ====================================================================
3053 @node Indexes, Acknowledgments, API Quick Reference, Top
3057 * Concept Index:: Well, the concept index
3058 * Function Index:: Well, the function index
3059 * Variable Index:: Well, the variable index
3060 * Data Type Index:: Well, the data type index
3067 @node Concept Index, Function Index, Indexes, Indexes
3076 @node Function Index, Variable Index, Concept Index, Indexes
3085 @node Variable Index, Data Type Index, Function Index, Indexes
3094 @node Data Type Index, , Variable Index, Indexes
3100 @c ====================================================================
3102 @c ====================================================================
3103 @node Acknowledgments, , Indexes, Top
3104 @appendix Acknowledgments
3105 The following people have contributed bug reports or fixes, suggestions,
3106 compiler support or any other kind of help. You have my gratitude!
3108 @multitable @columnfractions .99
3112 François-René Rideau@*
3119 @c LocalWords: Clon clon cmdline Clonification tty emph CmdLine clonified SGR
3120 @c LocalWords: clonfiscated clonistified clonificated clonificationated samp
3121 @c LocalWords: cindex subsubsection pxref Didier Nuker postfix Runtime cth
3122 @c LocalWords: cartouche toplevel prepended IEC
3124 @c user.texi ends here