---------------------------------------------------------------------- OP - A Command Line Parser for Eiffel Version: 0.9.1 Date: Mar 23th, 2006 ---------------------------------------------------------------------- INTRODUCTION -------------------- OP is a reusable library for Eiffel that handles the parsing of arguments from a command line. It makes it easy for the user to setup and add command line options, without the need to bother with complicated parsing routines or corner cases. Its main features are: * Different types of options: flags, strings, integers, booleans ... * Long (--make-love) and short (-l) options are supported. * Short form can be joined (-abc instead of -a -b -c), assuming that every one but the last is a flag (does not require an argument). * Arguments to the short form can be added with or without space (-ltoday or -l today). * Arguments to the long form can be added with '=' or with a space (--make-love=today or --make-love today) * Option termination introduced by '--'. * Usage instructions and a help text will be generated automatically from the options. * An agent can be called every time a certain option is found. * Good default values, minimal code is required for standard applications. * No special 'option description language' is required. It is all just plain Eiffel code. The main goal of the library was to create a good and simple default implementation of command line parsing. The library might not suite your needs if you want to create very complicated command line schemas. For this, you might have a look at other command line parsing libraries presented at http://www.eiffelzone.com/esd/lib-cl.html. DOWNLOAD -------------------- The offical homepage of this package is located at http://se.inf.ethz.ch/people/schoeller/op.html REQUIREMENTS -------------------- - GOBO >= 3.4 (available at www.gobosoft.com) - Eiffel compiler supported by GOBO with support of agents Remark: The library was developed with EiffelStudio 5.6, but I have tried only to use classes from the GOBO library. This means that it should work on any Eiffel compiler that is supported by GOBO. Still, I would like to hear from you if you have problems getting the library to work in other environments. HOW TO USE -------------------- Extract the files into a directory and let the environment variable OP_HOME point to it. Include the library.xace into you system.xace file with the mount instruction: To parse the command line, create an instance of OP_PARSER and call 'parse_arguments'. Parsing any other list of strings as arguments can be done using 'parse_list'. For every option, you have to create an option object and add it to the parser. There are multiple option classes, depending on if you want to pass parameters to the options or not. GLOSSARY -------------------- The following glossary might help understanding the library interface: arguments: the unparsed array of strings passed to the program options: optional flags with and without arguments, introduced by '-' short option: an option that is defined by a minus and a single letter (-f) long option: an option that is defined by two minuses and a keyword (--foo) option parameter: a string or other value that is passed to an option (--my-name=Bernd or (-f10) flag: an option that does not require a parameter parameters: all arguments that are not part of an option or option parameter (for example file names) EXAMPLE -------------------- class OP_EXAMPLE create main feature -- Main main is -- Main routine local parser: OP_PARSER flag: OP_FLAG option: OP_INTEGER_OPTION do -- First we create the parser create parser.make -- We add a flag create flag.make ('f',"flag") flag.set_description ("A simple flag") parser.extend (flag) -- We add an integer option create option.make ('o',"option") option.set_description ("An integer option. You have to supply an"+ " integer value to this option to be parsed correctly.") parser.extend (option) -- We parse the arguments parser.parse_arguments -- Lets see what we found if flag.was_found then print ("The user has activated the flag.%N") end if option.was_found then print ("The user has supplied the option with "+option.value.out+"%N") end print ("The number of parameters were "+parser.parameters.count.out+"%N") end end FAQ -------------------- 1.) How can I parse a certain option multiple times ? Attach a handler agent to that option. The handler will be called every time the option is encountered. If you just want to find out if an option was specified multiple times (for example for multiple verbosity levels like -vvv), the 'occurrences' flag can help you. 2.) How can I access the parameter to an option in the handler ? The parameter will be set to the option before the handler is called. You can read it from the option object directly in the handler. If you want an easy way to access the correct option object in the handler, pass the option object as an argument on agent creation: my_option.set_handler (agent my_handler (my_option)) 3.) I want to define my own help page, but the default one is in the way. What should I do ? The default help page is using a handler to print the help text. You can override this handler by calling 'parser.help_option.set_handler (an_agent)' directly. If you want to remove the help page completely, you can remove it with 'parser.remove (parser.help_option)'. COPYING -------------------- (c) 2006 by Bernd Schoeller All source code and binary programs included in OP are distributed under the terms and conditions of the Eiffel Forum License: Eiffel Forum License, version 2 1. Permission is hereby granted to use, copy, modify and/or distribute this package, provided that: * copyright notices are retained unchanged, * any distribution of this package, whether modified or not, includes this license text. 2. Permission is hereby also granted to distribute binary programs which depend on this package. If the binary program depends on a modified version of this package, you are encouraged to publicly release the modified version of this package. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT WARRANTY. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS BE LIABLE TO ANY PARTY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THIS PACKAGE. This license is an OSI Approved License: http://opensource.org/licenses/ver2_eiffel.php and a GPL-Compatible, Free Software License: http://www.gnu.org/licenses/eiffel-forum-license-2.html