mercenary 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3c649528973138a967d8f6cafe92e65ae25a4a95
-  data.tar.gz: 3a7b3477db81d199a956536247c0c0e6bd44fda9
+  metadata.gz: f8c6f00310335bb25ca352dd2172054bad0b3c24
+  data.tar.gz: 3dbc954fbe05ddd60c274f39e59cd19b8ffedc42
 SHA512:
-  metadata.gz: 906d1c04846f347c39bed714774527ccc7173b80e15799a69852368003b3d720da0e3dd0134a6069d7e353fa1c77205ca3e29cec731d0172b44377157b664bee
-  data.tar.gz: 6158035bcfa8721c4494498daba38e346d653484b20d29574bda9913dd8fd2f98cfee754227aa28c806a955a627582e3036b2df99819640784dff354152cee9b
+  metadata.gz: ff3e130d16901f12c6e30f4cbfeb24b7ba589350a785fbfd1386d3e418fdd683fa3771b915a1162334dff36a924d693c2a4b56a556372b2a6c79e493f8070f6b
+  data.tar.gz: 07c5c6bdb22f47880044fc1fb4ba90c122b8eae3c7bce02d95c3a8561eb29541ee5473b5043865b513f3b687749ce8664b51b090186e28ed0e6a4be7634d8caa

data/History.markdown

@@ -8,6 +8,13 @@
 
 ### Development Fixes
 
