mercenary 0.3.1 → 0.3.2

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 3c649528973138a967d8f6cafe92e65ae25a4a95
4
- data.tar.gz: 3a7b3477db81d199a956536247c0c0e6bd44fda9
3
+ metadata.gz: f8c6f00310335bb25ca352dd2172054bad0b3c24
4
+ data.tar.gz: 3dbc954fbe05ddd60c274f39e59cd19b8ffedc42
5
5
  SHA512:
6
- metadata.gz: 906d1c04846f347c39bed714774527ccc7173b80e15799a69852368003b3d720da0e3dd0134a6069d7e353fa1c77205ca3e29cec731d0172b44377157b664bee
7
- data.tar.gz: 6158035bcfa8721c4494498daba38e346d653484b20d29574bda9913dd8fd2f98cfee754227aa28c806a955a627582e3036b2df99819640784dff354152cee9b
6
+ metadata.gz: ff3e130d16901f12c6e30f4cbfeb24b7ba589350a785fbfd1386d3e418fdd683fa3771b915a1162334dff36a924d693c2a4b56a556372b2a6c79e493f8070f6b
7
+ data.tar.gz: 07c5c6bdb22f47880044fc1fb4ba90c122b8eae3c7bce02d95c3a8561eb29541ee5473b5043865b513f3b687749ce8664b51b090186e28ed0e6a4be7634d8caa
@@ -8,6 +8,13 @@
8
8
 
9
9
  ### Development Fixes
10
10
 
