NAME
Meta::Utils::Opts::Opts - Module to help you analyze command line arguments.
COPYRIGHT
Copyright (C) 2001 Mark Veltzer; All rights reserved.
LICENSE
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111, USA.
DETAILS
MANIFEST: Opts.pm PROJECT: meta
SYNOPSIS
package foo; use Meta::Utils::Opts::Opts qw(); my($obj)=Meta::Utils::Opts::Opts-new();> $obj-set_standard();> $obj-set_free_allo(0);> $obj-anal(\@ARGV);>
DESCRIPTION
This is a library to handle command line arguments for shell scripts. It surrounds the Getopt::Long library and gives a nicer interface. The way to use the library is this: first you have to prepare a list of variables (of different types of course) which will control the behaviour of your software. These values will be overriden by the user if neccessary (or by rc files of the user if neccessary...). 0. call init to initialize the library. 1. call desc to describe what your program does. 2. call auth to describe the author which wrote your program. 3. call (or not call) standard to use standard settings. 4. call a lot of def_{type} routine to define all the arguments to your software (these will include default values). 5. call free/free_mini/free_maxi if you want to allow free arguments to your program or set_free_allo(0) to disallow free arguments to your program. 6. call anal. If this routine succeds it means that all options given on the command line were valid and all files and directory options were indeed valid files and directories. 7. the values of the different arguements are in the variables you specified as linkage. 8. If you allowed free arguments they are the only thing left in ARGV after the anal call was made and you can access them from there. 9. If any error was made in the argument passing by the user then the anal routine will abort with appropriate error and correct usage messages.
* You can call the usage routine of this module whenever you like to print out a usage message.
Currently supported types for parameters are: bool bool integer inte string stri float floa directory dire file file
EXPORTS
new($) inse($$$$$$$) def_bool($$$$$) def_inte($$$$$) def_stri($$$$$) def_floa($$$$$) def_dire($$$$$) def_file($$$$$) def_newf($$$$$) def_enum($$$$$$) get_free_allo($) set_free_allo($$) get_free_stri($) set_free_stri($$) get_free_mini($) set_free_mini($$) get_free_maxi($) set_free_maxi($$) get_free_noli($) set_free_noli($$) get_colo($) set_colo($$) use_colo($$$) use_colo_rese($$) set_standard($) anal($) usag($$) man($$) get_valu($$) get_desc($) set_desc($$) get_auth($) set_auth($$) get_lice($) set_lice($$) get_gui($)
FUNCTION DOCUMENTATION
- new($)
-
This will give you a new Meta::Utils::Opts::Opts object.
- inse($$$$$$$)
-
Inserts an option string, with a type and a default value.
- def_bool($$$$$)
-
Add a boolean argument to the options.
- def_inte($$$$$)
-
Add an integer argument.
- def_stri($$$$$)
-
Add a string argument.
- def_floa($$$$$)
-
Add a float argument.
- def_dire($$$$$)
-
Add a directory argument (checks that the directory is valid).
- def_file($$$$$)
-
Add a file aegument (checks that the file is valid).
- def_newf($$$$$)
-
Add a new file aegument (checks that the file is non-existant).
- def_enum($$$$$$)
-
Add an enumerated argument (checks that the value is out of a set of values).
- get_colo($)
-
This method will return whether color printing will be used by this object.
- set_colo($$)
-
This method will set whether this object will use color printing or not.
- use_colo($$$)
-
This method will print color sequences to the file given if color is used.
- use_colo_rese($$)
-
This method will reset color usage on the specified file.
- get_free_allo($)
-
This will tell you if free arguments on the command line are allowed.
- set_free_allo($$)
-
This routine declares that free arguments are allowed on the command line and the parameter given is the title string for usage printing etc...
- get_free_stri($)
-
This will tell you how free arguments are going to be described on the command line usage.
- set_free_stri($$)
-
This will set the string which will be used to describe free arguments on the command line usage.
- get_free_mini($)
-
This method will return the minimal number of free arguments which are allowed on the command line.
- set_free_mini($$)
-
This routine sets the minimum number of free arguments that a program is supposed to accept. (the default value of this is 0).
- get_free_maxi($)
-
This method will return the maximal number of free arguments which are allowed on the command line.
- set_free_maxi($$)
-
This routine sets the maximum number of free arguments that a program is supposed to accept.
- get_free_noli($)
-
This method will return whether there is a maximal limit on the number of free arguments allowed on the command line.
- set_free_noli($$)
-
This routine sets no limit on the nubmer of free arguments that a program is supposed to accept.
- anal($)
-
This analyzes the arguments, stores the results and is ready to answer questions about what is going down.
- usag($)
-
This routine prints the programs usage statement to standard error with the program name and all the parameters along with their types and default values. The file on which to print the usage is a parameter.
- man($$)
-
Show the manual page for this program. The file on which the manual is shown is a paramter.
- get_valu($$)
-
This method will retrieve the current value of some option.
- set_standard($)
-
This does the standard initialization for base command line options. Regularly, this is the first routine you should call if you want to do command line parsing the base way. Currently this sets up the help variable correctly.
- get_desc($)
-
This method will return the description of the current software.
- set_desc($$)
-
This routine defines for the Opts module a one line description of what your software does. This will be stored in the module and used later (for instance when printing the software's usage or help...).
- get_auth($)
-
This method will return the author of the current software.
- set_auth($$)
-
This routine defines for the Opts module the name of the author of the file. This will be stored in the module and used later (for instance when printing the software's usage or help...).
- get_lice($)
-
This method will return the license of the current software.
- set_lice($$)
-
This routine defines for the Opts module the license of the software. This will be stored in the module and used later (for instance when printing the software's usage or help...).
- get_gui($)
-
This method will show a gui for the options.
BUGS
None.
AUTHOR
Mark Veltzer <mark2776@yahoo.com>
HISTORY
start of revision info 1 Sun Jan 7 18:17:29 2001 MV make Meta::Utils::Opts object oriented 2 Sun Jan 7 20:46:54 2001 MV more harsh checks on perl code 3 Tue Jan 9 19:29:31 2001 MV fix todo items look in pod documentation 4 Tue Jan 9 22:40:39 2001 MV add enumerated types to options 5 Wed Jan 10 12:05:55 2001 MV more on tests/more checks to perl 6 Fri Jan 12 15:53:19 2001 MV change new methods to have prototypes 7 Sat Jan 13 08:28:57 2001 MV UI for Opts.pm 8 Sun Jan 14 05:25:04 2001 MV fix up perl cooking a lot 9 Thu Jan 18 15:59:13 2001 MV correct die usage 10 Thu Jan 18 19:33:43 2001 MV fix expect.pl test 11 Fri Jan 19 12:38:57 2001 MV more organization 12 Sun Jan 28 02:34:56 2001 MV perl code quality 13 Sun Jan 28 13:51:26 2001 MV more perl quality 14 Tue Jan 30 03:03:17 2001 MV more perl quality 15 Sat Feb 3 03:39:36 2001 MV make all papers papers 16 Sat Feb 3 23:41:08 2001 MV perl documentation 17 Mon Feb 5 03:21:02 2001 MV more perl quality 18 Tue Feb 6 01:04:52 2001 MV perl qulity code 19 Tue Feb 6 07:02:13 2001 MV more perl code quality 20 Tue Feb 6 08:47:46 2001 MV more perl quality 21 Tue Feb 6 22:19:51 2001 MV revision change 22 Thu Feb 8 00:23:21 2001 MV betern general cook schemes end of revision info
SEE ALSO
Nothing.
TODO
-add nicer type description for each option type.
-Add some more features: 0. must parameters - paramters which must be there. 1. integer parameters which are limited in range. 3. a parameter which is a regular expression (and test the regular expression) 4. parameters which are allowed a selection out of a set.
-The help is not handled well if there is a limit on the minimal number of free arguments (if the user just asks --help that check fails and the usage is printed with an error but actually this is not an error...)
-do it so if I have a fixed sized list of free args I could also attach them to variables (this way I dont have to have lines like one,two,three=ARGV0,ARGV1,ARGV2 in my scripts....(maybe even a more general approach of fixed sized coming first and then var sized ?)
-in the usage print that option passing is in the GNU stype. Maybe even offer an option to show help on passing GNU args... add a document and help on how to set user defined defaults (if you implement that mechanism).
-add an option for a parameter type for a file to be written which is not yet on the disk (or is on the disk, or doesnt care...). The options module will check that the file can be created if need be.
-fix the man command which does not use the file argument given to it.