+## 0.3.2 / 2014-03-18
+
+### Bug Fixes
+
+* Remove duplicate commands from help output; show aliases w/command names
+  (#29)
+
 ## 0.3.1 / 2014-02-21
 
 ### Minor Enhancements

data/README.md

@@ -70,6 +70,177 @@ All commands have the following default options:
 - `-v/--version` - show the program version
 - `-t/--trace` - show the full backtrace when an error occurs
 
+## API
+
+### `Mercenary`
+
+#### `.program`
+
+Creates and executes a program. Accepts two arguments:
+
+- `name` - program name as a Symbol
+- `block` - the specification for the program, passed the program instance as an
+  argument.
+
+Example is above, under the heading [Usage](#usage).
+
+### `Program`
+
+`Program` is a subclass of `Command`, so it has all of the methods documented
+below as well as those for `Command`.
+
+#### `#config`
+
+Fetches the program configuration hash.
+
+### `Command`
+
+#### `#new`
+
+Create a new command. Accepts two arguments:
+
+- `name` - the name of your command, as a symbol
+- `parent` - (optional) the parent Command
+
+#### `#version`
+
+Sets or gets the version of the command. Accepts an optional argument:
+
+- `version` - (optional) the version to set for the command. If present, this
+  becomes the new version for the command and persists.
+
+#### `#syntax`
+
+Sets or gets the syntax of the command. Built on parent syntaxes if a parent
+exists. Accepts one optional argument:
+
+- `syntax` - (optional) the syntax to set for the command. Will inherit from the
+  parent commands or program. Usually in the form of
+  `"command_name <SUBCOMMAND> [OPTIONS]"`
+
+When a parent command exists, say `supercommand`, with syntax set as
+`supercommand <SUBCOMMAND> [OPTIONS]`, the syntax of the command in question
+will be `supercommand command_name <SUBCOMMAND> [OPTIONS]` with both
+`<SUBCOMMAND>` and `[OPTIONS]` stripped out. Any text between `<` and `>` or
+between `[` and `]` will be stripped from parent command syntaxes. The purpose
+of this chaining is to reduce redundancy.
+
+#### `#description`
+
+Sets or gets the description of the command. Accepts one optional argument:
+
+- `desc` - (optional) the description to set for the command. If
+  provided, will override any previous description set for the command.
+
+#### `#default_command`
+
+Sets or gets the default subcommand of the command to execute in the event no
+subcommand is passed during execution. Accepts one optional argument:
+
+- `command_name` - (optional) the `Symbol` name of the subcommand to be
+  executed. Raises an `ArgumentError` if the subcommand doesn't exist.
+  Overwrites previously-set default commands.
+
+#### `#option`
+
+Adds a new option to the command. Accepts many arguments:
+
+- `config_key` - the configuration key that the value of this option maps to.
+- `*options` - all the options, globbed, to be passed to `OptionParser`, namely the
+  switches and the option description. Usually in the format
+  `"-s", "--switch", "Sets the 'switch' flag"`.
+
+Valid option calls:
+
+```ruby
+cmd.option 'config_key', '-c', 'Sets the "config" flag'
+cmd.option 'config_key', '--config', 'Sets the "config" flag'
+cmd.option 'config_key', '-c', '--config', 'Sets the "config" flag.'
+cmd.option 'config_key', '-c FILE', '--config FILE', 'The config file.'
+cmd.option 'config_key', '-c FILE1[,FILE2[,FILE3...]]', '--config FILE1[,FILE2[,FILE3...]]', Array, 'The config files.'
+```
+
+Notice that you can specify either a short switch, a long switch, or both. If
+you want to accept an argument, you have to specify it in the switch strings.
+The class of the argument defaults to `String`, but you can optionally set a
+different class to create, e.g. `Array`, if you are expecting a particular class
+in your code from this option's value. The description is also optional, but
+it's highly recommended to include a description.
+
+#### `#alias` 
+
+Specifies an alias for this command such that the alias may be used in place of
+the command during execution. Accepts one argument:
+
+- `cmd_name` - the alias name for this command as a `Symbol`
+
+Example:
+
+```ruby
+cmd.alias(:my_alias)
+# Now `cmd` is now also executable via "my_alias"
+```
+
+#### `#action`
+
+Specifies a block to be executed in the event the command is specified at
+runtime. The block is given two arguments:
+
+- `args` - the non-switch arguments given from the command-line
+- `options` - the options hash built via the switches passed
+
+**Note that actions are additive**, meaning any new call to `#action` will
+result in another action to be executed at runtime. Actions will be executed in
+the order they are specified in.
+
+Example:
+
+```ruby
+cmd.action do |args, options|
+  # do something!
+end
+```
+
+#### `#logger`
+
+Access the logger for this command. Useful for outputting information to STDOUT.
+Accepts one optional argument:
+
+- `level` - (optional) the severity threshold at which to begin logging. Uses
+  Ruby's built-in
+  [`Logger`](http://www.ruby-doc.org/stdlib-2.1.0/libdoc/logger/rdoc/Logger.html)
+  levels.
+
+Log level defaults to `Logger::INFO`.
+
+Examples:
+
+```ruby
+cmd.logger(Logger::DEBUG)
+cmd.logger.debug "My debug message."
+cmd.logger.info "My informative message."
+cmd.logger.warn "ACHTUNG!!"
+cmd.logger.error "Something terrible has happened."
+cmd.logger.fatal "I can't continue doing what I'm doing."
+```
+
+#### `#command`
+
+Creates a new subcommand for the current command. Accepts two arguments:
+
+- `cmd_name` - the command name, as a Symbol
+- `block` -  the specification of the subcommand in a block
+
+Example:
+
+```ruby
+my_command.command(:my_subcommand) do |subcmd|
+  subcmd.description 'My subcommand'
+  subcmd.syntax 'my_subcommand [OPTIONS]'
+  # ...
+end
+```
+
 ## Contributing
 
 1. Fork it

data/examples/help_dialogue.rb

@@ -19,6 +19,7 @@ Mercenary.program(:help_dialogue) do |p|
     c.syntax 'some_subcommand <subcommand> [options]'
     c.description 'Some subcommand to do something'
     c.option 'an_option', '-o', '--option', 'Some option'
+    c.alias(:blah)
 
     c.command(:yet_another_sub) do |f|
       f.syntax 'yet_another_sub [options]'

data/lib/mercenary/command.rb

@@ -9,6 +9,7 @@ module Mercenary
     attr_reader :map
     attr_accessor :parent
     attr_reader :trace
+    attr_reader :aliases
 
     # Public: Creates a new Command
     #
@@ -25,6 +26,7 @@ module Mercenary
       @map      = {}
       @parent   = parent
       @trace    = false
+      @aliases  = []
     end
 
     # Public: Sets or gets the command version
@@ -113,6 +115,7 @@ module Mercenary
     # Returns nothing
     def alias(cmd_name)
       logger.debug "adding alias to parent for self: '#{cmd_name}'"
+      aliases << cmd_name
       @parent.commands[cmd_name] = self
     end
 
@@ -253,11 +256,18 @@ module Mercenary
       the_name.join(" ")
     end
 
+    # Public: Return all the names and aliases for this command.
+    #
+    # Returns a comma-separated String list of the name followed by its aliases
+    def names_and_aliases
+      ([name.to_s] + aliases).compact.join(", ")
+    end
+
     # Public: Build a string containing a summary of the command
     #
     # Returns a one-line summary of the command.
     def summarize
-      "  #{name.to_s.ljust(20)}  #{description}"
+      "  #{names_and_aliases.ljust(20)}  #{description}"
     end
 
     # Public: Build a string containing the command name, options and any subcommands

data/lib/mercenary/presenter.rb

@@ -31,7 +31,7 @@ module Mercenary
     # Returns the string representation of the subcommands
     def subcommands_presentation
       return nil unless command.commands.size > 0
-      command.commands.values.map(&:summarize).join("\n")
+      command.commands.values.uniq.map(&:summarize).join("\n")
     end
 
     # Public: Builds the command header, including the command identity and description

data/lib/mercenary/version.rb

@@ -1,3 +1,3 @@
 module Mercenary
-  VERSION = "0.3.1"
+  VERSION = "0.3.2"
 end

data/spec/command_spec.rb

@@ -80,6 +80,19 @@ describe(Mercenary::Command) do
     it "sets the default_command" do
       expect(with_sub.default_command(:sub_command).name).to eq(:sub_command)
     end
+
+    context "with an alias" do
+      before(:each) do
+        command_with_parent.alias(:an_alias)
+      end
+      it "shows the alias in the summary" do
+        expect(command_with_parent.summarize).to eql("  i_have_parent, an_alias  ")
+      end
+
+      it "its names_and_aliases method reports both the name and alias" do
+        expect(command_with_parent.names_and_aliases).to eql("i_have_parent, an_alias")
+      end
+    end
   end
 
 end

data/spec/presenter_spec.rb

@@ -10,6 +10,7 @@ describe(Mercenary::Presenter) do
     command.description 'Do all the things.'
     command.option 'one', '-1', '--one', 'The first option'
     command.option 'two', '-2', '--two', 'The second option'
+    command.alias :cmd
     supercommand.commands[command.name] = command
   end
 
@@ -17,8 +18,8 @@ describe(Mercenary::Presenter) do
     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")
   end
 
-  it "knows how to present the subcommands" do
-    expect(described_class.new(supercommand).subcommands_presentation).to eql("  subcommand            Do all the things.")
+  it "knows how to present the subcommands, without duplicates for aliases" do
+    expect(described_class.new(supercommand).subcommands_presentation).to eql("  subcommand, cmd       Do all the things.")
   end
 
   it "knows how to present the usage" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mercenary
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Tom Preston-Werner
@@ -9,48 +9,48 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-02-21 00:00:00.000000000 Z
+date: 2014-03-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
 description: Lightweight and flexible library for writing command-line apps in Ruby.
@@ -61,9 +61,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - History.markdown
 - LICENSE.txt
@@ -98,17 +98,17 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Lightweight and flexible library for writing command-line apps in Ruby.