11
+ ## 0.3.2 / 2014-03-18
12
+
13
+ ### Bug Fixes
14
+
15
+ * Remove duplicate commands from help output; show aliases w/command names
16
+ (#29)
17
+
11
18
  ## 0.3.1 / 2014-02-21
12
19
 
13
20
  ### Minor Enhancements
data/README.md CHANGED
@@ -70,6 +70,177 @@ All commands have the following default options:
70
70
  - `-v/--version` - show the program version
71
71
  - `-t/--trace` - show the full backtrace when an error occurs
72
72
 
73
+ ## API
74
+
75
+ ### `Mercenary`
76
+
77
+ #### `.program`
78
+
79
+ Creates and executes a program. Accepts two arguments:
80
+
81
+ - `name` - program name as a Symbol
82
+ - `block` - the specification for the program, passed the program instance as an
83
+ argument.
84
+
85
+ Example is above, under the heading [Usage](#usage).
86
+
87
+ ### `Program`
88
+
89
+ `Program` is a subclass of `Command`, so it has all of the methods documented
90
+ below as well as those for `Command`.
91
+
92
+ #### `#config`
93
+
94
+ Fetches the program configuration hash.
95
+
96
+ ### `Command`
97
+
98
+ #### `#new`
99
+
100
+ Create a new command. Accepts two arguments:
101
+
102
+ - `name` - the name of your command, as a symbol
103
+ - `parent` - (optional) the parent Command
104
+
105
+ #### `#version`
106
+
107
+ Sets or gets the version of the command. Accepts an optional argument:
108
+
109
+ - `version` - (optional) the version to set for the command. If present, this
110
+ becomes the new version for the command and persists.
111
+
112
+ #### `#syntax`
113
+
114
+ Sets or gets the syntax of the command. Built on parent syntaxes if a parent
115
+ exists. Accepts one optional argument:
116
+
117
+ - `syntax` - (optional) the syntax to set for the command. Will inherit from the
118
+ parent commands or program. Usually in the form of
119
+ `"command_name <SUBCOMMAND> [OPTIONS]"`
120
+
121
+ When a parent command exists, say `supercommand`, with syntax set as
122
+ `supercommand <SUBCOMMAND> [OPTIONS]`, the syntax of the command in question
123
+ will be `supercommand command_name <SUBCOMMAND> [OPTIONS]` with both
124
+ `<SUBCOMMAND>` and `[OPTIONS]` stripped out. Any text between `<` and `>` or
125
+ between `[` and `]` will be stripped from parent command syntaxes. The purpose
126
+ of this chaining is to reduce redundancy.
127
+
128
+ #### `#description`
129
+
130
+ Sets or gets the description of the command. Accepts one optional argument:
131
+
132
+ - `desc` - (optional) the description to set for the command. If
133
+ provided, will override any previous description set for the command.
134
+
135
+ #### `#default_command`
136
+
137
+ Sets or gets the default subcommand of the command to execute in the event no
138
+ subcommand is passed during execution. Accepts one optional argument:
139
+
140
+ - `command_name` - (optional) the `Symbol` name of the subcommand to be
141
+ executed. Raises an `ArgumentError` if the subcommand doesn't exist.
142
+ Overwrites previously-set default commands.
143
+
144
+ #### `#option`
145
+
146
+ Adds a new option to the command. Accepts many arguments:
147
+
148
+ - `config_key` - the configuration key that the value of this option maps to.
149
+ - `*options` - all the options, globbed, to be passed to `OptionParser`, namely the
150
+ switches and the option description. Usually in the format
151
+ `"-s", "--switch", "Sets the 'switch' flag"`.
152
+
153
+ Valid option calls:
154
+
155
+ ```ruby
156
+ cmd.option 'config_key', '-c', 'Sets the "config" flag'
157
+ cmd.option 'config_key', '--config', 'Sets the "config" flag'
158
+ cmd.option 'config_key', '-c', '--config', 'Sets the "config" flag.'
159
+ cmd.option 'config_key', '-c FILE', '--config FILE', 'The config file.'
160
+ cmd.option 'config_key', '-c FILE1[,FILE2[,FILE3...]]', '--config FILE1[,FILE2[,FILE3...]]', Array, 'The config files.'
161
+ ```
162
+
163
+ Notice that you can specify either a short switch, a long switch, or both. If
164
+ you want to accept an argument, you have to specify it in the switch strings.
165
+ The class of the argument defaults to `String`, but you can optionally set a
166
+ different class to create, e.g. `Array`, if you are expecting a particular class
167
+ in your code from this option's value. The description is also optional, but
168
+ it's highly recommended to include a description.
169
+
170
+ #### `#alias`
171
+
172
+ Specifies an alias for this command such that the alias may be used in place of
173
+ the command during execution. Accepts one argument:
174
+
175
+ - `cmd_name` - the alias name for this command as a `Symbol`
176
+
177
+ Example:
178
+
179
+ ```ruby
180
+ cmd.alias(:my_alias)
181
+ # Now `cmd` is now also executable via "my_alias"
182
+ ```
183
+
184
+ #### `#action`
185
+
186
+ Specifies a block to be executed in the event the command is specified at
187
+ runtime. The block is given two arguments:
188
+
189
+ - `args` - the non-switch arguments given from the command-line
190
+ - `options` - the options hash built via the switches passed
191
+
192
+ **Note that actions are additive**, meaning any new call to `#action` will
193
+ result in another action to be executed at runtime. Actions will be executed in
194
+ the order they are specified in.
195
+
196
+ Example:
197
+
198
+ ```ruby
199
+ cmd.action do |args, options|
200
+ # do something!
201
+ end
202
+ ```
203
+
204
+ #### `#logger`
205
+
206
+ Access the logger for this command. Useful for outputting information to STDOUT.
207
+ Accepts one optional argument:
208
+
209
+ - `level` - (optional) the severity threshold at which to begin logging. Uses
210
+ Ruby's built-in
211
+ [`Logger`](http://www.ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html)
212
+ levels.
213
+
214
+ Log level defaults to `Logger::INFO`.
215
+
216
+ Examples:
217
+
218
+ ```ruby
219
+ cmd.logger(Logger::DEBUG)
220
+ cmd.logger.debug "My debug message."
221
+ cmd.logger.info "My informative message."
222
+ cmd.logger.warn "ACHTUNG!!"
223
+ cmd.logger.error "Something terrible has happened."
224
+ cmd.logger.fatal "I can't continue doing what I'm doing."
225
+ ```
226
+
227
+ #### `#command`
228
+
229
+ Creates a new subcommand for the current command. Accepts two arguments:
230
+
231
+ - `cmd_name` - the command name, as a Symbol
232
+ - `block` - the specification of the subcommand in a block
233
+
234
+ Example:
235
+
236
+ ```ruby
237
+ my_command.command(:my_subcommand) do |subcmd|
238
+ subcmd.description 'My subcommand'
239
+ subcmd.syntax 'my_subcommand [OPTIONS]'
240
+ # ...
241
+ end
242
+ ```
243
+
73
244
  ## Contributing
74
245
 
75
246
  1. Fork it
@@ -19,6 +19,7 @@ Mercenary.program(:help_dialogue) do |p|
19
19
  c.syntax 'some_subcommand <subcommand> [options]'
20
20
  c.description 'Some subcommand to do something'
21
21
  c.option 'an_option', '-o', '--option', 'Some option'
22
+ c.alias(:blah)
22
23
 
23
24
  c.command(:yet_another_sub) do |f|
24
25
  f.syntax 'yet_another_sub [options]'
@@ -9,6 +9,7 @@ module Mercenary
9
9
  attr_reader :map
10
10
  attr_accessor :parent
11
11
  attr_reader :trace
12
+ attr_reader :aliases
12
13
 
13
14
  # Public: Creates a new Command
14
15
  #
@@ -25,6 +26,7 @@ module Mercenary
25
26
  @map = {}
26
27
  @parent = parent
27
28
  @trace = false
29
+ @aliases = []
28
30
  end
29
31
 
30
32
  # Public: Sets or gets the command version
@@ -113,6 +115,7 @@ module Mercenary
113
115
  # Returns nothing
114
116
  def alias(cmd_name)
115
117
  logger.debug "adding alias to parent for self: '#{cmd_name}'"
118
+ aliases << cmd_name
116
119
  @parent.commands[cmd_name] = self
117
120
  end
118
121
 
@@ -253,11 +256,18 @@ module Mercenary
253
256
  the_name.join(" ")
254
257
  end
255
258
 
259
+ # Public: Return all the names and aliases for this command.
260
+ #
261
+ # Returns a comma-separated String list of the name followed by its aliases
262
+ def names_and_aliases
263
+ ([name.to_s] + aliases).compact.join(", ")
264
+ end
265
+
256
266
  # Public: Build a string containing a summary of the command
257
267
  #
258
268
  # Returns a one-line summary of the command.
259
269
  def summarize
260
- " #{name.to_s.ljust(20)} #{description}"
270
+ " #{names_and_aliases.ljust(20)} #{description}"
261
271
  end
262
272
 
263
273
  # Public: Build a string containing the command name, options and any subcommands
@@ -31,7 +31,7 @@ module Mercenary
31
31
  # Returns the string representation of the subcommands
32
32
  def subcommands_presentation
33
33
  return nil unless command.commands.size > 0
34
- command.commands.values.map(&:summarize).join("\n")
34
+ command.commands.values.uniq.map(&:summarize).join("\n")
35
35
  end
36
36
 
37
37
  # Public: Builds the command header, including the command identity and description
@@ -1,3 +1,3 @@
1
1
  module Mercenary
2
- VERSION = "0.3.1"
2
+ VERSION = "0.3.2"
3
3
  end
@@ -80,6 +80,19 @@ describe(Mercenary::Command) do
80
80
  it "sets the default_command" do
81
81
  expect(with_sub.default_command(:sub_command).name).to eq(:sub_command)
82
82
  end
83
+
84
+ context "with an alias" do
85
+ before(:each) do
86
+ command_with_parent.alias(:an_alias)
87
+ end
88
+ it "shows the alias in the summary" do
89
+ expect(command_with_parent.summarize).to eql(" i_have_parent, an_alias ")
90
+ end
91
+
92
+ it "its names_and_aliases method reports both the name and alias" do
93
+ expect(command_with_parent.names_and_aliases).to eql("i_have_parent, an_alias")
94
+ end
95
+ end
83
96
  end
84
97
 
85
98
  end
@@ -10,6 +10,7 @@ describe(Mercenary::Presenter) do
10
10
  command.description 'Do all the things.'
11
11
  command.option 'one', '-1', '--one', 'The first option'
12
12
  command.option 'two', '-2', '--two', 'The second option'
13
+ command.alias :cmd
13
14
  supercommand.commands[command.name] = command
14
15
  end
15
16
 
@@ -17,8 +18,8 @@ describe(Mercenary::Presenter) do
17
18
  expect(presenter.command_presentation).to eql("script_name subcommand 1.4.2 -- Do all the things.\n\nUsage:\n\n script_name subcommand\n\nOptions:\n -1, --one The first option\n -2, --two The second option")
18
19
  end
19
20
 
20
- it "knows how to present the subcommands" do
21
- expect(described_class.new(supercommand).subcommands_presentation).to eql(" subcommand Do all the things.")
21
+ it "knows how to present the subcommands, without duplicates for aliases" do
22
+ expect(described_class.new(supercommand).subcommands_presentation).to eql(" subcommand, cmd Do all the things.")
22
23
  end
23
24
 
24
25
  it "knows how to present the usage" do
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: mercenary
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.3.1
4
+ version: 0.3.2
5
5
  platform: ruby
6
6
  authors:
7
7
  - Tom Preston-Werner
@@ -9,48 +9,48 @@ authors:
9
9
  autorequire:
10
10
  bindir: bin
11
11
  cert_chain: []
12
- date: 2014-02-21 00:00:00.000000000 Z
12
+ date: 2014-03-19 00:00:00.000000000 Z
13
13
  dependencies:
14
14
  - !ruby/object:Gem::Dependency
15
15
  name: bundler
16
16
  requirement: !ruby/object:Gem::Requirement
17
17
  requirements:
18
- - - ~>
18
+ - - "~>"
19
19
  - !ruby/object:Gem::Version
20
20
  version: '1.3'
21
21
  type: :development
22
22
  prerelease: false
23
23
  version_requirements: !ruby/object:Gem::Requirement
24
24
  requirements:
25
- - - ~>
25
+ - - "~>"
26
26
  - !ruby/object:Gem::Version
27
27
  version: '1.3'
28
28
  - !ruby/object:Gem::Dependency
29
29
  name: rake
30
30
  requirement: !ruby/object:Gem::Requirement
31
31
  requirements:
32
- - - '>='
32
+ - - ">="
33
33
  - !ruby/object:Gem::Version
34
34
  version: '0'
35
35
  type: :development
36
36
  prerelease: false
37
37
  version_requirements: !ruby/object:Gem::Requirement
38
38
  requirements:
39
- - - '>='
39
+ - - ">="
40
40
  - !ruby/object:Gem::Version
41
41
  version: '0'
42
42
  - !ruby/object:Gem::Dependency
43
43
  name: rspec
44
44
  requirement: !ruby/object:Gem::Requirement
45
45
  requirements:
46
- - - ~>
46
+ - - "~>"
47
47
  - !ruby/object:Gem::Version
48
48
  version: '2.14'
49
49
  type: :development
50
50
  prerelease: false
51
51
  version_requirements: !ruby/object:Gem::Requirement
52
52
  requirements:
53
- - - ~>
53
+ - - "~>"
54
54
  - !ruby/object:Gem::Version
55
55
  version: '2.14'
56
56
  description: Lightweight and flexible library for writing command-line apps in Ruby.
@@ -61,9 +61,9 @@ executables: []
61
61
  extensions: []
62
62
  extra_rdoc_files: []
63
63
  files:
64
- - .gitignore
65
- - .rspec
66
- - .travis.yml
64
+ - ".gitignore"
65
+ - ".rspec"
66
+ - ".travis.yml"
67
67
  - Gemfile
68
68
  - History.markdown
69
69
  - LICENSE.txt
@@ -98,17 +98,17 @@ require_paths:
98
98
  - lib
99
99
  required_ruby_version: !ruby/object:Gem::Requirement
100
100
  requirements:
101
- - - '>='
101
+ - - ">="
102
102
  - !ruby/object:Gem::Version
103
103
  version: '0'
104
104
  required_rubygems_version: !ruby/object:Gem::Requirement
105
105
  requirements:
106
- - - '>='
106
+ - - ">="
107
107
  - !ruby/object:Gem::Version
108
108
  version: '0'
109
109
  requirements: []
110
110
  rubyforge_project:
111
- rubygems_version: 2.0.14
111
+ rubygems_version: 2.2.2
112
112
  signing_key:
113
113
  specification_version: 4
114
114
  summary: Lightweight and flexible library for writing command-line apps in Ruby.