Home

The Clon User Manual - LRDE

Contents

1. 19 30 31 Environment CLON_LINE_WIDTH 19 30 31 Environment CLON_SEARCH_PATH 19 30 31 Environment CLON_THEME 19 30 31 Environment COLUMNS 0 eee e eee eee 36 P Parameter release major level 31 Parameter release minor level 31 Parameter srelease namer 31 Parameter srelease statusr 31 Parameter release status level 31 S slime enable evaluate in emacs 35 Appendix C Indexes C 4 Data Types a Classes emm 13 21 22 23 25 Classes enmum base cece eee eee eee eee 21 Glasses Tlap nina 13 18 21 Classes lispobj 2 22ees sense 13 26 Classes option 12 21 Classes ENEE 13 Classes stropie seen 13 21 Classes Switch lul ipi E LER cae 14 Classes valued option 13 21 22 Classes xswitch 00 cece eee eee eee 14 21 O banaue IER 13 21 22 23 25 enun basen bise D IUe MELU rx e EA eS 21 Error Conditions invalid argument 23 43 Error Conditions invalid argument slots argument E e 23 43 Error Conditions invalid argument slots comment aaa iaa 23 43 Error Conditions invalid value 22 43 Error Conditions invalid value slots comment A es ELA EE MAI 22 43 Error Conditions invalid value slots value 22 43 Error Conditions option error 22 23 43 Error Conditions option error slots
2. Value Check Protocol ee 22 Value Stringification Protocol 24 Valued Options 0 cece eee eee eee 13 21 Valued Options common properties 13 Valued Options common properties argument name etui dd E 13 14 22 Valued Options common properties argument type vem i arena Mr EE NENA 13 14 Valued Options common properties default value oua ub ee verdes pret DTP ER Yos 13 18 24 Valued Options common properties fallback value 00 13 18 24 Valued Options Enumerations enum 13 21 22 23 25 Valued Options Enumerations enum properties O SP 13 21 22 23 Valued Options Extended Switches xswitch 14 21 Valued Options Extended Switches xswitch properties argument style 14 Appendix C Indexes Valued Options Extended Switches xswitch properties emm 14 21 Valued Options Lisp Objects lispobj 13 26 Valued Options Lisp Objects lispobj properties DUypespec an nn Ye nn 13 26 Valued Options Paths path 13 Valued Options Paths path properties type 13 Valued Options Strings stropt 13 21 47 Valued Options Switches switch 14 Valued Options Switches switch properties sargument style 6 cee eee eee 14 Values source command line 18 Values source default 13 18 24 Values source envir
3. 0 56 CMUCL gt 20b CCL ECL CLISP ABCL gt 1 1 0 Allegro both standard and modern and LispWorks Clon is provided as an ASDF 3 system but has no mandatory dependency CFFI may optionally be used with CLISP Allegro and LispWorks See Section A 3 Supported Platforms page 36 for more information See Clon s homepage for tarballs Git repository and online documentation Clon is also available via Quicklisp In order to install and load the bare Lisp library unpack it somewhere in the ASDF 3 source registry and type this at the REPL asdf load system net didierverna clon Alternatively if you just want to use the core library without all the platform dependent bells and whistles see Appendix A Technical Notes page 35 you can also just load the net didierverna clon core system In the general case and if you are using SBCL you may want to make sure that the CC environment variable is set to your favorite C compiler in your init file Otherwise Clon will run in restricted mode see Appendix A Technical Notes page 35 For instance put this in your sbelrc require sb posix sb posix setenv CC gcc 1 In addition to the library itself the Clon distribution offers documentation in the form of 3 different manuals some data files like sample themes see Section Theme Creation in The Clon End User Manual and a couple of demonstration programs If you want to benefit from all those wonders some b
4. Clon checks all of those I think Since those mistakes relate to the definition of the application itself they do not depend on a particular execution of it Consequently the sooner Clon catches them the better If you define your application s synopsis as a toplevel form Clon will be able to perform its integrity checks when the application is created not only when it is used In other words you won t be able to get a working application until your use of Clon is semantically correct This is why it is strongly recommended to create synopsis from toplevel forms and this also explains why Clon chooses not to provide an initialize function that would wrap around defsynopsis and make context together 4 4 Option Retrieval During the runtime phase of Clon your main activity will be to retrieve options and their values Clon provides two techniques for retrieving options you can request the value for a specific option directly or you can process the command line sequentially which is the more traditional approach Both of these techniques can be freely combined together at any time because Clon keeps track of the current status of the command line In fact Clon never works on the original command line but uses a mutable copy of it after parsing If you want to access the real command line of your application except for the compiler specific options see Section A 5 Not Dumping Executables page 38 you may use the cmdline function
5. Constructors make synopsis initargs imake def ult ua es 29 41 Constructors make synopsis initargs postfix PA pA NED 15 41 Constructors make text 2220 14 15 41 Constructors make text initargs contents 15 41 Constructors make text initargs hidden 15 41 Constructors make xswitch 15 41 CONVERTS cu N ren 23 43 convert methods Enumerations enum 23 24 D a A E RS 16 25 26 41 defgroup options header 12 16 41 defgroup options hidden 12 16 41 defoption oi ia ee ee 21 26 43 defsynopsis 8 11 14 15 17 25 26 41 defsynopsis epD ngion ee nen 14 defsynopsis items group 8 12 16 41 defsynopsis items options 8 12 41 defsynopsis items text 8 11 41 defsynopsis options make default 29 41 defsynopsis options postfix 8 11 41 do cmdline options ss 8 19 29 42 do cmdline options options context 30 42 AUR ee 9 24 36 37 38 41 The Clon User Manual Generic Functions check 22 43 Generic Functions check methods Enumerations Lengt dee EE ER Generic Functions convert 20 23 43 Generic Functions convert methods Enumerations A ae Dre abes 23 24 Generic Functions stringify 25 43 Generic Functions stringify methods Enumerations emm 25 gBetopt cei LIII 8 18
6. consequence there is currently no simple way to have a single set of built in options apply to the whole application for instance to both a global and a command specific context Let me make this clearer if your end user calls prog clon theme foo command h then the theme option will have no effect because it would only affect the global help option In order to actually use the expected theme your end user would need to use prog command clon theme foo h Depending on which cerebral emisphere s he prefers to use this may seem logical or not Finally note that you can use the virtual command line specific synopsis technique re cursively to manage complicated command line syntax for instance alternating options and non options parts several times In the future Clon may provide better ways to achieve this kind of things a notion of sub context may be in order Chapter 6 Advanced Usage 31 6 2 Programmatic Help Strings So far we ve seen how to use the help function to implement a typical help option This is mostly intended for the end user There are also times when this function could be useful to you the application developer For instance one could imagine that part of the compilation phase would involve generating the help string in order to include it in the manual Another idea would be that make install creates a REFCARD file in usr local share doc my app which contains the help string formatted with
7. file make config make 38 The Clon User Manual Allegro Dumping a complete application with Allegro is complicated but more importantly only possible in the Enterprise edition Because of that Clon s dumping facility only makes use of the dumplisp feature which just dumps a Lisp image You can per form this operation with a command line such as alisp qq L quickstart lisp The Makefile infrastructure in the demo directory also creates shell script wrappers around this image to simplify their use LispWorks lispworks init siteinit load quickstart lisp Please note that dumping a complete application with LispWorks is only possible in the Professional or Enterprise editions A 5 Not Dumping Executables Although command line processing really makes sense for standalone executables you may want to preserve interactivity with your application during the development phase for instance for testing or debugging purposes It is possible to use Clon interactively that is within a regular Lisp REPL without dumping anything First of all we have already seen that it is possible to use a virtual command line see Section 6 1 2 Using Different Command Lines page 29 You can also use Clon interactively with the actual Lisp invocation s command line although a word of advice is in order here As you might expect the problem in that situation lies in the way the different Lisp im plementations treat their own command line Gues
8. numbers this is as if the corresponding status level was considered to be always 0 Only stable releases have their level taken into account 32 The Clon User Manual e A short version will appear like this for unstable releases 1 3a4 2 5b8 or 4 2rc1 Remem ber that alpha beta or release candidate levels start at 1 Patchlevels for stable releases start at 0 but 0 is ignored in the output So for instance version 4 3 2 will appear as is while version 1 3 0 will appear as just 1 3 e A Long version is expanded from the short one and includes the release name For instance 1 3 alpha 4 Bill Evans 2 5 beta 8 Scott Henderson 4 2 release candidate 1 Herbie Hancock or 4 3 2 Chick Corea As for the short version a patchlevel of 0 is ignored in the output 1 3 Bill Evans Chapter 7 Conclusion 33 7 Conclusion So that s it I guess You know all about Clon now The next step is to actually use it to clonify your favorite application write new applications using it and contaminate the world with standalone Common Lisp programs featuring unprecedented command line power and thrill a minute option hacking Now go Luke The Attack of the Clon is ready to begin Appendix A Technical Notes 35 Appendix A Technical Notes This chapter contains important information about the library s configuration supported plat forms non ANSI features and portability concerns A 1 Configuration Some aspects of Clon s behavior can b
9. option 22 23 43 invalid argument cc cee eee eee 23 43 invalid argument slots argument 23 43 invalid argument slots comment 23 43 EECH EE 22 43 invalid value slots comment 22 43 invalid value slots value 22 43 5l LIDO NEE 13 26 net didierverna cloM ooooooo oooooo 5 7 21 net didierverna clon core 5 35 net didierverna con eetup eese 39 BETEN EE 12 21 Option Classes enum 13 21 22 23 25 Option Classes flag 13 18 21 Option Classes lispobj 13 26 Option Classes path eee 13 Option Classes stropt co 13 21 Option Classes sgitch cece eee eee eee 14 Option Classes zegitch 14 21 Option error sess rises hrs 22 23 43 option error slots option 22 23 43 Packages net didierverna clon 7 21 Packages net didierverna clon setup 35 paths hj ss ism eese 13 AE euren lt e uu peo ta 13 21 o deret DEI 14 Systems net didierverna clon 5 7 Systems net didierverna clon core 5 35 Systems net didierverna clon setup 35 valued option eee eee 13 21 22 X o ke ves ud en E e Ee 14 21 Appendix D Acknowledgments 53 Appendix D Acknowledgments The following people have contributed bug reports or fixes suggestions compiler support or any other kind of help You have my grati
10. program called simple in the distribution z in package cl user require asdf asdf load system net didierverna clon use package net didierverna clon defsynopsis postfix FILES text contents A very short program group header Immediate exit options flag short name h long name help description Print this help and exit flag short name v long name version description Print version number and exit defun main Entry point for our standalone application make context when getopt short name h help exit do cmdline options option name value source print list option name value source terpri exit dump quickstart main 3 2 Explanation Let s examine this program step by step now First we put ourselves in the Common Lisp user package and load Clon from its ASDF system net didierverna clon Next we use the Clon package also named net didierverna clon a in package cl user require asdf asdf load system net didierverna clon use package net didierverna clon 8 The Clon User Manual In fact using the Clon package directly is done here for simplicity but is not recommended In case you find the package name too long to prefix every symbol with Clon provides a util ity function that allows you to add and use a shorter nickname instead the demonstration programs in the distribution sho
11. type Properly defined option types are a good thing because they allow for reusability and also extensibility since new option types can always be defined on top of others In this chapter we explain how to extend Clon by providing new option types We illustrate the process with the example of the built in enum one Oh and I almost forgot I hope it is obvious to everyone that new option types are always valued There s no point in extending Clon with options that don t take any arguments since we already have flags 5 1 New Option Types From a software engineering point of view it is better to implement new option types in a file of their own preferably named after the option type itself and to put this file in the Clon package like this in package net didierverna clon Creating your own option type involves 5 steps providing a class for them implementing three protocols related to argument value tweaking and providing a constructor function We now review those 5 steps in order 5 1 1 New Option Classes Clon maintains a class hierarchy for all option types The mother of all option types is the option abstract class It handles the options short and long names description and associated environment variable see Section 4 1 2 1 Common Properties page 12 Valued options inherit from an abstract subclass of option called valued option This class handles the option s argu ment name and status optional or mandat
12. which is a wrapper around an implementation dependent way to access it Finally remember that the command line is scanned from left to right during option retrieval see Section Option Retrieval in The Clon End User Manual 18 The Clon User Manual 4 4 1 Explicit Retrieval Since Clon lets you retrieve options on demand at any time it makes sense to be able to request the value of a specific option explicitely For instance you might want to try the help option first without looking at the rest of the command line because the application will in fact quit immediately after having displayed the help string getopt KEY VALUE Function Retrieve the value of a specific option The following KEYs are currently available short name long name Use one of these 2 keys to specify the name of the option you wish to retrieve option Alternatively you can use a reference to an option object see Section 4 1 3 1 Constructors page 14 This function return two values the option s value and the value s source see Section Value Sources in The Clon End User Manual The value s source may have the following forms N cmdline NAME This is for options found on the command line NAME is the name used on the command line It can be the option s long or short name or a completed long name if the option s name was abbreviated A completed name displays the omitted parts in parentheses he 1p for ins
13. 1 2 3 Common Valued Option Properties 0c cece eee eee eee 13 4 1 2 4 Built In Valued Options ssseessssseeese m ns 13 4 1 3 Advanced Synopsis Creation isses 14 4 L 3 D ConStructotss cia st tit a hada RR ee IRRE Dade Lt an 14 4 11 3 2 Advantages ity A Bei IP HET eet 15 4 1 3 3 Group Definition id e hehe 16 4 2 Context Cr ation vo A ears a pet m da etes eos 16 42 1 Making A Context ir nitet eee o ooo o e e be ala 16 4 22 Contextual Informationc ic co exe Ge odes REC LER NERO aa Re ERE 16 4 2 2 1 Program Name i sais bee ela eee ad UU EUER ANE ARS US 16 4 2 2 2 Command Line Remainder ee 16 4 2 2 3 Command Line Polling ssseessseseesses en 17 4 3 Integrity Checke nez koe hea RR HL ea I diene ea D 17 4 4 Option Retrieved ames 17 AAT Explicit Retrieval uso anche Lei eene da whois 18 4 42 Sequential Retrieval oooooooccccoccccccnnnncro e hee 18 ALS Help bevor ee a eee Seas ar Tte se teeth c iden Un de Me ENG ete ean ads 19 5s Wuxtendine Clan nce ede Res E e ern 21 5 1 New Option Types ee anne ERR Rx nn RR aad bees 21 5 1 1 New Option Cla8868 un tees pesi a 21 ALE Value Gheck Protocolsc iia ose eek At A air 22 5 1 3 Argument Conversion Protocol 0 0 cece eee eee eens 23 ALA Error Management eed gee ee ale Be ea 24 5 1 5 Value Stringification Protocol 0 ccc cece nee nent eas 24 5 1 6 Constr ctor Burictiong 2i ge a ER
14. 29 42 getopt keys contert 30 42 getopt keys long name 18 42 getopt keys option 18 42 getopt keys short name 8 18 42 getopt cmdline snasnsuussn rno 18 29 42 getopt cmdline keys context 30 42 H help suisses unge 8 19 29 30 31 42 help keys contest 2 eee ee ee eee 30 42 help keys highlight 31 42 help keys dtem io 21 iria 19 42 help keys line width 31 42 help keys output stream 31 42 help keys search path 31 42 help keys theme cece eee 31 42 L make c ntext ici der 8 16 17 29 41 make context initargs cmdline 29 41 make context initargs make current 29 41 make context initargs synopsis 29 41 EE 15 25 41 Make flag iti jcc nie E ges 14 15 41 UE e EE 14 15 41 make group initargs header 15 41 make group initargs hidden 15 41 make group initargs item 15 41 make lispobj ti seira eent cece eee eee 15 41 make OPTION e EN ANERE EES ee AH 15 41 Make path r r rasen ae 15 41 make Stropt co xcv Re EN PEETER OA 15 41 MAKCASWAC GH tases ca pee ed eer pru TER AE eR 15 41 make synopsisS cs en 14 15 41 make synopsis initargs item 15 41 make synopsis initargs make defau
15. 3 Options valued Strings stropt 13 21 Options valued Switches switch 14 Options valued Switches switch properties argument sStgle 0 cee eee 14 P Package nicknames 0 e eee eee eee 8 41 The Clon User Manual P ths path ie dee 13 Paths path properties tepe esses 13 Phase initialization oooooocooommmm 11 16 Phase runtime rauhen 17 Polling of command line 2er2220 17 Postfix xe censis e ae ie eek 8 11 30 Protocols argument copvergion s s ssrsrres 23 Protocols value check 22 Protocols value stringification 24 R Remainder of command line 11 16 30 38 Restricted Mode 35 36 Retrieval of options 00 eee eee eee eee 17 Retrieval of options explicit 8 18 Retrieval of options sequential 8 18 Runtime Phase 17 29 S Standard Themes refcard 22 31 Strings StrOpt iii capo No ten 13 21 Switches Legitch 14 Switches switch properties argument style 14 SYHOBSISE sehen pre Ru ru iR RAV E 8 11 Synopsis defa lt 222 i234 ENEE ce eben 29 My NT 11 Text contents 2 3 4 he en sa ales 11 Text hidden uic Rr E E 12 Text in groups Ee E sti papas rd ada 12 Text in SyBoOpSlS vec EV en a 8 11 NR 3l Themes standard refcard 3l U User Defined Option Classes 21 y
16. 50 CA Data Eng e gern re I nig eee ee Le eu 51 Appendix D Acknowledgments 53 Copying Copying Permission to use copy modify and distribute this software for any purpose with or without fee is hereby granted provided that the above copyright notice and this permission notice appear in all copies THIS SOFTWARE IS PROVIDED AS IS AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL DIRECT INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHAT SOEVER RESULTING FROM LOSS OF USE DATA OR PROFITS WHETHER IN AN ACTION OF CONTRACT NEGLIGENCE OR OTHER TORTIOUS AC TION ARISING OUT OF OR IN CONNECTION WITH THE USE OR PER FORMANCE OF THIS SOFTWARE Chapter 1 Introduction 3 1 Introduction Clon is a library for managing command line options in standalone Common Lisp applications It provides a unified option syntax with both short and long names automatic completion of partial names and automatic retrieval conversion of option arguments from the command line associated environment variables fallback or default values Clon comes with a set of extensible option types switches paths strings etc Clon also provides automatic generation and formatting of help strings with support for highlighting on tty s through ISO IEC 6429 SGR This formatting is customizable t
17. DE ken 25 9 2 Extension TIPS deren Raa ee we EOD ae 26 The Clon User Manual 5 2 1 Incremental Option Types 0 cece eee nen 26 5 2 2 Lisp Optim Abuse wee sles ee wen aed ea in e ii ee 26 6 Advanced Usage essen reale reed 29 6 1 Multiple Clon Instances dizi 2 les lien 29 6 1 1 Using Different SBenopgie 000 eee nee e nent e nee e eens 29 6 1 2 Using Different Command Lines 0 eee e 29 6 1 3 Using Multiple Context 29 6 1 4 Potential Uses ma 30 6 2 Programmatic Help Strings mr wann ee ea ra 31 6 3 Version Numbering c al AA PRAA AE EERE E ERI ee 31 T CONCISO AA d d n ERNEST 33 Appendix A Technical Notes 35 SN EE 35 A 2 Non ANSI Features 35 A 3 Supported Platforms ea ner een ea 36 CLISP Allegro and LispWorks specificities 0 00 e cece cece eens 36 ABGL Specifleities a tia 36 A A Dumping Raxecutables 0000 c cece eee m eeeeenes 36 A 5 Not Dumping Executables 0 000 E cence ne 38 Appendix B API Quick Reference 41 Bil EE A A Ana LP ER A E NE en 41 B 2 Utilities ics nee Henn ul eee aw wale 41 B Initialization Phase PI cu seen teret nina ku 41 BA Runtime Phase AR NEEN nennen nee 42 Bh Extensi n APLI nn 43 BE Versioning API sienne ee a an der anne 43 Appendix C dee 45 CL EE 45 CZ P nction8z em desee ie RR pea eee tag DER Ha E gant rn 48 C3 Variables acortar ae pereo t e edo ra ag edle rego taker
18. E is the option s short name without the dash It defaults to nil LONG NAME is the option s long name without the double dash It defaults to nil DESCRIPTION is the option s description appearing in help strings It defaults to nil ARGUMENT NAME is the option s argument name appearing in help strings ARGUMENT TYPE is one of required mandatory or optional required and mandatory are synonyms It defaults to optional ENUM is the set of possible values ENV VAR is the option s associated environment variable It defaults to nil FALLBACK VALUE is the option s fallback value for missing optional arguments if any DEFAULT VALUE is the option s default value if any When HIDDEN the option doesn t appear in help strings declare ignore short name long name description argument name argument type enum env var fallback value default value hidden apply make instance enum keys y Woah what a mouthful for a single line of code Yeah Pm a maniac and I like redundancy I always restate all the available keys explicitely and everything again in the docstring so that all the interesting information is directly available I might change my mind as I grow older though 5 2 Extension Tips So that s it Now you know how to extend Clon with your own option types Here is some piece of advice that you might find useful in the process 5 2 1 Incremental Option Types If
19. NT t See Section 4 2 Context Creation page 16 Section 6 1 1 Using Different Synopsis page 29 and Section 6 1 2 Using Different Command Lines page 29 42 The Clon User Manual B 4 Runtime Phase API context User Option See Section 6 1 3 Using Multiple Contexts page 29 with context CONTEXT amp body BODY Function See Section 6 1 3 Using Multiple Contexts page 29 progname amp key CONTEXT context Function See Section 4 2 2 Contextual Information page 16 and Section 6 1 3 Using Multiple Con texts page 29 remainder amp key CONTEXT context Function See Section 4 2 2 Contextual Information page 16 and Section 6 1 3 Using Multiple Con texts page 29 cmdline options p amp key CONTEXT context Function See Section 4 2 2 3 Command Line Polling page 17 and Section 6 1 3 Using Multiple Con texts page 29 cmdline p amp key CONTEXT context Function See Section 4 2 2 3 Command Line Polling page 17 and Section 6 1 3 Using Multiple Con texts page 29 getopt amp key CONTEXT context SHORT NAME LONG NAME Function OPTION See Section 4 4 1 Explicit Retrieval page 18 and Section 6 1 3 Using Multiple Contexts page 29 getopt cmdline amp key CONTEXT context Function See Section 4 4 2 Sequential Retrieval page 18 and Section 6 1 3 Using Multiple Contexts page 29 multiple value getopt cmdline OPTION NAME VALUE SOURCE amp key Macro CONTEXT amp b
20. T Generic Function Convert ARGUMENT to OPTION s value If ARGUMENT is invalid raise an invalid argument error As you can see you need to provide a method with the first argument specialized to your new option type This method must return the conversion of ARGUMENT to the appropriate type if it is valid and raise an invalid argument error otherwise The invalid argument error condition is defined like this a define condition invalid argument option error argument documentation The invalid argument type string initarg argument reader argument comment documentation An additional comment about the error type string initarg comment reader comment report lambda error stream format stream Option A invalid argument S 0 4 A option error argument error comment error documentation An invalid argument error When the error is raised you must fill in the argument and comment slots appropriately As before the super condition option error provides an additional option slot that you must also fill in when the error is raised Let s look at the enumeration example now 24 The Clon User Manual 7 defmethod convert enum enum argument Convert ARGUMENT to an ENUM value or closest match argument enum enum ignore case t key symbol name error invalid argument option enum argument argument comment format nil Valid arguments are A list to
21. The Clon User Manual The Command Line Options Nuker Version 1 0 beta 24 Michael Brecker Didier Verna lt didier didierverna net gt Copyright 2010 2012 2015 Didier Verna Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying provided also that the section entitled Copy ing is included exactly as in the original Permission is granted to copy and distribute translations of this manual into an other language under the above conditions for modified versions except that this permission notice may be translated as well Cover art by Alexis Angelidis Table of Contents COPE ere Ge e A d AAA as 1 T Introduetion ad DAA re 3 2 Installations nas tee adt ac t ade teo aed 9 3 Mc SUE ceno wies eet e ra tabe S te vaca um tp RN ade 7 O A A aee ao atte tto eae tar 7 9 2 Explanation e nassen bae eere TRUE e redet icis 7 ds sme Clones re E Dee Nee 11 41 Synopsis Definition wo u ma een 11 4 LI Synopsis Items rs ae are ehe 11 ADV Val Alters o ea na e bee de o an dece etes 11 4 1 1 2 ee s oii stp da DABEI Ute Ape ane 12 A GIO ida 12 4 1 2 Built In Option Types x ii a a 12 4 1 2 1 Common Properties iu tn E ERE eds 12 41 2 2 Flags ie iiu ee p Ep RR ede ER A E RU NC eem uns 13 4
22. a een hee ge 12 Groups in synopsis sees 8 12 16 H Header in group 12 Help String 8 11 12 15 19 24 31 Help String display 00 eee ee eee 8 30 Hidden Groups 12 19 Hidden Options cece ee eee eee a 12 Hidden Textiel espese ae leeren 12 I Initialization Phase 11 16 L Lisp Objects spob i 13 26 Lisp Objects lispobj properties typespec 13 26 O Option Classes user defined o n ununeuuuenn 21 46 Option Constructors lessen 25 Option Types buibt Am eee eee 12 Option Types built in valued 13 Option Types in Des 21 Option Types valued 0 eee eee eee ee 13 Options sxe ae tan e eae AE ripe ea 12 Options Hetrieval 0 cee eee eee eee eee 17 Options Retrieval explicit 2 8 18 Options Retrieval sequential 8 18 Options built in types 0 eee eee eee eee 12 Options built in types valued 13 Options built in clon help 12 19 Options built in clon highlight 14 19 30 31 36 Options built in clon line width 13 19 30 31 36 Options built in clon search path 13 19 30 31 Options built in clon theme 13 19 30 31 Options built in clon version 13 31 Options common properties 000 12 Options common properties description 12 O
23. a remainder see Section Option Separator in The Clon End User Manual ABCL ABCL processes its own options and leaves the others unprocessed on the command line This means that as long as there is no overlap between ABCL s options and yours you can just put them all together on the command line In case of overlap however you need to separate ABCL s options from yours with a separator Note that you can still use a second such separator to provide Clon with both some Appendix A Technical Notes 39 Allegro LispWorks options and a remainder see Section Option Separator in The Clon End User Manual Allegro processes its own options issues only a warning about options it doesn t know of and leaves anything after a alone Consequently if you want to provide options to your application you need to put them after a separator Note that you can still use a second such separator to provide Clon with both some options and a remainder see Section Option Separator in The Clon End User Manual LispWorks processes its own options and ignores the other ones but always leaves everything on the command line It does not currently support as an option separator either Consequently if you want to provide options to your application you need to put them after a separator although you will get into trouble if any option there is recognized by LispWorks itself Note that you can still use a second such separ
24. alue of context All subsequent calls to the runtime phase API will hence use this other context 2 Clon also provides a macro which changes the current context for you 30 The Clon User Manual with context CONTEXT amp body BODY Function Execute BODY with context bound to CONTEXT 3 If you prefer to use another context only once you can use the context key in stead The whole runtime phase API of Clon understands it For the functions getopt getopt cmdline and help it s just another key in addition to those we ve already seen For the macros multiple value getopt cmdline and do cmdline options the key must appear at the end of the first list argument like this multiple value getopt cmdline option name value context ctx do cmdline options option name value context ctx 6 1 4 Potential Uses By combining Clon s ability to use a virtual command line different synopsis and multiple contexts you can achieve very neat read totally useless things For instance you could write an application that takes an option providing command line arguments for an external program to be forked Some revision control systems do that for controlling external diff programs for instance so no big deal The big deal is that you can completely control the validity of the external program s command line before it is forked from your original one Here is another idea again related to revision control systems Some of them f
25. ator to provide Clon with both some options and a remainder see Section Option Separator in The Clon End User Manual Appendix B API Quick Reference 41 Appendix B API Quick Reference B 1 Setup configure KEY VALUE Function See Section A 1 Configuration page 35 configuration KEY Function See Section A 1 Configuration page 35 B 2 Utilities dump NAME FUNCTION amp rest ARGS Macro See Chapter 3 Quick Start page 7 exit amp optional STATUS 0 Function See Chapter 3 Quick Start page 7 cmdline Function See Section 4 4 Option Retrieval page 17 nickname package amp optional NICKNAME Function See Chapter 3 Quick Start page 7 B 3 Initialization Phase API make text amp key CONTENTS HIDDEN Function make OPTION INITARG INITVAL Function make group amp key HEADER HIDDEN ITEM Function make synopsis amp key POSTFIX ITEM MAKE DEFAULT t Function See Section 4 1 3 1 Constructors page 14 and Section 6 1 1 Using Different Synopsis page 29 defgroup amp key HEADER HIDDEN amp body FORMS Macro See Section 4 1 3 3 Group Definition page 16 defsynopsis amp key POSTFIX MAKE DEFAULT amp body FORMS Macro See Section 4 1 Synopsis Definition page 11 and Section 6 1 1 Using Different Synopsis page 29 synopsis User Option See Section 6 1 1 Using Different Synopsis page 29 make context amp key SYNOPSIS synopsis CMDLINE Function MAKE CURRE
26. bles Creating standalone executables is orthogonal to Clon Clon is just a library that you might want to use and in fact it is also possible to use it without dumping executables at all see Section A 5 Not Dumping Executables page 38 Unfortunately there is no standard way to dump executables from Lisp We re entering the portability mine field here Clon however wants to help We ve already seen that it provides utility wrappers like exit and dump to make your life easier I mean more portable in Chapter 3 Quick Start page 7 If you re not interested in portability or if you prefer to do it your own way you don t need to use those wrappers If you do however please read on 1 more precisely git revision 3e2e5f9dc3c5176ef6ef8d7794bfa43flaf8f8db more precisely svn trunk revision 140640 3 both standard and modern images are supported Appendix A Technical Notes 37 Continuing on the quickstart example the table below provides ready to use command line samples for dumping the program with the compilers currently supported Remember that they work in conjunction with the somewhat rudimentary dump macro mentionned above SBCL CMUCL CCL ECL CLISP ABCL CC gcc sbcl script quickstart lisp The CC gcc bit is needed for the sb grovel contrib module that Clon uses unless restricted mode is requested lisp noinit nositeinit load quickstart lisp ccl no init load quickstart lisp ECL doesn t work like th
27. called argumentize or even deconvertify As you can see you need to provide a method with the first argument specialized to your new option type You can assume that VALUE is a valid value for your option so no checking is necessary and no error needs to be raised Let s look at the enumeration example now defmethod stringify enum enum value Transform ENUM s VALUE into an argument string downcase symbol name value Pretty straightforward right 5 1 6 Constructor Functions The last required step to complete our new option type extension is to provide a constructor function that wraps around make instance on the corresponding option class I won t insult you by explaining how to write a constructor Let me just give four good reasons why providing constructors is important Providing a constructor for every new option type is important because 1 it is important 2 it isa good software engineering practice 3 it is important 4 and above all it makes your new option type automatically available in calls to defsynopsis and defgroup see Section 4 1 1 Synopsis Items page 11 and Section 4 1 3 3 Group Defi nition page 16 Let s look at the enumeration example now 26 The Clon User Manual gt gt defun make enum amp rest keys amp key short name long name description argument name argument type enum env var fallback value default value hidden Make a new enum option SHORT NAM
28. ch is expected Possible values are file directory file list directory list or nil meaning that anything is allowed Null paths are al lowed and may be provided by an empty argument Look at the clon search path and clon theme built in options for examples 14 The Clon User Manual switch This option type is for Boolean options switch options change their default argument type from required to optional and provide a fallback value of t au tomatically for optional arguments switch options provide a new property called argument style Possible values are yes no the default on off true false yup nope yeah nah This property affects the way the argument name and true or false values are advertized in help strings However all possible arguments forms see Section Switches in The Clon End User Manual are always available to all switches xswitch This option type stands for extended switch Extended switches result from the mating of a male switch and a female enumeration or the other way around ele mentary decency prevents me from describing this mating process in detail their possible values are either Boolean or from an enum property as in the case of enum options As simple switches xswitch options change their default argument type from required to optional and provide a fallback value of t automatically for optional arguments They also provide the argument style property Contrary to switches however
29. e configured before the library is actually loaded Clon stores its user level configuration along with some other setup parameters in another ASDF system called net didierverna clon setup and the eponym package In order to configure the library I repeat prior to loading it you will typically do something like this require asdf asdf load system net didierverna clon setup net didierverna clon setup configure option lt value gt configure KEY VALUE Function Set KEY to VALUE in the current Clon configuration Out of curiosity you can also inquire the current configuration for specific options with the following function configuration KEY Function Return KEY s value in the current Clon configuration Currently the following options are provided swank eval in emacs This option is only useful if you use Slime and mostly if you plan on hacking Clon itself The library provides indentation information for some of its functions directly embedded in the code This information can be automatically transmit ted to X Emacs when the ASDF system is loaded if you set this option to t However note that for this to work the Slime variable slime enable evaluate in emacs must also be set to t in your X Emacs session If you re interested to know how this process works I have described it in the following blog en try http www didierverna com sciblog index php post 2011 07 20 One more indentation hac
30. e other Lisp compilers In particular creating an executable does not involve dumping a Lisp image but compiling the source into separate object files and then linking them The consequence is that there is no simple command line recipe to show here Instead you might want to look at the file demos dump lisp in the distribution for an example Note that this file doesn t really attempt to dump the whole application Only the actual example file is dumped Because the dumping scheme is different with ECL it is also less straightforward to write portable code for standalone applications The demo programs in the distribution both contain comments that are worth reading at the top of them One specific difference between ECL and the other Lisp compilers is that it doesn t require you to specify a particular function as the entry point for your executable but instead relies on having code to execute directly at the toplevel of some file Clon s dump macro helps you with this it normally expands to a compiler specific function which saves the current Lisp image but for ECL it simply expands to the main function call hence consituting the entry point to the code that ECL needs CC gcc clisp norc i quickstart lisp The CC gcc bit lets you choose your preferred C compiler for cffi Please note that executables dumped the Clon way by CLISP still understand lisp specific command line options when they are prefixed with clisp so you sho
31. e to automatically display a help string if the command line is effectively empty 4 3 Integrity Checks At this point you know about the two necessary steps to initialize Clon defining a synopsis and creating a context If you paid attention to the quick start application see Chapter 3 Quick Start page 7 you may have noticed that defsynopsis was called as a top level form whereas make context was called from the function main So why the difference First I hope that you see why a context cannot be created as a toplevel form If you do that you will end up creating a context relevant to the Lisp environment from which the application is created not run The synopsis on the other hand could be defined either as a toplevel form as done in the quick start and the demo programs or in the function main just before making a context There is a very good reason to prefer a toplevel form however that reason is called integrity checks When you define a synopsis or any synopsis item for that matter Clon performs a number of checks to make sure that you re making a sensible use of the library In fact the number of semantic mistakes that you can make is quite puzzling You could for instance define several options with identical names forget to provide a fallback or default value when it is required provide invalid fallback or default values and the list goes on and on These are just a few examples but there are many more and
32. eature a command line syntax like the following prog global options command command specific options You can achieve this with Clon quite easily In fact the demonstration program called advanced in the distribution shows you how to do it First define a synopsis which only handles the global options and provide a postfix of command command specific option or something like that This will authorize a command line remainder which will start with the command name Now for every command in your program define a specific synopsis with only the command specific options Get the remainder of the original command line see Section 4 2 2 2 Command Line Remainder page 16 and figure out which command was used Depending on it create a new context with the appropriate synopsis and the original command line s remainder as the new virtual command line You re done retrieve global options from the first context and command specific ones from the second one What s even cooler is that you can display the command specific options on demand quite easily as well like what git does when you call it like this git commit help for instance calling the help function on the original context gives you the global options s help string while calling it on the command specific one will display the command specific usage One thing to remember here is that every context synopsis duet you create gets its own set of built in Clon options As a
33. ed you must fill in the value and comment slots appropriately The super condition option error provides an additional option slot that you must also fill in when the error is raised Let s look at the enumeration example now Chapter 5 Extending Clon 23 C defmethod check enum enum value Check that VALUE is a valid ENUM unless member value enum enum error invalid value option enum value value comment format nil Valid values are A list to string enum enum key prini to string value This code should be self explanatory We check that the value we got belongs to the enu meration list to string is a utility function that will separate every element with comas in the resulting string 5 1 3 Argument Conversion Protocol The next protocol we need to implement is the so called argument conversion protocol This protocol is used to convert option arguments that is strings to an actual value of the proper type Arguments going through this protocol come from the command line the value of an environment variable or a debugger restart see Section Error Management in The Clon End User Manual Also note that Clon assumes that you implement this protocol correctly so no value check is performed on values coming from the conversion of an argument The conversion protocol is implemented through a convert generic function for which you must provide a method convert OPTION ARGUMEN
34. g to make context instead 6 1 2 Using Different Command Lines In Section 4 2 Context Creation page 16 we saw that a context object describes a particular instance of your application most notably depending on the actual command line the end user provided It turns out however that the command line doesn t need to be the actual program s command line as the user typed it Any list of strings can act as a command line The function make context has a cmdline key that allows you to provide any list of strings that will act as the command line Of course the default is to use the actual program s one 6 1 3 Using Multiple Contexts Did you also notice that after creating a context there is actually never any explicit reference to it anymore So again where is the magick In fact there s no magick at all involved here either Clon has a global variable named context which holds the current context When you create a context with make context it is automatically made current unless you use the make current initarg with a value of nil The whole runtime phase API of Clon uses a context implicitely This involves prognane remainder cmdline options p cmdline p getopt getopt cmdline multiple value getopt cmdline do cmdline options and help As a consequence it is possible to use Clon with multiple contexts at the same time There are in fact three ways to achieve this 1 At any time in your program you may change the v
35. g name but did I really need to mention this Chapter 4 Using Clon 13 4 1 2 2 Flags In Clon options that don t take any argument are of type flag These options don t provide additional properties on top of the common set described in Section 4 1 2 1 Common Properties page 12 All properties default to nil 4 1 2 3 Common Valued Option Properties All non flag options in Clon are said to be valued All valued options including those you define yourself see Section 5 1 New Option Types page 21 share a set of additional properties Here is a list of them argument name The name of the option s argument as it appears in the help string It defaults to ARG so that for instance a name option would appear like this name ARG argument type The status of the argument Possible values are required the default and mandatory which are synonyms or optional fallback value default value The option s fallback and default values Remember that a fallback value only makes sense when the argument is optional Besides also when the argument is optional you need to provide at least a fallback or a default value or both of course see Section Value Sources in The Clon End User Manual 4 1 2 4 Built In Valued Options Clon currently defines 6 built in valued option types These option types may change the default value for some common properties and or provide additional properties of their
36. his program I would rather have the help op tion display an overview of the program advertise version and a couple of others and I would then implement help as an enumeration for listing every option category individually they would normally be stored in hidden groups The user could then use help settings help operators and so on to display only the category she s interested in Finally here is potentially useful application of hidden options that are never ever displayed in any help string whatsoever and I mean like ever This is the perfect tool for backdoor ing a program For instance if you ever need to implement a discard all security measures and blow the nuke option then you d better have it hidden Chapter 5 Extending Clon 21 5 Extending Clon As you know Clon already provides seven built in option types flags and six other types for valued options see Section 4 1 2 4 Built In Valued Options page 13 After using Clon for a while you may find that however brilliant and perfectly designed it is none of the provided built in types fullfill your requirements exactly There are two ways around this the right way and the wrong way hint The wrong although perhaps quicker way would be to use the stropt option type to simply retrieve unprocessed string values and then do whatever tweaking required on them In doing so you risk reinventing some of Clon s wheels The right way is to define a new option
37. hrough themes Depending on the target audience Clon stands for either The Command Line Options Nuker or The Common Lisp Options Nuker Clon also has a recursive acronym Clon Likes Options Nuking and a reverse one Never Omit to Link with Clon Other possible expansions of the acronym are still being investigated This manual is for the Clon user that is the developer of a Common Lisp application who wants to use Clon for command line option management As opposed to the user of the library the user of an application powered by Clon is called an end user Clon provides both a user manual this one and an end user manual see The Clon End User Manual Everybody should read the end user manual first Chapter 3 Quick Start page 7 provides a very short example in order to give an overview of what s coming next Chapter 4 Using Clon page 11 explains in detail how to clonify your application and Chapter 5 Extending Clon page 21 describe how to extend Clon with your own option types An application using Clon for its command line option management is said to be clonified It is also possible to say clonfiscated However we advise against using clonistified The term clonificated is also considered bad style and the use of clonificationated is strictly prohibited Chapter 2 Installation 5 2 Installation Clon currently works on Unix including MacOS X and Windows Cygwin or MinGW with SBCL gt 1
38. ion version amp optional TYPE number Function Return the current version number of Clon TYPE can be one of number short or long For number the returned value is a fixnum Otherwise it is a string A Clon version is characterized by 4 elements as described below e A major version number stored in the parameter release major level e A minor version number stored in the parameter release minor level A release status stored in the parameter release status The status of a release can be alpha beta rc standing for release candidate or patchlevel These are in effect 4 levels of expected stability e A status specific version number stored in the parameter release status level Status levels start at 1 alpha 1 beta 1 and release candidate 1 except for stable versions in which case patch levels start at 0 e g 2 4 0 In addition to that each version of Clon in the sense major minor regardless of the status has a name stored in the parameter release name The general theme for Clon is Great Jazz Musicians and specifically for the 1 x series Great Saxophone Players Anyone daring to mention Kenny G at that point will be shot on sight Here is how the version function computes its value e A version number is computed as major 10000 minor 100 patchlevel effectively leaving two digits for each level Note that alpha beta and release candidate status are ignored in version
39. isplay of the help string In fact the defsynopsis macro allows you to freely mix declarative forms constructor calls or whatever Lisp code you may want to use The way this works is as follows if a synopsis ITEM see Section 4 1 1 Synopsis Items page 11 is a list whose car is text group or any option type inluding those you define yourselves see Section 5 1 New Option Types page 21 then the ITEM is expanded as explained earlier Otherwise it is just left as is To sum up here s a example of things you can do in defsynopsis net didierverna clon defsynopsis flag 14 my great option setq another option net didierverna clon make switch 4 1 3 2 Advantages So why would you want to use constructors directly or mix declarative and imperative forms in defsynopsis There are several reasons for doing so 1 Some people prefer to declare or should I say create their arbitrary texts options and groups locally in files modules or ASDF components where they belong In such a case you need to keep references to the corresponding objects in order to compute the synopsis in the end 16 The Clon User Manual 2 Since using constructors explicitly allows you to keep references to the created objects these objects can be reused For instance you can use the same text at different places you can also use a single option several times or even a single group several times so that its items ap
40. its of manual installation are needed After unpacking somewhere in the ASDF 3 source registry please perform the following steps in order 1 Edit make config make to your specific needs 2 Type make to compile the documentation and the demo programs end user manual user manual and possibly reference manual By default the documentation is built in info PDF and HTML formats If you want other formats DVI and PostScript are available type make all formats You can also type individually make dvi and or make ps in order to get the corresponding format 3 As documented in make config make the reference manual is only generated if you have SBCL and the Declt library at hand see http www Irde epita fr didier software lisp misc php declt 4 Type make install to install both the documentation and the data files If you have compiled the documentation in DVI and PostScript format those will be installed as well The same goes for the reference manual The demo programs are not installed anywhere Type make uninstall to uninstall the library Chapter 3 Quick Start 7 3 Quick Start In this chapter we assume that you have properly installed Clon see Appendix A Techni cal Notes page 35 and we build a very short program to get you started Let s call it quickstart lisp 3 1 Full Source For cut n paste convenience the complete source code is given below For a slightly longer example have a look at the demonstration
41. k restricted Some non ANSI features of Clon require external functionality that may not be available in all contexts Normally Clon should autodetect this and switch to so called restricted mode at build time see Section A 2 Non ANSI Features page 35 If Clon has failed to autodetect the problem in which case I would like to know or if for some reason you explicitly want to disable those features you may set the restricted configuration option to t Another way to do it without even bothering with configuration is to just use the com svlsoft clon core system instead of the regular one dump This option is only used by the ABCL port Section A 4 Dumping Executables page 36 provides more information on its use A 2 Non ANSI Features One feature of Clon that is beyond the ANSI standard is terminal autodetection it requires an ioctl call and hence a foreign function interface Terminal autodetection is used in several situations for turning on highlighting automatically and for detecting a terminal line width 36 The Clon User Manual If for some reason terminal autodetection is not available Clon will work in so called re stricted mode This means that clon highlight auto won t work highlighting will not be turned on automatically on a tty For the same reason unless otherwise specified via either the COLUMNS environment variable or the clon line width option terminal output will be formatted for 80 colum
42. line that has not been previously retrieved either explicitely or sequentially Chapter 4 Using Clon 19 When there are no more options on the command line this function returns nil Otherwise four values are returned the corresponding option object from the synopsis definition see Section 4 1 3 1 Constructors page 14 the name used on the command line the option s value and the value source cmdline fallback or default As in the case of explicit retrieval see Section 4 4 1 Explicit Retrieval page 18 the option s name may be completed in case of abbreviation Unless you keep references to all your option objects and thus can compare them directly to the one returned by this function you can still identify the retrieved option by using the short name and long name readers on it simply use long name OPTION or short name OPTION and you will get the corresponding strings multiple value getopt cmdline OPTION NAME VALUE SOURCE Macro BODY Evaluate BODY with OPTION NAME VALUE and SOURCE bound to the values returned by the getopt cmdline function above Note that BODY is not evaluated if there was no remaining option on the command line so you don t need to conditionalize on OPTION being null yourself do cmdline options OPTION NAME VALUE SOURCE BODY Macro As above but loop over all command line options 4 5 Help One of the first motivations in the design of Clon was to automate the generation of the he
43. lp string which is a very boring maintenance task to do by hand The application s synopsis contains all the necessary information to do so In order to print your application s help string use the help function help item ITEM Function Print the application s help string Printing honors the search path theme line width and highlight settings provided by the corresponding built in options see Section Theme Mech anism in The Clon End User Manual By default help prints the whole application help string excluding hidden items However if you have kept a reference to any synopsis item option text group you can pass it as the value of the item key and Clon will only print the help string for that particular item In this case however it will be displayed even if was declared as hidden this exception does not extend to its sub items though and they will not be displayed if themselves declared hidden For instance the Clon built in group is normally hidden so it doesn t show up in the global help string but the clon help option uses the help function on it explicitely so it discards its hidden state Here is a potentially useful application of hidden groups in conjunction with the item key Look at ImageMagick s convert program s help string for instance it is 276 lines long Gosh The help string is decomposed into several categories image settings image operators misc options etc If I were to implement t
44. lt 29 A1 Appendix C Indexes make synopsis initargs postfix 15 41 E GEET 14 15 41 make text initargs contents 15 41 make text initargs hidden 15 41 nake xsSwitch eov le rey DEVE 15 41 multiple value getopt cmdline 19 29 42 multiple value getopt cmdline options context Be ee ot sis waa IRIS EPUM 30 42 nickname package 0 cece eee renn 8 41 P Progname foots an sr nee 16 29 42 progname keys econtert 30 42 49 Readers Long name 19 42 Readers short name 00 eee e eee 19 42 TOMA Odia goa er eas 16 29 42 remainder keys context 0 30 42 short Halle sec vias ps eke eevee deme entre 19 42 String if yrs dots less c qu fend dale tae beers 25 43 stringify methods Enumerations enum 25 YerSlOl 511g 080 449b ENSE 31 43 W With CcOntext ciel ern 30 42 50 C 3 Variables ECONO DA sea Ra ven 29 42 zreleasge maior Levelz sss 31 43 zrelease mninor Levelz sss 31 43 zrelease namek 6 eee eee 31 43 release status eee 31 43 zrelease status Levelz 31 43 standard output ooo 31 42 SynODSis rss 29 41 C CLON HIGHLIGHT 19 30 31 CLON_LINE_WIDTH 0 19 30 31 CLON SEARCH PATH oce une 19 30 31 CLON THEME m o ada tds 19 30 31 COLUMNS e yia haley sedis da Bra hes 36 The Clon User Manual E Environment CLON_HIGHLIGHT
45. mmon Lisp standalone executables may depend on e the state of the Lisp environment when the application was dumped which may in turn depend on command line options passed to the Lisp itself see Section A 4 Dumping Exe cutables page 36 e the arguments passed to the dumping function look at Clon s dump macro to see what it does e worse both No really Common Lisp is no fun at all 5 1 5 Value Stringification Protocol Okay back to implementing our new option type The third and last protocol we need to implement is called the value stringification protocol This protocol can be seen as the reverse protocol for argument conversion see Section 5 1 3 Argument Conversion Protocol page 23 its purpose is to transform an option s value into a corresponding argument that the end user could have provided in order to get that value The main use for this protocol is to advertise the fallback and default values correctly in help strings the end user does not want to see those values but rather the argument that would lead to them However you are free to use it wherever you like see the convert method for enum options for instance The value stringification protocol is implemented through a stringify generic function for which you must provide a method Chapter 5 Extending Clon 25 stringify OPTION VALUE Generic Function Transform OPTION s VALUE into an argument I admit that this function could also have been
46. ns regardless of the actual terminal width see Section Global Control in The Clon End User Manual A 3 Supported Platforms Clon is an ASDF 3 library It currently works on Unix including MacOS X and Windows Cygwin or MinGW and has been ported to 8 Common Lisp implementations The following table lists the supported platforms Compiler Minimum Version Dependencies SBCL 1 0 56 CMU CL 20b CCL ECL 11 1 2 CLISP cffi optional ABCL 1 1 0 Allegro cffi optional Lisp Works cffi optional CLISP Allegro and LispWorks specificities As mentioned in the above table CLISP Allegro and LispWorks dependency on cffi is optional They need cffi in order to implement terminal autodetection only note that many other implementations come with their own foreign function interface If cffi cannot be found when the ASDF system is loaded or in the case of CLISP if it has been compiled without ffi support you get a big red blinking light and a warning but that s all Clon will still work although in restricted mode ABCL specificities Clon s ABCL port currently has two limitations e It only works in restricted mode see Section A 2 Non ANSI Features page 35 e Since Java doesn t have a putenv or setenv function the modify environment restart normally proposed when an environment variable is set to a bogus value is unavailable see Section Error Management in The Clon End User Manual A 4 Dumping Executa
47. o subclass lispobj with defoption only to provide friendlier error messages Chapter 6 Advanced Usage 29 6 Advanced Usage This chapter contains information about different features that are present in Clon because of design decisions but that I expect to be used only rarely if at all 6 1 Multiple Clon Instances It is possible to use different instances of Clon in parallel in a single application by using a virtual command line instead of the real one different synopsis and multiple contexts simultaneously 6 1 1 Using Different Synopsis Did you notice that after defining a synopsis there is actually never any explicit reference to it anymore So where is the magick In fact there s no magick at all involved here Clon has a global variable named synopsis which holds the current synopsis When you define create a synopsis with either defsynopsis or make synopsis it is automatically made the default one unless you use the make default option initarg with a value of nil like this defsynopsis make default nil or this make synopsis make default nil When you create a context with make context the default synopsis is used implicitely but you have two ways to avoid this 1 At any time in your program you may change the value of synopsis All subsequent calls to make context will hence use this other synopsis 2 If you prefer to use another synopsis only temporarily you can use the synopsis initar
48. ody BODY do cmdline options OPTION NAME VALUE SOURCE amp key CONTEXT Macro amp body BODY See Section 4 4 2 Sequential Retrieval page 18 and Section 6 1 3 Using Multiple Contexts page 29 short name OPTION Reader long name OPTION Reader See Section 4 4 2 Sequential Retrieval page 18 help amp key CONTEXT context ITEM synopsis context Function OUTPUT STREAM standard output SEARCH PATH search path context THEME theme context LINE WIDTH line width context HIGHLIGHT highlight context See Section 4 5 Help page 19 Section 6 1 3 Using Multiple Contexts page 29 and Section 6 2 Programmatic Help Strings page 31 Appendix B API Quick Reference B 5 Extension API defoption CLASS SUPERCLASSES SLOTS amp rest OPTIONS see Section 5 1 1 New Option Classes page 21 check OPTION VALUE See Section 5 1 2 Value Check Protocol page 22 option error OPTION invalid value VALUE COMMENT See Section 5 1 2 Value Check Protocol page 22 convert OPTION ARGUMENT See Section 5 1 3 Argument Conversion Protocol page 23 invalid argument ARGUMENT COMMENT See Section 5 1 3 Argument Conversion Protocol page 23 stringify OPTION VALUE See Section 5 1 5 Value Stringification Protocol page 24 B 6 Versioning API version amp optional TYPE number See Section 6 3 Version Numbering page 31 release major level release minor level release status release status level
49. one of the built in options is almost what you need you may be tempted to subclass it directly instead of using defoption and only change what s needed After all it s Lisp Lisp is a world of mess D D D Dfreedom Wrong defoption is not only a convenience wrapper around defclass It also arranges for defsynopsis and defgroup to recognize your new option type So please do use it systemati cally 5 2 2 Lisp Option Abuse Along with the same lines you may find that the lispobj type is all you need in many situations Let s take an example Suppose you want to implement a stars option to assign a rank to a movie from 0 to 5 The lazy approach is to simply create a lispobj option with a typespec type specifier of integer 0 5 and you re done Chapter 5 Extending Clon 27 But now remember that the end user of your application is probably not a Lisper in fact I would hope that Clon contributes to increasing the number of standalone Common Lisp ap plications out there What do you think would be her reaction if after providing a bogus value to the stars option she get the following error message Option stars invalid argument 6 Argument 6 must evaluate to integer 0 5 or worse a Cannot parse argument error message because of a typo Not very friendly right In other words you need to think in terms of what the end user of your application will expect In that particular situation you might want t
50. onment oooooooccccccoo 18 Values source fallback 13 18 24 48 C 2 Functions Checa ti 22 43 check methods Enumerations enum 22 Closest mat chins tac Saves in eee 23 Cd bine a uro cus rn 17 38 41 cmdline options p sess 17 29 42 cmdline options p keys context 30 42 cmdline pi qid p vehe DOeg Beer 29 42 cmdline p keys contezt sss 30 42 CMON LING A e REPRE ARIS 17 Configurations silpo treisi i En E oni pie 35 41 configure a T EEE EEEE 35 41 Constructors make context 8 16 17 29 41 Constructors make context initargs cmdline 29 41 Constructors make context initargs make current a ke iM MM e Eee eg 29 41 Constructors make context initargs synopsis N EE eu 29 41 Constructors make enum 15 25 41 Constructors make flag 14 15 41 Constructors make group 14 15 41 Constructors make group initargs header 15 41 Constructors make group initargs hidden 15 41 Constructors make group initargs item 15 41 Constructors make lispobj 15 41 Constructors make OPTION 15 41 Constructors make parb 15 41 Constructors make stropt esses 15 41 Constructors make switch 15 41 Constructors make synopsis 14 15 41 Constructors make synopsis initargs item 15 41
51. ory fallback and default values see Section 4 1 2 3 Common Valued Option Properties page 13 In order to create a new option type use the defoption macro defoption CLASS SUPERCLASSES SLOTS amp rest OPTIONS Macro Create a new option CLASS and register it with Clon Syntactically thismacro behaves like defclass Option types created like this implicitely inherit from valued option and in turn option so you don t need to put them explicitely in the SUPERCLASSES list Let s look at the enumeration example now 7 defoption enum enum base argument name inherited from the VALUED OPTION class initform TYPE documentation The ENUM class This class implements options whose values belong to a set of keywords 22 The Clon User Manual As you can see this class inherits from enum base which is the class handling the enum prop erty The reason for this split is that there are currently two option types providing enumeration like facility enum and xswitch so xswitch also inherits from enum base There are no new slots in this class but the argument name slot provided by the valued option class has its initform changed from ARG to TYPE 5 1 2 Value Check Protocol Now that we have our new option class we need to implement the so called value check protocol This protocol is used to make sure that values provided for options of your new type actually comply with the type in question Values going
52. own All of this is described below stropt This option type is for options taking strings as their argument String options don t provide any additional properties but their default argument name is changed from ARG to STR lispobj This option type is for options taking any kind of Lisp object as their argument lispobj options change their default argument name from ARG to OBJ Also they provide an additional property called typespec which must be a Common Lisp type specifier that the argument must satisfy It defaults to t Look at the clon line width built in option for an example enum This option type is for options taking values from an enumerated set of keywords enum options change their default argument name from ARG to TYPE Also they provide an additional property called enum to store the list of Common Lisp keywords enumerating the possible values The end user does not use a colon when providing an argument to an enum option Only the keyword s name The end user also has the ability to abbreviate the possible values An empty argument is considered as an abbreviation for the first element in the set Look at the clon version built in option for an example path This option type is for options taking a colon separated list of pathnames as ar gument path options change their default argument name from ARG to PATH Also they provide an additional property called type which specifies the kind of path whi
53. pear in different places etc Note that Clon knows its way around multiple occurrences of the same object even if you use the same option object several times in a synopsis Clon only maintains a single option definition 4 1 3 3 Group Definition There is one last point we need to address in order to complete this section There might be times when you need to manipulate an explicit group object but the object itself can still be created in a declarative or mixed way because you don t need to keep references on its items For this Clon provides a macro called defgroup defgroup OPTIONS ITEMS Macro Define a new group and return it This macro behaves exactly like the group form in a call to defsynopsis see Section 4 1 1 3 Groups page 12 In fact an intermediate step in the expansion of the defsynopsis macro is to transform group forms into defgroup macro calls As for defsynopsis defgroup allows you to mix declarative forms constructor calls or any kind of Lisp code 4 2 Context Creation Step two of the Clon initialization phase consists in creating a context A context is an object representing a particular instance of your program for example and most notably with an actual command line as the user typed it 4 2 1 Making A Context You create a context with the make context function make context Function Create a new context That s it 4 2 2 Contextual Information Once a context object is created yo
54. ption Properties env var 12 18 Common Option Properties hidden 12 Common Option Properties long name 12 19 Common Option Properties short name 12 19 Common Valued Option Properties 13 Common Valued Option Properties argument name LEW tect senserit 13 14 22 Common Valued Option Properties argument type BESTEHEN A HELEN eg 13 14 Common Valued Option Properties default value a ca aca 13 18 24 Common Valued Option Properties fallback value o o o oooooooo o 13 18 24 Configuration at 35 Configuration Option dump 35 37 Configuration Option restricted 35 Configuration Option swank eval in emacs 35 45 Constructors for options objects 25 Contextos rad E deas 8 16 Context Current zeci nee sen 29 D Debugger ta AD 24 Debugger restarts vice russ see 24 DUMping ar sein sn 9 24 36 E Enumerations enum 13 21 22 23 25 Enumerations enum properties enum 13 21 22 23 Extended Switches xswitch 14 21 Extended Switches xswitch properties sargument style iani PAE eee 14 Extended Switches xswitch properties enum PEE ad he 14 21 F Files one per option type 0 eee eee eee 21 Flags flag A bey iene ess tees 13 18 21 Group Header 12 VE EE 12 Groups built in mo 12 19 Groups bidden 12 19 Gro ps in groups ic
55. ptions common properties env var 12 18 Options common properties hidden 12 Options common properties long name 12 19 Options common properties short name 12 19 Options creation cece eee eee eens 15 Options Flags lag 13 18 21 Options hidden corta lille ma 12 Options in group 12 Options in synopsis eee eee eee eee 8 12 Options valued 0 eee eee eee eee 13 21 Options valued common properties 13 Options valued common properties argument name Ale BA A 13 14 22 Options valued common properties argument type Sos holden a sao 13 14 Options valued common properties default value A HORE NE 13 18 24 Options valued common properties fallback value esses 13 18 24 Options valued Enumerations enum 13 21 22 23 25 Options valued Enumerations enum properties Lenumcidcirieheresfewerksles indui 13 21 22 23 Options valued Extended Switches xswitch 14 21 Options valued Extended Switches xswitch properties argument style 14 Options valued Extended Switches xswitch properties enum sseeeeeeeeeees 14 21 Options valued Lisp Objects lispobj 13 26 Options valued Lisp Objects lispobj properties O inne ea e e bri reve 13 26 Options valued Paths path 13 Options valued Paths path properties type 1
56. ram all you need to do now is to type CC gcc sbcl script quickstart lisp Note that the actual way of dumping executables is compiler dependent For more information on the proper way to do it and on the compilers currently supported see Section A 4 Dumping Executables page 36 Note also that it is possible to use Clon without actually dumping a standalone executable see Section A 5 Not Dumping Executables page 38 Chapter 4 Using Clon 11 4 Using Clon Using Clon in your application is a two stages process In phase 1 you create a synopsis which is a description of your application s command line and a context which describes this specific execution of the program In phase 2 you retrieve the option values and possibly display help strings Phase 1 is called the initialization phase while phase 2 is called the runtime phase 4 1 Synopsis Definition Step one of the Clon initialization phase consists in defining a synopsis A synopsis is essentially a description of your application s command line it describes what are the available options whether your application has a postfix etc The synopsis however plays a second role it also describes the contents of your application s help string When you create a synopsis you describe the command line and the help string at the same time 4 1 1 Synopsis Items Look again at the synopsis definition provided in Chapter 3 Quick Start page 7 a defsynopsis pos
57. s what it s a mess When you dump an executable the Clon way the cmdline function will always contain user options only the dump macro instructs the compilers to not process the command line at all When you use Clon interactively and mix compiler specific options with application ones when invoking your Lisp environment the situation is as follows SBCL SBCL processes its own options and leaves the others unprocessed on the command line This means that as long as there is no overlap between SBCL s options and yours you can just put them all together on the command line In case of overlap however you need to separate SBCL s options from yours with a call to end toplevel options that s an SBCL specific option separator CMUCL CMUCL processes its own options issues a warning about the options it doesn t know about but in any case it eats the whole command line Consequently if you want to provide options to your application you need to put them after a separator Note that you can still use a second such separator to provide Clon with both some options and a remainder see Section Option Separator in The Clon End User Manual CCL ECL CLISP CCL ECL and CLISP all process their own options but will abort on unknown ones Consequently if you want to provide options to your application you need to put them after a separator Note that you can still use a second such separator to provide Clon with both some options and
58. short name h long name help description Print this help and exit item make flag short name v long name version description Print version number and exit As you can see every synopsis element has a corresponding make SOMETHING constructor and the keywords used here and there in defsynopsis are in fact initargs to those constructors We now examine those constructors in greater detail make text hidden BOOL contents STRING Function Create an arbitrary text object possibly hidden whose contents is STRING make OPTION INITARG INITVAL Function Create a new OPTION object OPTION being any built in option type flag stropt etc see Section 4 1 2 4 Built In Valued Options page 13 or user defined one see Section 5 1 New Option Types page 21 For a list of available initialization arguments depending on the option type see Section 4 1 2 Built In Option Types page 12 make group header STRING bidden BOOL item ITEMI item Function ITEM2 Create a group object possibly hidden whose header is STRING Every ITEM is an arbi trary text object option object or group object The order is important as it determines the display of the help string make synopsis postfix STRING item ITEMI item ITEM2 Function Create a synopsis object whose postfix is STRING Every ITEM is an arbitrary text object option object or group object The order is important as it determines the d
59. string Hidden groups can still be displayed individually though see Section 4 5 Help page 19 For instance the Clon built in group is hidden in the regular help string but the clon help option still displays 1t individually 4 1 2 Built In Option Types In this section we will review all the built in option types that Clon provides along with their corresponding properties You can use them directly in your synopsis description For adding personal option types to Clon see Section 5 1 New Option Types page 21 4 1 2 1 Common Properties All option types in Clon including those you define yourself see Section 5 1 New Option Types page 21 have a set of basic common properties Here is a list of them short name The option s short name A string or nil long name The option s long name A string or nil description The option s descriptive text A string or nil The same formatting recommenda tions as for arbitrary text apply see Section 4 1 1 1 Text page 11 env var The option s associated environment variable A string or nil hidden When non nil the option won t appear in the help string Hidden options can still be displayed individually though see Section 4 5 Help page 19 Note that an option is required to have at least one name either short or long Non nil but empty names are also prohibited and of course a short name cannot begin with a dash otherwise it would be mistaken for a lon
60. string enum enum key lambda value stringify enum value Since enumerations allow their arguments to be abbreviated a utility function named closest match is used to find the closest match between an argument and the possible val ues Otherwise an invalid argument error is raised For an explanation of stringify See Section 5 1 5 Value Stringification Protocol page 24 5 1 4 Error Management Let s take a short break in our Clon extension process We have seen that Clon may throw errors in different situations including invalid arguments or values The end user manual advertises that the interactive error handler offers a set of options to fix problems if you don t know what I m talking about please read Section Error Management in The Clon End User Manual and you will know Well you may have guessed that these options are simply restarts of course we don t use that term there as we wouldn t want to frighten the casual user or would we When you ship your application you are encouraged to disable the debugger in the stand alone executable because that also might scare the casual user a little bit the end user manual only mentions the none error handler to explain that people shouldn t use it The way error handling is done in Common Lisp standalone executables is implementation dependent so please refer to your favorite compiler s documentation More generally the behavior of Co
61. tance es fallback NAME The same but when the fallback value is used that is when an option is not provided with its optional argument N default NAME The same but when the default value is used because there is no fallback environment VAR This is for options not found on the command line but for which there is an asso ciated environment variable set in the application s environment VAR is the name of the corresponding environment variable default This is for options not found anywhere but for which a default value was provided Note that because flags don t take any argument getopt returns a virtual value of t when they are found or a corresponding environment variable exists in the environment For the same reason a flag s value source may ony be cmdline NAME or environment VAR When an option is not found anywhere and there is no default value getopt just returns nil no second value Also note that when your option accepts nil as a value you need to handle the second retrun value to make the difference between an option not found and an actual value of nil 4 4 2 Sequential Retrieval The more traditional approach to option retrieval is to scan the command line for options in their order of appearance Clon supports this by providing you with one function and two macros as explained below getopt cmdline Function Get the next command line option that is the first option on the command
62. tfix FILES text contents A very short program group header Immediate exit options flag short name h long name help description Print this help and exit flag short name v long name version description Print version number and exit You define a synopsis with the defsynopsis macro defsynopsis OPTIONS ITEMS Macro Define a new synopsis and return it OPTIONS are key value pairs ITEMS are text group or option descriptions The following OPTIONS are currently available postfix A string which will appear at the end of the synopsis line in the help string When you provide a postfix you also implicitely tell Clon that your application accepts non option arguments at the end of the command line this is called the remainder of the command line See Section Option Separator in The Clon End User Manual for more information on the behavior of Clon with respect to postfixes Also see Section 4 2 2 2 Command Line Remainder page 16 on how to access the command line remainder We now examine the syntax for each possible ITEM 4 1 1 1 Text In order to add arbitrary text to your help string use the following form text OPTIONS OPTIONS are key value pairs The following OPTIONS are currently available contents The actual text string Try to make proper sentences when adding arbitrary text You can use explicit newline characters in your text if you really want
63. the command line Let s first see if the user has called the option h and give him the help string Option retrieval is done with the function getopt and automatic help string output with the function help Note that what we do here is not process the command line in sequence but look directly for a specific option by name this retrieval method is said to be explicit when getopt short name h help exit The exit function is a wrapper around an implementation dependent way to exit shall I say quit the Common Lisp environment hence the program It takes an optional argument that stands for the exit status And now we are going to retrieve the other options and simply print them This time how ever we process the command line sequentially so this retrieval method is said to be sequential This is done with the do cmdline options macro We also close the main function Chapter 3 Quick Start 9 do cmdline options option name value source print list option name value source terpri exit Finally time to save the Lisp image caup quickstart main The first argument to dump is the name of the executable to produce and the second argument is the name of the function to call automatically at startup In fact dump also accepts a amp rest argument that just be passed on to the underlying implementation specific dumping facility In order to get a standalone executable from this prog
64. the refcard theme etc In such situations calling the help function might not be directly associated with an end user level option or at least not help and you might not want to honor the end user level settings for theme search path line width or highlighting either remember that these settings might come from the environment variables associated with clon theme clon search path clon line width and clon highlight Because of this the help function provides additional keys that allow you to override those settings they are in fact stored in the context object The keys in question are theme search path line width and highlight In addition to that there is an output stream key which defaults to standard output which you could use for instance to write directly to a file Note that there is no end user level access to this parameter 6 3 Version Numbering As Clon evolves over time you might one day feel the need for conditionalizing your code on the version of the library While the end user of your application has limited means to access the current version number of Clon see Section Clonification in The Clon End User Manual and the built in option clon version you the application programmer and Clon user have a finer grained access to it The first thing you can do to access the current version number of Clon is use the version function this is in fact the function bound to the clon version opt
65. this property does not affect the argument name It only affects the way true or false values are displayed in help strings Look at the clon highlight built in option for an example 4 1 3 Advanced Synopsis Creation The fact that defsynopsis lets you define things in a declarative way has not escaped you Declarative is nice but sometimes it gets in the way so it is time to see how things work under the hood Every item in a synopsis is in fact implemented as an object an instance of some class so it turns out that defsynopsis simply is a convenience wrapper around the corresponding constructor functions for all such objects Instead of using defsynopsis you can then use those constructor functions explicitely 4 1 3 1 Constructors Let s have a look at the expansion of defsynopsis from the quick start example see Chapter 3 Quick Start page 7 The original code is like this a defsynopsis postfix FILES text contents A very short program group header Immediate exit options flag short name h long name help description Print this help and exit flag short name v long name version description Print version number and exit And once the macro is expanded it will look like this Chapter 4 Using Clon 15 S make synopsis postfix FILES item make text contents A very short program item make group header Immediate exit options item make flag
66. through this protocol are fallback values default values and values provided from a debugger restart see Section Error Management in The Clon End User Manual In the case of fallback and default values which by the way are provided by you the Clon user the check is performed only once when the option object is created Values provided from a debugger restart come from the application end user and hence are checked every time The value check protocol is implemented through a check generic function for which you must provide a method check OPTION VALUE Generic Function Check that VALUE is valid for OPTION If VALUE is valid return it Otherwise raise an invalid value error As you can see you need to provide a method with the first argument specialized to your new option type This method must return VALUE if it is okay and raise an invalid value error otherwise Clon maintains a hierarchy of error conditions The invalid value error condition is defined like this define condition invalid value option error value documentation The invalid value initarg value reader value comment documentation An additional comment about the error type string initarg comment reader comment report lambda error stream format stream Option A invalid value S 0 4 A option error value error comment error documentation An invalid value error When the error is rais
67. to go next line but in general you should not worry about the formatting because the themes are here to do so In particular don t finish your text with a newline This would break potential theme specifications 12 The Clon User Manual hidden When non nil the text won t appear in the help string Hidden texts can still be displayed individually though see Section 4 5 Help page 19 4 1 1 2 Options In order to add an option to your help string you must provide a list beginning with the option type and followed by key value pairs describing the option s properties For instance to add a flag with a short name and a description you could do this flag short name h description Print this help and exit Option properties vary depending on the option type The exact list of available option types and the corresponding properties are described in Section 4 1 2 Built In Option Types page 12 4 1 1 3 Groups In order to add a group to your help string use the following form group OPTIONS ITEMS OPTIONS are key value pairs ITEMS simply are arbitrary text option or sub group de scriptions as we ve just seen The following OPTIONS are currently available header A string which will be displayed above the group s contents in the help string The same formatting recommendations as for arbitrary text apply see Section 4 1 1 1 Text page 11 hidden When non nil the group won t appear in the help
68. tude Alessio Stalla Antony something Erik Huelsmann Erik Winkels Frangois Ren Rideau Jan Moringen James Wright Martin Simmons Nikodemus Siivola Sam Steingold
69. u have access to some interesting contextual information 4 2 2 1 Program Name The application s program name as it appears on the command line may be accessed from Clon You may find it easier to do this way as Clon wraps around implementation dependent access methods to argv 0 In order to retrieve argv 0 use the progname function like this progname 4 2 2 2 Command Line Remainder In the case your command line has a remainder that is a non options part see Section Option Separator in The Clon End User Manual and Section 4 1 1 Synopsis Items page 11 you may need to access it in order to process it independently from Clon Since Clon is responsible for parsing the command line it is also in charge of figuring out where the remainder of the command line begins The command line remainder is known to Clon as soon as a context is created You can retrieve it by using the remainder function like this remainder The remainder is provided as a list of strings Chapter 4 Using Clon 17 4 2 2 3 Command Line Polling Clon provides two utility functions to inquire on the current status of the command line The function cmdline options p returns true if there are still unprocessed options on the command line The function cmdline p returns true if there s anything left on the command line that is either unprocessed options or a remainder A potential use of cmdline p at a very early stage of your application could b
70. uld obvi ously avoid defining options by those names ABCL is a totally different beast because it s a Java based Common Lisp imple mentation Most notably you don t create standalone executables in Java so the normal way of running ABCL is by telling it to load some lisp code If you want to run the quickstart program in the usual way you will typically type this abcl noinform noinit nosystem load quickstart lisp Note that for this to work the dump macro expands to the main function call for ABCL just as for ECL There s more to it than that though It is possible to get closer to standalone executables with ABCL by 1 providing your whole application in a jar file directly and 2 overriding ABCL s entry point by providing your own interpreter which runs your main function automatically I have described this process in more details in the following blog entry http www didierverna com sciblog index php post 2011 01 22 Towards ABCL Standalone Executables Clon helps you to do this to some extend If the dump configuration option is set see Section A 1 Configuration page 35 then the dump macro doesn t expand to a call to the main function but instead dumps a Java file containing an alternate ABCL interpreter that you can compile and add to the original ABCL jar file along with quickstart lisp If you want more details on this you will need to look at the Makefile in the demo directory and also at the
71. w how to use it nickname package amp optional NICKNAME Function Add NICKNAME CLON by default to the NET DIDIERVERNA CLON package The next thing you want to do is to create a set of options groups or texts that your application will recognize and or display in its help string The structure of your command line is known to Clon as the synopsis In order to create it use the macro defsynopsis S defsynopsis postfix FILES text contents A very short program group header Immediate exit options flag short name h long name help description Print this help and exit flag short name v long name version description Print version number and exit gt Note that the synopsis has a double role it not only serves to define the options recognized by your application but also the order in which every element appears in the help string In that particular example we define a line of text and a group with a header and two flags Now we are going to define a function main for our standalone application The first thing that we need to do is create a context A context is an object that Clon uses to store various things including some state related to the parsing of the command line You create a context with the function make context defun main Entry point for our standalone application make context At that point Clon is ready to retrieve the options you want from
72. x release name See Section 6 3 Version Numbering page 31 43 Macro Generic Function Error Condition Error Condition Generic Function Error Condition Generic Function Function Parameter Parameter Parameter Parameter Parameter Appendix C Indexes Appendix C Indexes C 1 Concepts zcclonzhelp cs eh anna ta nee 12 19 clon highlight 14 19 30 31 36 clon line width 13 19 30 31 36 clon search path 13 19 30 31 o en O 13 19 30 31 CLORO e 13 31 SAUMP RENEE E E ne ee tees 39 37 ireStricted un en nn ren 35 swank eval in emacs 00 cee eee 35 A Argument Conversion Protocol 23 B Built In Groups tans anna 12 19 Built In Option Types 0 ec eee eee eee 12 Built In Option Types valued 13 Built In Options clon help 12 19 Built In Options clon highlight 14 19 30 31 36 Built In Options clon line width 13 19 30 31 36 Built In Options clon search path 13 19 30 31 Built In Options clon theme 13 19 30 31 Built In Options clon version 13 31 C Commande 17 41 Command Line polling 0 ee eee 17 Command Line remainder 11 16 30 38 Common Option Properties ooooooooccocoo 12 Common Option Properties description 12 Common O

Download Pdf Manuals

Related Search

Related Contents

  INSTRUCTION MANUAL  DigiTech HardWire RV-7  FEUILLE D`INSTRUCTION N° 04  Dell HV02T MP3 Player User Manual  Canon 2159B002 Printer User Manual  SM-100 Französisch.book  取り扱い説明書はこちら  Sony DCR-SR90E Personal Computer User Manual  Brodit ProClip  

Copyright © All rights reserved. Failed to retrieve file