aargvark 0.0.14 → 0.0.15

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.
Files changed (4) hide show
  1. data/HISTORY +9 -0
  2. data/README +179 -179
  3. data/Rakefile +4 -4
  4. metadata +5 -3
data/HISTORY ADDED
@@ -0,0 +1,9 @@
1
+
2
+ == 0.0.15 / 2009-05-21
3
+
4
+ * 3 minor enhancements
5
+ * Added HISTORY file in /, ammended Rakefile to include HISTORY in rdoc.
6
+ * Fixed bug #25969 (improper description) in /Rakefile.
7
+ * Amended README file to observe proper rdoc indenting for code.
8
+
9
+
data/README CHANGED
@@ -1,180 +1,180 @@
1
1
 
2
- #=Aargvark
3
- # Version 0.0.14
4
- # Updated 2009-05-12
5
- #
6
- # Maintainer: Mike Zazaian, mike@zop.io, http://zop.io
7
- # License: This file is placed in the public domain.
8
- #
9
- #
10
- #=OVERVIEW
11
- #
12
- # Aargvark is a utility written in Ruby to process arguments for command-line
13
- # scripts and applications. It allows you to define a simple structure for your
14
- # script's arguments, then compares them against the ARGV array that's produced
15
- # by Ruby when your script is called from a command line, such as:
16
- #
17
- # ruby myscript.rb -a -b -c --example-alias inputfile.txt outputfile.txt
18
- #
19
- #
20
- #=INSTALL
21
- #
22
- # To install Aargvark, either install Aargvark as a Rubygem, like this:
23
- #
24
- # gem install --remote aargvark
25
- #
26
- # Or just put lib/aargvark.rb in your own script's lib/ directory, and add the path
27
- # to the LOAD_PATH global like this:
28
- #
29
- # $LOAD_PATH << "/path/to/aargvark/directory"
30
- #
31
- # This assumes that /path/to/aargvark/directory is whichever directory in
32
- # which the aargvark.rb file is located.
33
- #
34
- # Once you've got aargvark in place, you can import it into your script with
35
- # *require*, such as:
36
- #
37
- # require 'aargbark'
38
- #
39
- #
40
- #=CREATING AN AARGVARK
41
- #
42
- # Once you've required Aargvark into your script, you can use it catch arguments
43
- # called from a command line like this:
44
- #
45
- # processed_arguments = Aargvark.new(called_arguments, argument_structure)
46
- #
47
- #
48
- # There are three important parts to this equation, being:
49
- #
50
- #
51
- #==*THE CALLED ARGUMENTS ARRAY* An array of arguments called by the
52
- # script's user that are passed into the script. In this example it's intended
53
- # to be Ruby's ARGV array, which automatically passes arguments called from the
54
- # commandline into the Ruby script. However, "called_arguments" can be any
55
- # array within your script that contains called arguments.
56
- #
57
- #==*THE ARGUMENT STRUCTURE ARRAY* This array represents the structure of how the
58
- # script will process and recognize available and required arguments.
59
- #
60
- # This array contains one or more _SUB-ARRAYS_, each of which represent an argument
61
- # that CAN or MUST be passed into the script. An example of basic _SUB-ARRAY_
62
- # structure is:
63
- #
64
- # ["-a", "--alias", :required, [true, :string], [false, :integer], ...]
65
- #
66
- # |-a| *ARGUMENT.* Used to call the argument from the command line. Must
67
- # be a single letter [A-Za-z] preceded by a single hyphen "-".
68
- #
69
- # This is the only value that MUST be included regardless of whether or
70
- # not an ALIAS is provided. If both an ARGUMENT and an ALIAS are
71
- # set in the structure array, only ONE of the can be called from
72
- # the commandline when invoking the script, otherwise an error will
73
- # be thrown.
74
- #
75
- # |--alias| *ALIAS.* Must be a series of uppercase, lowercase letters and
76
- # hyphens [A-Za-z\-] preceded by two hyphens "--".
77
- #
78
- # Can be used in substitute of the argument to call the argument
79
- # from the commandline, but cannot be called simultaneously with the
80
- # argument. May be OMITTED.
81
- #
82
- # |:required| *REQUIREMENT.* Determines whether this argument (or its alias) is
83
- # required to be called when running the script. This may be set as
84
- # either :required, or OMITTED.
85
- #
86
- #|[true, :string]| *SUB-ARGUMENT.* The first value (true||false) indicates whether the
87
- # sub-argument must be called along with the argument. The second
88
- # value (:string||:integer||:float), determines what type of
89
- # information must be passed in this place. May be OMITTED.
90
- #
91
- # |...| *PLACEHOLDER FOR MORE SUB-ARGUMENTS.* May be as few or as many as
92
- # you need, or may be OMITTED.
93
- #
94
- # To break this down a bit, this sub-array represents ONE ARGUMENT that can be
95
- # called with the letter "-a", OR its alias "--alias". The :required symbol after
96
- # the alias indicates that this argument must be called when running the parent
97
- # script. So that's the first part of the sub-array.
98
- #
99
- # The remaining arrays represent *SUB-ARGUMENTS*, arguments that can or must be
100
- # called along with the primary argument. The first value in the *SUB-ARGUMENT*
101
- # array is boolean (true||false) indicating whether or not the sub-argument is
102
- # required, and the second value is a symbol (:string|:integer|:float) indicating
103
- # the type of data that the subargument must contain.
104
- #
105
- #
106
- #===EXAMPLES OF VALID SUB-ARRAYS
107
- #
108
- # An argument that is called with the letter -r that has the alias "--recursive":
109
- #
110
- # ["-r", "--recursive"]
111
- #
112
- # An argument that is called with the letter -b, that has no alias, but is required
113
- # and has two sub-arguments that are strings and are also required.
114
- #
115
- # ["-b", :required, [true, :string], [true, :string]]
116
- #
117
- # An argument called with the letter -z that has the alias "--zip-me-up", is
118
- # required, has one integer sub-argument that is required, and one float
119
- # sub-argument that isn't required.
120
- #
121
- # ["-z", "--zip-me-up", :required, [true, :integer], [false, :float]]
122
- #
123
- # An argument that is only called with the letter -c, has no alias or
124
- # sub-arguments, and is not required.
125
- #
126
- # ["-c"]
127
- #
128
- #
129
- #===THE NO-ARGUMENT SUB-ARRAY
130
- #
131
- # Sometimes you may want to include an argument that isn't called with a letter or
132
- # an alias. For this you use the [:noarg] array.
133
- #
134
- # The [:noarg] array, or, if it's required, the [:noarg, :required] array, can be
135
- # included at the end of the *ARGUMENT STRUCTURE ARRAY*, after all *ARGUMENT
136
- # SUB-ARRAYS* are called.
137
- #
138
- #
139
- #===AN EXAMPLE OF A FULL ARGUMENT-STRUCTURE ARRAY
140
- #
141
- # Here's an example of a full *ARGUMENT-STRUCTURE ARRAY*. Note that the order of
142
- # the sub-arrays doesn't matter ("-e" can be called after "-c"), except for the
143
- # fact that all [:noarg] arguments must be placed at the end of the array.
144
- #
145
- # argument structure = []
146
- # argument_structure << ["-a", "--alias", :required]
147
- # argument_structure << ["-e"]
148
- # argument_structure << ["-c", :required, [true, :string]]
149
- # argument_structure << [:noarg, :required]
150
- # argument_structure << [:noarg]
151
- #
152
- # OR
153
- #
154
- # argument_structure = [["-a", "--alias", :required], ["-e"], ["-c", :required, [true, :string]], [:noarg, :required], [:noarg]]
155
- #
156
- #
157
- #== THE PROCESSED ARGUMENTS ARRAY
158
- #
159
- # The result of comparing the *CALLED ARGUMENTS ARRAY* (ARGV, etc.) against the
160
- # *ARGUMENT STRUCTURE ARRAY* (such as the one seen above).
161
- #
162
- # If the *ARGUMENT-STRUCTURE ARRAY* is of the correct format, and all of the
163
- # arguments passed in from the *CALLED ARGUMENTS ARRAY* fit that structure, this
164
- # array will spit out a single-level array with all of the *ARGUMENT* and
165
- # SUB-ARGUMENT values that have been passed into the script.
166
- #
167
- #
168
- #===AN EXAMPLE OF A PROCESSED ARGUMENTS ARRAY
169
- #
170
- # Suppose you passed arguments into the script according to the *ARGUMENT-STRUCTURE
171
- # ARRAY* seen immediately above. The resulting array, which would be identical to
172
- # the incoming ARGV array, might look something like this:
173
- #
174
- # ["-a", "-c", "file_name.txt", "output_file.txt"]
175
- #
176
- # Note that this array contains only four values, as only four are required by the
177
- # above *ARGUMENT-STRUCTURE ARRAY*, but this include as many as SIX values if the
178
- # argument "-e" were called, along with a value for the second [:noarg].
179
- #
180
- #
2
+ =Aargvark
3
+ Version 0.0.14
4
+ Updated 2009-05-12
5
+
6
+ Maintainer: Mike Zazaian, mike@zop.io, http://zop.io
7
+ License: This file is placed in the public domain.
8
+
9
+
10
+ =OVERVIEW
11
+
12
+ Aargvark is a utility written in Ruby to process arguments for command-line
13
+ scripts and applications. It allows you to define a simple structure for your
14
+ script's arguments, then compares them against the ARGV array that's produced
15
+ by Ruby when your script is called from a command line, such as:
16
+
17
+ ruby myscript.rb -a -b -c --example-alias inputfile.txt outputfile.txt
18
+
19
+
20
+ =INSTALL
21
+
22
+ To install Aargvark, either install Aargvark as a Rubygem, like this:
23
+
24
+ gem install --remote aargvark
25
+
26
+ Or just put lib/aargvark.rb in your own script's lib/ directory, and add the path
27
+ to the LOAD_PATH global like this:
28
+
29
+ $LOAD_PATH << "/path/to/aargvark/directory"
30
+
31
+ This assumes that /path/to/aargvark/directory is whichever directory in
32
+ which the aargvark.rb file is located.
33
+
34
+ Once you've got aargvark in place, you can import it into your script with
35
+ *require*, such as:
36
+
37
+ require 'aargbark'
38
+
39
+
40
+ =CREATING AN AARGVARK
41
+
42
+ Once you've required Aargvark into your script, you can use it catch arguments
43
+ called from a command line like this:
44
+
45
+ processed_arguments = Aargvark.new(called_arguments, argument_structure)
46
+
47
+
48
+ There are three important parts to this equation, being:
49
+
50
+
51
+ ==*THE CALLED ARGUMENTS ARRAY* An array of arguments called by the
52
+ script's user that are passed into the script. In this example it's intended
53
+ to be Ruby's ARGV array, which automatically passes arguments called from the
54
+ commandline into the Ruby script. However, "called_arguments" can be any
55
+ array within your script that contains called arguments.
56
+
57
+ ==*THE ARGUMENT STRUCTURE ARRAY* This array represents the structure of how the
58
+ script will process and recognize available and required arguments.
59
+
60
+ This array contains one or more _SUB-ARRAYS_, each of which represent an argument
61
+ that CAN or MUST be passed into the script. An example of basic _SUB-ARRAY_
62
+ structure is:
63
+
64
+ ["-a", "--alias", :required, [true, :string], [false, :integer], ...]
65
+
66
+ |-a| *ARGUMENT.* Used to call the argument from the command line. Must
67
+ be a single letter [A-Za-z] preceded by a single hyphen "-".
68
+
69
+ This is the only value that MUST be included regardless of whether or
70
+ not an ALIAS is provided. If both an ARGUMENT and an ALIAS are
71
+ set in the structure array, only ONE of the can be called from
72
+ the commandline when invoking the script, otherwise an error will
73
+ be thrown.
74
+
75
+ |--alias| *ALIAS.* Must be a series of uppercase, lowercase letters and
76
+ hyphens [A-Za-z\-] preceded by two hyphens "--".
77
+
78
+ Can be used in substitute of the argument to call the argument
79
+ from the commandline, but cannot be called simultaneously with the
80
+ argument. May be OMITTED.
81
+
82
+ |:required| *REQUIREMENT.* Determines whether this argument (or its alias) is
83
+ required to be called when running the script. This may be set as
84
+ either :required, or OMITTED.
85
+
86
+ |[true, :string]| *SUB-ARGUMENT.* The first value (true||false) indicates whether the
87
+ sub-argument must be called along with the argument. The second
88
+ value (:string||:integer||:float), determines what type of
89
+ information must be passed in this place. May be OMITTED.
90
+
91
+ |...| *PLACEHOLDER FOR MORE SUB-ARGUMENTS.* May be as few or as many as
92
+ you need, or may be OMITTED.
93
+
94
+ To break this down a bit, this sub-array represents ONE ARGUMENT that can be
95
+ called with the letter "-a", OR its alias "--alias". The :required symbol after
96
+ the alias indicates that this argument must be called when running the parent
97
+ script. So that's the first part of the sub-array.
98
+
99
+ The remaining arrays represent *SUB-ARGUMENTS*, arguments that can or must be
100
+ called along with the primary argument. The first value in the *SUB-ARGUMENT*
101
+ array is boolean (true||false) indicating whether or not the sub-argument is
102
+ required, and the second value is a symbol (:string|:integer|:float) indicating
103
+ the type of data that the subargument must contain.
104
+
105
+
106
+ ===EXAMPLES OF VALID SUB-ARRAYS
107
+
108
+ An argument that is called with the letter -r that has the alias "--recursive":
109
+
110
+ ["-r", "--recursive"]
111
+
112
+ An argument that is called with the letter -b, that has no alias, but is required
113
+ and has two sub-arguments that are strings and are also required.
114
+
115
+ ["-b", :required, [true, :string], [true, :string]]
116
+
117
+ An argument called with the letter -z that has the alias "--zip-me-up", is
118
+ required, has one integer sub-argument that is required, and one float
119
+ sub-argument that isn't required.
120
+
121
+ ["-z", "--zip-me-up", :required, [true, :integer], [false, :float]]
122
+
123
+ An argument that is only called with the letter -c, has no alias or
124
+ sub-arguments, and is not required.
125
+
126
+ ["-c"]
127
+
128
+
129
+ ===THE NO-ARGUMENT SUB-ARRAY
130
+
131
+ Sometimes you may want to include an argument that isn't called with a letter or
132
+ an alias. For this you use the [:noarg] array.
133
+
134
+ The [:noarg] array, or, if it's required, the [:noarg, :required] array, can be
135
+ included at the end of the *ARGUMENT STRUCTURE ARRAY*, after all *ARGUMENT
136
+ SUB-ARRAYS* are called.
137
+
138
+
139
+ ===AN EXAMPLE OF A FULL ARGUMENT-STRUCTURE ARRAY
140
+
141
+ Here's an example of a full *ARGUMENT-STRUCTURE ARRAY*. Note that the order of
142
+ the sub-arrays doesn't matter ("-e" can be called after "-c"), except for the
143
+ fact that all [:noarg] arguments must be placed at the end of the array.
144
+
145
+ argument structure = []
146
+ argument_structure << ["-a", "--alias", :required]
147
+ argument_structure << ["-e"]
148
+ argument_structure << ["-c", :required, [true, :string]]
149
+ argument_structure << [:noarg, :required]
150
+ argument_structure << [:noarg]
151
+
152
+ OR
153
+
154
+ argument_structure = [["-a", "--alias", :required], ["-e"], ["-c", :required, [true, :string]], [:noarg, :required], [:noarg]]
155
+
156
+
157
+ == THE PROCESSED ARGUMENTS ARRAY
158
+
159
+ The result of comparing the *CALLED ARGUMENTS ARRAY* (ARGV, etc.) against the
160
+ *ARGUMENT STRUCTURE ARRAY* (such as the one seen above).
161
+
162
+ If the *ARGUMENT-STRUCTURE ARRAY* is of the correct format, and all of the
163
+ arguments passed in from the *CALLED ARGUMENTS ARRAY* fit that structure, this
164
+ array will spit out a single-level array with all of the *ARGUMENT* and
165
+ SUB-ARGUMENT values that have been passed into the script.
166
+
167
+
168
+ ===AN EXAMPLE OF A PROCESSED ARGUMENTS ARRAY
169
+
170
+ Suppose you passed arguments into the script according to the *ARGUMENT-STRUCTURE
171
+ ARRAY* seen immediately above. The resulting array, which would be identical to
172
+ the incoming ARGV array, might look something like this:
173
+
174
+ ["-a", "-c", "file_name.txt", "output_file.txt"]
175
+
176
+ Note that this array contains only four values, as only four are required by the
177
+ above *ARGUMENT-STRUCTURE ARRAY*, but this include as many as SIX values if the
178
+ argument "-e" were called, along with a value for the second [:noarg].
179
+
180
+
data/Rakefile CHANGED
@@ -6,7 +6,7 @@ require 'rake/gempackagetask'
6
6
 
