Usage 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/LICENSE ADDED
@@ -0,0 +1 @@
1
+ This is released under the same terms as the Ruby license.
data/README ADDED
@@ -0,0 +1,137 @@
1
+ OVERVIEW
2
+
3
+ The usage library is a library that is allows command line scripts to be written with
4
+ a minimum of memorization necessary to access the arguments. I wrote it because I was
5
+ tired of copying code from other command line programs that used GetOptLong. This was
6
+ started before there was a profusion of different command line libraries. Even with this
7
+ profusion, there is still some memorization that goes along with how to set up the
8
+ framework process the arguments.
9
+
10
+ LIMITATIONS
11
+
12
+ This library really intended for simplish command line programs. It is not really
13
+ capable of handling complex command line requirements like commands with sub-commands
14
+ and the like (like CVS or SVN). It is really intended for that quick command that you
15
+ are whipping up to do a simple task. It can grow with you for a while but at some
16
+ point it may not be up to the task.
17
+
18
+ USAGE ON USAGE
19
+
20
+ A note on terminology. When I mention "arguments" it means command line arguments that
21
+ are not prefixed by a "-" option. When I mention options, I mean those things following
22
+ the "-". Options themselves can have arguments as well. So we have:
23
+
24
+ program arguments - those non option arguments
25
+ options - those dash things
26
+ option arguments - those things that are after but associated with options
27
+
28
+ 1. Simple Usage
29
+
30
+ The only thing you have remember to use usage are how commands are usually documented.
31
+ First you need to require the usage library:
32
+
33
+ require "Usage"
34
+
35
+ Then set up the usage string for the command:
36
+
37
+ usage = Usage.new "infile outfile"
38
+
39
+ The above would be a command with two require arguments: an input file and an output file.
40
+ To access those arguments, you just need to use the usage variable that was created and
41
+ send the .infile or .outfile message to them.
42
+
43
+ File.open(usage.infile) do |fi|
44
+ File.open(usage.outfile, "w") do |fo|
45
+ fo.write(fi.read)
46
+ end
47
+ end
48
+
49
+ If the user doesn't supply the correct number of arguments, the program exits with an error
50
+ and the usage for the program (hence the libraries name).
51
+
52
+ PROGRAM: test.rb
53
+ ERROR: too few arguments 2 expected, 0 given
54
+
55
+ USAGE: test.rb infile outfile
56
+
57
+ 2. Lists of files (...)
58
+
59
+ You can write a program that accepts a list of files by using elipses appended to an
60
+ argument (the following program concatenates the input files into one output file).
61
+
62
+ usage = Usage.new "outfile infiles..."
63
+
64
+ File.open(usage.outfile, "w") do |fo|
65
+ usage.infiles.each do |infile|
66
+ File.open(usage.infile) { |fi| fo.write(fi.read)}
67
+ end
68
+ end
69
+
70
+ 3. Optional arguments
71
+
72
+ You can have optional arguments by surounding them in square brackets.
73
+
74
+ usage = Usage.new "[optional_arg] required_arg"
75
+
76
+ These are accessed in the standard way
77
+
78
+ usage.optional_arg # this is nil if it is not given by the user
79
+
80
+ usage.required_arg
81
+
82
+ 4. Options
83
+
84
+ You can have dash options that are either required or optional. Options can also have
85
+ arguments associated with them.
86
+
87
+ usage = Usage.new "[-y] [-x excluded_tags] (-z ztag) (-w warning_arg) files..."
88
+
89
+ The options are accessed with "dash_" prefixing the option so that the -y is accessed
90
+ via .dash_y. The -x can be accessed either with #dash_x (which would be either nil or
91
+ true) or #excluded_tags (which would be either nil or the argument for the -x option).
92
+ The -z option is required and has one argument, also the -w option is also required.
93
+ They can appear in any order (-z option first or -w option first). The optional arguments
94
+ can appear either before, interspersed with, or after the required options.
95
+
96
+ 5. Long Options
97
+
98
+ You can also have long options by including lines following the initial usage line that
99
+ associates the short options with the long ones. Example below:
100
+
101
+ usage = Usage.new "-x files...", <<EOT
102
+ -x,--exclusive specifies exclusive access to the files
103
+ EOT
104
+
105
+ With this case, now #dash_x and #exclusive give the same result when applied to the usage
106
+ variable.
107
+
108
+ 6. Typed options
109
+
110
+ In order to remove a step and improve argument checking, you can also add in a "type"
111
+ character to identify its type. The characters I used are somewhat arbitrary. Some of
112
+ them I took from BASIC which I programmed in long long ago.
113
+
114
+ % - Integer
115
+ $ - String (but this is unnecessary as this is default)
116
+ # - Float
117
+ @ - Date-Time
118
+
119
+ So when you send the argument message to the usage object, you will get a value of that
120
+ type and if the user does not give that type, then they get an error message.
121
+
122
+ usage = Usage.new "%num_times @on_date"
123
+
124
+ In this example, #num_times returns and Integer object and #on_date returns a Time object.
125
+
126
+ 7. Choice options
127
+
128
+ You can have optional options that have a set of values which they can be. The choices
129
+ are separated by pipe symbols. See below:
130
+
131
+ usage = Usage.new "[-a coffee|tea|milk]"
132
+
133
+ After this #dash_a will give the string coffee, tea, or milk. If the value given isn't
134
+ one of the given choices, then the user is given an error message with the
135
+ appropriate choices.
136
+
137
+
data/TODO ADDED
@@ -0,0 +1,6 @@
1
+ 1. Parse more styles of date/time than currently
2
+ 2. Add ability to add types in a pluggable way.
3
+ 3. Add a type for input files and output files. In those cases, the
4
+ file could be opened for reading or writing respectively and
5
+ it could yield a File object.
6
+