clasp-ruby 0.23.0.1 → 0.23.0.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +63 -52
- data/examples/cr-example.rb +16 -16
- data/examples/flag_and_option_specifications.md +25 -25
- data/examples/flag_and_option_specifications.rb +6 -6
- data/examples/show_usage_and_version.md +5 -5
- data/examples/show_usage_and_version.rb +1 -1
- data/examples/simple_command_line_no_specifications.rb +1 -1
- data/lib/clasp/arguments.rb +538 -537
- data/lib/clasp/clasp.rb +7 -7
- data/lib/clasp/cli.rb +140 -135
- data/lib/clasp/doc_.rb +3 -3
- data/lib/clasp/old_module.rb +3 -3
- data/lib/clasp/specifications.rb +337 -333
- data/lib/clasp/util/exceptions.rb +17 -17
- data/lib/clasp/util/value_parser.rb +97 -97
- data/lib/clasp/version.rb +15 -15
- data/lib/clasp-ruby.rb +3 -2
- data/lib/clasp.rb +3 -2
- data/test/scratch/test_list_command_line.rb +6 -6
- data/test/scratch/test_specifications.rb +14 -14
- data/test/scratch/test_usage.rb +6 -6
- data/test/scratch/test_usage_from_DATA.rb +1 -1
- data/test/scratch/test_usage_with_duplicate_specifications.rb +6 -6
- data/test/unit/tc_ARGV_rewrite.rb +36 -38
- data/test/unit/tc_arguments_1.rb +694 -694
- data/test/unit/tc_arguments_2.rb +52 -53
- data/test/unit/tc_arguments_3.rb +77 -77
- data/test/unit/tc_arguments_inspect.rb +55 -56
- data/test/unit/tc_cli.rb +4 -4
- data/test/unit/tc_default_value.rb +91 -91
- data/test/unit/tc_defaults_1.rb +38 -38
- data/test/unit/tc_examples_Arguments.rb +130 -132
- data/test/unit/tc_extras.rb +24 -26
- data/test/unit/tc_option_required.rb +38 -39
- data/test/unit/tc_option_value_aliases.rb +44 -44
- data/test/unit/tc_specifications.rb +7 -8
- data/test/unit/tc_typed_options.rb +204 -204
- data/test/unit/tc_usage.rb +112 -55
- data/test/unit/tc_with_action.rb +23 -24
- data/test/unit/ts_all.rb +1 -1
- metadata +5 -4
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 6116d56077b53fd8d42a2f1275e08d5921982e2d4ffe425e9df637d6a7d97861
|
4
|
+
data.tar.gz: 778800e1fcacd3b7ccbb6911c3251c5fcca73fef3447c01318b458c36ef7472a
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 56d7aa277b5f5441c9472d0bb1e8961ccd577ae6477e3ec82f5a932aa6033aa3bbd4506d290e664a4f74c1f2cf9915fb4bb7b41606f884a32e1f7a29dec0ab20
|
7
|
+
data.tar.gz: 33474797746dfe908b5d083d4aaedf4922d9b2cd990b0264595f557c1075d70ef0aa07d0940e1d3ed94869c0a70b999fdc3a3677f64145b2b2e6578afd904f13
|
data/README.md
CHANGED
@@ -1,32 +1,40 @@
|
|
1
|
-
# CLASP.Ruby
|
1
|
+
# CLASP.Ruby <!-- omit in toc -->
|
2
2
|
Command-Line Argument Sorting and Parsing, for Ruby
|
3
3
|
|
4
4
|
[![Gem Version](https://badge.fury.io/rb/clasp-ruby.svg)](https://badge.fury.io/rb/clasp-ruby)
|
5
5
|
|
6
|
-
## Table of Contents
|
7
|
-
|
8
|
-
|
9
|
-
|
10
|
-
|
11
|
-
|
12
|
-
|
6
|
+
## Table of Contents <!-- omit in toc -->
|
7
|
+
|
8
|
+
- [Introduction](#introduction)
|
9
|
+
- [libCLImate.Ruby](#libclimateruby)
|
10
|
+
- [Installation](#installation)
|
11
|
+
- [Components](#components)
|
12
|
+
- [Command-line parsing](#command-line-parsing)
|
13
|
+
- [Declarative specification of the flags and options for a CLI](#declarative-specification-of-the-flags-and-options-for-a-cli)
|
14
|
+
- [Utility functions for displaying usage and version information](#utility-functions-for-displaying-usage-and-version-information)
|
15
|
+
- [Examples](#examples)
|
16
|
+
- [Project Information](#project-information)
|
17
|
+
- [Where to get help](#where-to-get-help)
|
18
|
+
- [Contribution guidelines](#contribution-guidelines)
|
19
|
+
- [Related projects](#related-projects)
|
20
|
+
- [License](#license)
|
13
21
|
|
14
22
|
## Introduction
|
15
23
|
|
16
|
-
**CLASP** stands for
|
17
|
-
|
18
|
-
|
19
|
-
|
24
|
+
**CLASP** stands for **C**ommand-**L**ine **A**rgument **S**orting and **P**arsing. The first **CLASP** library was a C library with a C++ wrapper (see project [**CLASP**](https://github.com/synesissoftware/CLASP/)). There have been several implementations in other languages (as listed in [Relation projects](#related-projects)). **CLASP.Ruby** is the Ruby version.
|
25
|
+
|
26
|
+
All **CLASP** libraries provide the facilities to **C**ommand **L**ine **I**nterface (**CLI**) programs as described in detail below.
|
27
|
+
|
28
|
+
### libCLImate.Ruby
|
20
29
|
|
21
|
-
|
22
|
-
**I**nterface (**CLI**) programs as described in detail below.
|
30
|
+
The [**libCLImate.Ruby**](https://github.com/synesissoftware/libCLImate.Ruby) library is implemented in terms of **CLASP.Ruby** but provides a higher-level abstration as well as several utility functions and the facility to fully specify command-line arguments declaratively in the `__END__` section of a source file. More information and examples provided in the [**libCLImate.Ruby**](https://github.com/synesissoftware/libCLImate.Ruby) project.
|
23
31
|
|
24
32
|
## Installation
|
25
33
|
|
26
34
|
Install via **gem** as in:
|
27
35
|
|
28
36
|
```
|
29
|
-
|
37
|
+
gem install clasp-ruby
|
30
38
|
```
|
31
39
|
|
32
40
|
or add it to your `Gemfile`.
|
@@ -50,7 +58,7 @@ All **CLASP** libraries discriminate between three types of command-line argumen
|
|
50
58
|
For example, in the command line
|
51
59
|
|
52
60
|
```
|
53
|
-
|
61
|
+
myprog --all -c --opt1=val1 infile outfile
|
54
62
|
```
|
55
63
|
|
56
64
|
there are:
|
@@ -62,25 +70,25 @@ there are:
|
|
62
70
|
*Flags* and *options* may have alias. If the alias for `--all` is `-a` and the alias for `--opt1` is `-o` then the following command-line is exactly equivalent to the previous one:
|
63
71
|
|
64
72
|
```
|
65
|
-
|
73
|
+
myprog -a -c -o val1 infile outfile
|
66
74
|
```
|
67
75
|
|
68
76
|
One-letter *flags* may be combined. Hence, the following command-line is exactly equivalent to the previous ones:
|
69
77
|
|
70
78
|
```
|
71
|
-
|
79
|
+
myprog -ac -o val1 infile outfile
|
72
80
|
```
|
73
81
|
|
74
82
|
Option aliases may specify a value. If the alias `-v1` means `--opt1=val1` then the following command-line is exactly equivalent to the previous ones:
|
75
83
|
|
76
84
|
```
|
77
|
-
|
85
|
+
myprog -ac -v1 infile outfile
|
78
86
|
```
|
79
87
|
|
80
88
|
Option aliases that are one letter may be combined with one-letter flags. If the alias `-v` means `--opt1=val1` then the following command-line is exactly equivalent to the previous ones:
|
81
89
|
|
82
90
|
```
|
83
|
-
|
91
|
+
myprog -acv infile outfile
|
84
92
|
```
|
85
93
|
|
86
94
|
UNIX standard arguments confer specific meanings:
|
@@ -104,14 +112,14 @@ PROGRAM_VERSION = '0.1.2'
|
|
104
112
|
|
105
113
|
Specifications = [
|
106
114
|
|
107
|
-
|
108
|
-
|
109
|
-
|
110
|
-
|
115
|
+
CLASP.Flag('--all', alias: '-a', help: 'processes all item types'),
|
116
|
+
CLASP.Flag('-c', help: 'count the processed items'),
|
117
|
+
CLASP.Option('--opt1', alias: '-o', help: 'an option of some kind', values_range: %w{ val1, val2 }),
|
118
|
+
CLASP.Flag('--opt1=val1', alias: '-v'),
|
111
119
|
|
112
|
-
|
113
|
-
|
114
|
-
|
120
|
+
# see next section for why these two are here
|
121
|
+
CLASP::Flag.Help,
|
122
|
+
CLASP::Flag.Version,
|
115
123
|
]
|
116
124
|
|
117
125
|
# assuming the command-line `myprog -acv infile outfile`
|
@@ -139,25 +147,25 @@ There are aspects common to all CLI programs, such as responding to `--help` and
|
|
139
147
|
|
140
148
|
Args.flags.each do |f|
|
141
149
|
|
142
|
-
|
143
|
-
|
150
|
+
case f.name
|
151
|
+
when CLASP::Flag.Help.name
|
144
152
|
|
145
|
-
|
146
|
-
|
153
|
+
CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
|
154
|
+
when CLASP::Flag.Version.name
|
147
155
|
|
148
|
-
|
149
|
-
|
156
|
+
CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
|
157
|
+
when '--all'
|
150
158
|
|
151
|
-
|
159
|
+
# do something appropriate to `--all`
|
152
160
|
|
153
|
-
|
161
|
+
. . .
|
154
162
|
|
155
163
|
```
|
156
164
|
|
157
165
|
Given the command
|
158
166
|
|
159
167
|
```
|
160
|
-
|
168
|
+
./cr-example.rb --help
|
161
169
|
```
|
162
170
|
|
163
171
|
then the program will output the following
|
@@ -167,32 +175,32 @@ USAGE: cr-example.rb [ ... flags and options ... ] <input-file> <output-file>
|
|
167
175
|
|
168
176
|
flags/options:
|
169
177
|
|
170
|
-
|
171
|
-
|
172
|
-
|
178
|
+
-a
|
179
|
+
--all
|
180
|
+
processes all item types
|
173
181
|
|
174
|
-
|
175
|
-
|
182
|
+
-c
|
183
|
+
count the processed items
|
176
184
|
|
177
|
-
|
178
|
-
|
179
|
-
|
180
|
-
|
181
|
-
|
182
|
-
|
185
|
+
-v --opt1=val1
|
186
|
+
-o <value>
|
187
|
+
--opt1=<value>
|
188
|
+
an option of some kind where <value> one of:
|
189
|
+
val1,
|
190
|
+
val2
|
183
191
|
|
184
|
-
|
185
|
-
|
192
|
+
--help
|
193
|
+
shows this help and terminates
|
186
194
|
|
187
|
-
|
188
|
-
|
195
|
+
--version
|
196
|
+
shows version and terminates
|
189
197
|
|
190
198
|
```
|
191
199
|
|
192
200
|
and given the command
|
193
201
|
|
194
202
|
```
|
195
|
-
|
203
|
+
./cr-example.rb --version
|
196
204
|
```
|
197
205
|
|
198
206
|
then the program will output the following
|
@@ -239,3 +247,6 @@ Projects in which **CLASP.Ruby** is used include:
|
|
239
247
|
|
240
248
|
**CLASP.Ruby** is released under the 3-clause BSD license. See LICENSE for details.
|
241
249
|
|
250
|
+
|
251
|
+
<!-- ########################### end of file ########################### -->
|
252
|
+
|
data/examples/cr-example.rb
CHANGED
@@ -11,31 +11,31 @@ PROGRAM_VERSION = '0.1.2'
|
|
11
11
|
|
12
12
|
Specifications = [
|
13
13
|
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
|
19
|
-
|
20
|
-
|
21
|
-
|
14
|
+
CLASP.Flag('--all', alias: '-a', help: 'processes all item types'),
|
15
|
+
CLASP.Flag('-c', help: 'count the processed items'),
|
16
|
+
CLASP.Option('--opt1', alias: '-o', help: 'an option of some kind', values_range: %w{ val1, val2 }),
|
17
|
+
CLASP.Flag('--opt1=val1', alias: '-v'),
|
18
|
+
|
19
|
+
# see next section for why these two are here
|
20
|
+
CLASP::Flag.Help,
|
21
|
+
CLASP::Flag.Version,
|
22
22
|
]
|
23
23
|
|
24
24
|
Args = CLASP::Arguments.new(ARGV, Specifications)
|
25
25
|
|
26
26
|
Args.flags.each do |f|
|
27
27
|
|
28
|
-
|
29
|
-
|
28
|
+
case f.name
|
29
|
+
when CLASP::Flag.Help.name
|
30
30
|
|
31
|
-
|
32
|
-
|
31
|
+
CLASP.show_usage(Specifications, exit: 0, values: '<input-file> <output-file>')
|
32
|
+
when CLASP::Flag.Version.name
|
33
33
|
|
34
|
-
|
35
|
-
|
34
|
+
CLASP.show_version(Specifications, exit: 0, version: PROGRAM_VERSION)
|
35
|
+
when '--all'
|
36
36
|
|
37
|
-
|
38
|
-
|
37
|
+
;
|
38
|
+
end
|
39
39
|
end
|
40
40
|
|
41
41
|
puts Args.flags.size
|
@@ -35,9 +35,9 @@ Flag_Chatty = CLASP.Flag('--verbosity=chatty', alias: '-c')
|
|
35
35
|
|
36
36
|
Specifications = [
|
37
37
|
|
38
|
-
|
39
|
-
|
40
|
-
|
38
|
+
Flag_Debug,
|
39
|
+
Option_Verbosity,
|
40
|
+
Flag_Chatty,
|
41
41
|
|
42
42
|
CLASP::FlagSpecification.Help,
|
43
43
|
CLASP::FlagSpecification.Version,
|
@@ -60,12 +60,12 @@ end
|
|
60
60
|
|
61
61
|
if (opt = args.find_option('--verbosity'))
|
62
62
|
|
63
|
-
|
63
|
+
$stdout.puts "verbosity is specified as: #{opt.value}"
|
64
64
|
end
|
65
65
|
|
66
66
|
if args.flags.include?('--debug')
|
67
67
|
|
68
|
-
|
68
|
+
$stdout.puts 'Debug mode is specified'
|
69
69
|
end
|
70
70
|
|
71
71
|
|
@@ -74,7 +74,7 @@ end
|
|
74
74
|
|
75
75
|
if (unused = args.find_first_unknown())
|
76
76
|
|
77
|
-
|
77
|
+
$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
|
78
78
|
|
79
79
|
exit 1
|
80
80
|
end
|
@@ -120,25 +120,25 @@ USAGE: flag_and_option_specifications.rb [ ... flags and options ... ]
|
|
120
120
|
|
121
121
|
flags/options:
|
122
122
|
|
123
|
-
|
124
|
-
|
125
|
-
|
126
|
-
|
127
|
-
|
128
|
-
|
129
|
-
|
130
|
-
|
131
|
-
|
132
|
-
|
133
|
-
|
134
|
-
|
135
|
-
|
136
|
-
|
137
|
-
|
138
|
-
|
139
|
-
|
140
|
-
|
141
|
-
|
123
|
+
-d
|
124
|
+
--debug
|
125
|
+
runs in Debug mode
|
126
|
+
|
127
|
+
-c --verbosity=chatty
|
128
|
+
-v <value>
|
129
|
+
--verbosity=<value>
|
130
|
+
specifies the verbosity
|
131
|
+
where <value> one of:
|
132
|
+
terse *default*
|
133
|
+
quiet
|
134
|
+
silent
|
135
|
+
chatty
|
136
|
+
|
137
|
+
--help
|
138
|
+
shows this help and terminates
|
139
|
+
|
140
|
+
--version
|
141
|
+
shows version and terminates
|
142
142
|
```
|
143
143
|
|
144
144
|
### Specify flags and options in long-form
|
@@ -26,9 +26,9 @@ Flag_Chatty = CLASP.Flag('--verbosity=chatty', alias: '-c')
|
|
26
26
|
|
27
27
|
Specifications = [
|
28
28
|
|
29
|
-
|
30
|
-
|
31
|
-
|
29
|
+
Flag_Debug,
|
30
|
+
Option_Verbosity,
|
31
|
+
Flag_Chatty,
|
32
32
|
|
33
33
|
CLASP::FlagSpecification.Help,
|
34
34
|
CLASP::FlagSpecification.Version,
|
@@ -51,12 +51,12 @@ end
|
|
51
51
|
|
52
52
|
if (opt = args.find_option('--verbosity'))
|
53
53
|
|
54
|
-
|
54
|
+
$stdout.puts "verbosity is specified as: #{opt.value}"
|
55
55
|
end
|
56
56
|
|
57
57
|
if args.flags.include?('--debug')
|
58
58
|
|
59
|
-
|
59
|
+
$stdout.puts 'Debug mode is specified'
|
60
60
|
end
|
61
61
|
|
62
62
|
|
@@ -65,7 +65,7 @@ end
|
|
65
65
|
|
66
66
|
if (unused = args.find_first_unknown())
|
67
67
|
|
68
|
-
|
68
|
+
$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
|
69
69
|
|
70
70
|
exit 1
|
71
71
|
end
|
@@ -52,7 +52,7 @@ end
|
|
52
52
|
|
53
53
|
if (unused = args.find_first_unknown())
|
54
54
|
|
55
|
-
|
55
|
+
$stderr.puts "#{args.program_name}: unrecognised flag/option: #{unused}"
|
56
56
|
|
57
57
|
sys.exit(1)
|
58
58
|
end
|
@@ -102,11 +102,11 @@ USAGE: show_usage_and_version.rb [ ... flags and options ... ]
|
|
102
102
|
|
103
103
|
flags/options:
|
104
104
|
|
105
|
-
|
106
|
-
|
105
|
+
--help
|
106
|
+
Shows usage and terminates
|
107
107
|
|
108
|
-
|
109
|
-
|
108
|
+
--version
|
109
|
+
Shows version and terminates
|
110
110
|
```
|
111
111
|
|
112
112
|
### Show version
|
@@ -25,6 +25,6 @@ puts args.values[0].given_index # => 1
|
|
25
25
|
puts args.values[1] # => outfile
|
26
26
|
puts args.values[1].given_index # => 3
|
27
27
|
|
28
|
-
# ############################## end of file ############################# #
|
29
28
|
|
29
|
+
# ############################## end of file ############################# #
|
30
30
|
|