7
7
  spec = Gem::Specification.new do |s|
8
8
  s.name = "aargvark"
9
- s.version = "0.0.14"
9
+ s.version = "0.0.15"
10
10
  s.author = "Mike Zazaian"
11
11
  s.email = "zazaian@gmail.com"
12
12
  s.homepage = "aargvark.rubyforge.org"
@@ -15,7 +15,7 @@ spec = Gem::Specification.new do |s|
15
15
 
16
16
  s.summary = "A simple, powerful argument parser for Ruby."
17
17
  s.description = <<-EOL
18
- Prawn is a fast, tiny, and nimble PDF generator for Ruby
18
+ A simple, powerful argument parser for Ruby
19
19
  EOL
20
20
 
21
21
  s.files = %[ lib/aargvark.rb ]
@@ -24,12 +24,12 @@ EOL
24
24
  '--main' << 'README' << '-q'
25
25
  s.require_path = "lib"
26
26
  s.has_rdoc = true
27
- s.extra_rdoc_files = %w[ README LICENSE ]
27
+ s.extra_rdoc_files = %w[ README HISTORY LICENSE ]
28
28
  end
29
29
 
30
30
  desc "genrates documentation"
31
31
  Rake::RDocTask.new do |rdoc|
32
- rdoc.rdoc_files.include( "README", "LICENSE", "lib/" )
32
+ rdoc.rdoc_files.include( "README", "HISTORY", "LICENSE", "lib/" )
33
33
  rdoc.main = "README"
34
34
  rdoc.rdoc_dir = "doc/html"
35
35
  rdoc.title = "Aargvark Documentation"
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: aargvark
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.14
4
+ version: 0.0.15
5
5
  platform: ruby
6
6
  authors:
7
7
  - Mike Zazaian
@@ -9,11 +9,11 @@ autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
11
 
12
- date: 2009-05-20 00:00:00 +10:00
12
+ date: 2009-05-21 00:00:00 +10:00
13
13
  default_executable:
14
14
  dependencies: []
15
15
 
16
- description: Prawn is a fast, tiny, and nimble PDF generator for Ruby
16
+ description: A simple, powerful argument parser for Ruby
17
17
  email: zazaian@gmail.com
18
18
  executables: []
19
19
 
@@ -21,11 +21,13 @@ extensions: []
21
21
 
22
22
  extra_rdoc_files:
23
23
  - README
24
+ - HISTORY
24
25
  - LICENSE
25
26
  files:
26
27
  - lib/aargvark.rb
27
28
  - Rakefile
28
29
  - README
30
+ - HISTORY
29
31
  - LICENSE
30
32
  has_rdoc: true
31
33
  homepage: aargvark.rubyforge.org