command_lion 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 91313ee91c191e8a8f0b492a5b6f0f603e3ae8b2
-  data.tar.gz: 18bac0196033a11566c923b933b2f47d161575ac
+  metadata.gz: e1a46eb35cac2757a52188adce29bcb41c03a26c
+  data.tar.gz: f38a9d1c5559252a4232a5ec0d221e6f73708e55
 SHA512:
-  metadata.gz: 14ef85bc5916f07d98adc9a553f623acfdcabdc51b5ada2eaeed1758eda824b8e518a6d2b3db36010a04219921d2ef05d1df1915cf2196f612c2152070963b7a
-  data.tar.gz: 467f4cefb3d55ec0d0990b10bbb01e54a223ba84fad25e9ae120a69178ac474ab4a0c32fcf0fbb1e7f93699439adc54fdbcc3724906ce431b3c45b5b94634c78
+  metadata.gz: 8a2c13b8007fdeff85b9bbeadcc1157deb5008e5087910b3b0c6216d0c993e25d264c2583204f968f843e4c0d03f89dc39c5f3b75c8e357f837977656090753c
+  data.tar.gz: 1a8513c041c2097d2fce2bb393f654aa76a718860640404af10ef25e0b1bc31ec9b7352076648f699ea008783ef9e3e5451d7349d6386c398bb22e34803cade1

data/README.md

@@ -19,8 +19,14 @@ CommandLion::App.run do
 
   command :hello do
     description "A simple command to say hello!"
+    
     type :string
-    flag "hello"
+
+    flags do
+      short "-h"
+      long  "--hello" 
+    end
+
     default "world"
 
     action do

data/lib/command_lion/app.rb

@@ -1,6 +1,23 @@
 module CommandLion
 
-
+  # The App class provides what can be considered the "main" function for the a Command Lion application.
+  # 
+  # The App class is primarily used in one of two ways:
+  #
+  # == Building Block
+  # To build an application using the DSL, but not run it right away, the build method block is available.
+  #   app = CommandLion::App.build do
+  #     # ...
+  #   end
+  #
+  #   app.run!
+  #
+  # == Run Block
+  # To build, parse, and run everything in one concise block, the run method block is available.
+  #   CommandLion::App.run do
+  #     # ...
+  #   end
+  #
   # == DSL Keywords:
   # name::
   #   The name of your application. This is how your application would be referenced in conversation.
@@ -179,20 +196,21 @@ module CommandLion
 
     # An application usually has multiple commands.
     #
-    # app = CommandLion::App.build
-    #   # meta information
-    #   
-    #   command :example1 do
-    #     # more code
-    #   end
+    # == Example
+    #   app = CommandLion::App.build
+    #     # meta information
+    #     
+    #     command :example1 do
+    #       # more code
+    #     end
     #
-    #   command :example2 do
-    #     # more code
+    #     command :example2 do
+    #       # more code
+    #     end
     #   end
-    # end
     #
-    # app.commands.map(&:name)
-    # # => [:example1, :example2]
+    #   app.commands.map(&:name)
+    #   # => [:example1, :example2]
     def command(index, &block)
       if index.is_a? Command
         cmd = index
@@ -227,22 +245,26 @@ module CommandLion
       cmd
     end
 
-    # Plugin a command.
+    # Plugin a command that's probably been built outside of the application's run or build block.
+    # This is helpful for sharing or reusing commands in applications.
+    # @param command [Command] 
     def plugin(command)
       command(command)
     end
 
-    # Direct access to the various flags an application has.
+    # Direct access to the various flags an application has. Helpfulp for debugging.
     def flags
       @flags
     end
 
-    # Direct access to the various commands an application has.
+    # Direct access to the various commands an application has. Helpful for debugging.
     def commands
       @commands
     end
 
     # Parse arguments off of ARGV.
+    #
+    # @TODO Re-visit this.
     def parse
       @commands.each do |_, cmd|
         if cmd.flags?
@@ -266,6 +288,7 @@ module CommandLion
     end
 
     # Parse a given command with its 
+    # @TODO Re-visit this.
     def parse_cmd(cmd, flags)
       if cmd.flags?
         args = Raw.arguments_to(cmd.flags.short, flags)
@@ -344,12 +367,15 @@ module CommandLion
       nil
     end
 
+    # @TODO Re-visit this.
     def run!
       parse do |cmd|
         cmd.action.call
       end 
     end
 
+    # Run the application if the file is the main file being run.
+    # It's almost kind of narcisitc, if you think about it.
     if __FILE__== $0
       run!
     end

data/lib/command_lion/base.rb

@@ -1,5 +1,7 @@
 module CommandLion
 
+  # To encapsulate some of the common patterns within Command Lion, there is a Base
+  # class which both the App and Command class inhereit from. 
   class Base
 
     class << self

data/lib/command_lion/command.rb

@@ -1,54 +1,282 @@
 module CommandLion
 
-
-  # The Command class is a fundatmental class for Command Lion. 
-  #
-  # What's kind of nice about it -- at least, I hope -- is that it's actually
-  # a very simple class. The `Option` class for Command Lion literally just inhereits from
-  # this class so that a Command's options has a specfic namespace, but basically works
-  # identically in every other way. This allows you to work out the options for your command
-  # in a very simple node-leaf representation. This allows you to naturally work your way down
-  # and up the tree as nessecary.
-  #
-  # Because most of the "keywords" for Command Lion, which are simply ruby methods that behave
-  # in a particular way for the Command Lion DSL.
-  #
-  # == DSL Keywords:
-  # description::
-  #   To provide further context for your application's existence, it's fairly nice to have a description.
-  #   Like, the usage statement, this can be as complex or as simple as you would like. It isn't required either.
+  # Every command or option for Command Lion is built on the Command class.
+  #
+  # A Command is typically built using the DSL provided within a build method block:
+  # == ⚙️  Build Block
+  #   cmd = CommandLion::Command.build do
+  #     # ...
+  #   end
+  # This is used under the hood within an Application's DSL run or block:
+  # == ⚙️  Application Build Block
+  #   app = CommandLion::App.build do
+  #     command :example_index do
+  #       # ...
+  #     end
+  #   end
+  #
+  # The DSL keywords are simple methods provided for any Command object and can be accessed
+  # or modified outside of the DSL building block itself to, for example, query if it exists.
+  #
+  # == 🗣  DSL 
+  # Command Lion's DSL is meant to be as flexible as possible without being too compelx.
+  # 
+  # ==⚡️  Example
+  #   cmd = CommandLion::Command.build do
+  #     index :example
+  #     flags do
+  #       short "-e"
+  #       long  "--example"
+  #     end
+  #     type :strings
+  #     default ["Jim", "Pam", "Dwight", "Michael"]
+  #     before do
+  #       unless arguments.count > 2
+  #         abort "Must provide more than two arguments!"
+  #       end
+  #     end
+  #     action do
+  #       arguments.each do |argument|
+  #         puts "Hello #{argument}!"
+  #       end
+  #     end
+  #     after do
+  #       exit 0
+  #     end
+  #   end
+  #
+  # == Keywords 
+  # 🔑  description::
+  #   To provide further context for your command's existence, it's fairly nice 
+  #   to have a description.
   #   
   #   == Example
-  #     app = CommandLion::Command.build do
+  #     cmd = CommandLion::Command.build do
   #       description "Example"
   #     end
   #     
-  #     app.description?
+  #     cmd.description?
   #     # => true
   #
-  #     app.description = "Changed"
+  #     cmd.description = "Changed"
   #     # => "Changed"
   #
-  #     app.description
+  #     cmd.description
   #     # => Changed
-  # threaded::
+  # 🔑  type::
+  #   A command may require a specific argument from the command-line. The type
+  #   of argument(s) that the command utilizies can be specified with this keyword.
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       type :string
+  #     end
+  #     
+  #     cmd.type?
+  #     # => true
+  #
+  #     cmd.type = :strings
+  #     # => :strings
+  #
+  #     cmd.type
+  #     # => :strings
+  # 🔑  default::
+  #   To specify a command's default arguments, the default keyword can be used.
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       default "example"
+  #     end
+  #     
+  #     cmd.default?
+  #     # => true
+  #
+  #     cmd.default = "EXAMPLE"
+  #     # => "EXAMPLE"
+  #
+  #     cmd.default
+  #     # => "EXAMPLE"
+  #
+  #     cmd.argument
+  #     # => "EXAMPLE"
+  # 🔑  delimiter::
+  #   In the case of multiple command-line arguments, a custom delimter can be used
+  #   to help split up the arguments. Command Lion uses the space betwen arguments as the
+  #   default delimter.
+  #
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       delimter ","
+  #     end
+  #     
+  #     cmd.delimter?
+  #     # => true
+  #
+  #     cmd.delimter = ":"
+  #     # => ":"
+  #
+  #     cmd.delimter
+  #     # => : 
+  # 🔑  flag::
+  #   If you'd like for one specfic flag to be used for the command, then this keyword is for you!
+  #   
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       flag "example"
+  #     end
+  #     
+  #     cmd.flag?
+  #     # => true
+  #
+  #     cmd.flag = "EXAMPLE"
+  #     # => "EXAMPLE"
+  #
+  #     cmd.flag 
+  #     # => "EXAMPLE"
+  # 🔑  flags::
+  #   The flags keywords can be used two specify the short and long flags option for a command.
+  #
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       flags do
+  #         short "-e"
+  #         long  "--example
+  #       end
+  #     end
+  #     
+  #     cmd.flags?
+  #     # => true
+  #
+  #     cmd.flags.short? 
+  #     # => true
+  #
+  #     cmd.flags.long? 
+  #     # => true
+  #
+  #     cmd.flags.short = "-E" 
+  #     # => "-E"
+  #
+  #     cmd.flags.long = "--EXAMPLE" 
+  #     # => "--EXAMPLE"
+  # 
+  #     cmd.flags.long
+  #     # => "--EXAMPLE"
+  #
+  #     cmd.flags.short
+  #     # => "-E"
+  # 🔑  threaded::
   #   To have your command spawn a thread and have the action block
   #   for your command run in its own background thread. 
   #
   #   == Example
-  #     app = CommandLion::Command.build do
+  #     cmd = CommandLion::Command.build do
   #       description "Example"
   #     end
   #     
-  #     app.description?
+  #     cmd.description?
   #     # => true
   #
-  #     app.description = "Changed"
+  #     cmd.description = "Changed"
   #     # => "Changed"
   #
-  #     app.description
+  #     cmd.description
   #     # => Changed
+  # 🔑  action::
+  #   What do you want a command to do when it is used? The action keyword can be used
+  #   to capture the block you'd like to run when the command is used.
+  #
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       action do
+  #         puts "Hello World!"
+  #       end
+  #     end
+  #     
+  #     cmd.action?
+  #     # => true
+  #
+  #     cmd.action
+  #     # => #<Proc:...>
+  #
+  #     cmd.action.call
+  #     # => Hello World! .. to STDOUT
+  # 🔑  before::
+  #   Before the action block is called, you can specify anouther block to be used beforehand
+  #   which can be used to help setup or do some custom error checking.
+  #
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       before do
+  #         abort "Not on Mondays!" Time.now.monday?
+  #       end
+  #       action do
+  #         puts "Hello World!"
+  #       end
+  #     end
+  #     
+  #     cmd.before?
+  #     # => true
+  #
+  #     cmd.before
+  #     # => #<Proc:...>
+  #
+  #     cmd.before.call
+  #     # aborts application if it's Monday
+  # 🔑  after::
+  #   After the action block has been called and completed, anouther optional block
+  #   can be used within the block given in the after keyword. This can be used for all sorts
+  #   of nifty things: from stopping the application from moving on, to logging, to whatever else.
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       action do
+  #         puts "Hello World!"
+  #       end
+  #       after do
+  #         exit 0 
+  #       end
+  #     end
+  #     
+  #     cmd.after?
+  #     # => true
+  #
+  #     cmd.after
+  #     # => #<Proc:...>
+  #
+  #     cmd.after.call
+  #     # exits application with successful status code
+  # 🔑  index::
+  #   A command's index should be unique. It is used to used to accesses the command amongst other 
+  #   commands when used within an application. However, this keyword usually isn't used unless being utilized
+  #   when using Command Lion's plugin system. 
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       index :example
+  #     end
+  #     
+  #     cmd.index?
+  #     # => :example
+  #
+  #     cmd.index
+  #     # => :example
+  # 🔑  option::
+  #   a command may have mutiple sub commands or options associated with it. these effectively
+  #   work exactly like any other command, but are just started as a leaf under the paren't command's options.
+  #   == Example
+  #     cmd = CommandLion::Command.build do
+  #       # ...
+  #       option :example do
+  #         action do
+  #           puts "hello world!"
+  #         end
+  #       end
+  #     end
+  #     
+  #     cmd.options?
+  #     # => true
+  #
+  #     cmd.options[:example]
+  #     # => #<proc:...>
   #
+  #     cmd.after.call
+  #     # exits the application with successful status code
   #
   class Command < Base
     

data/lib/command_lion/flags.rb

@@ -1,5 +1,33 @@
 module CommandLion
 
+  # The way a user is able to call or access a command or option for
+  # a command-line application is by passing their flags when the application
+  # is run at the command-line.
+  #
+  # == 🗣  DSL 
+  # The flags DSL works three different ways.
+  # 
+  # == Index as Flag
+  #   app = CommandLion::Command.build do
+  #     command :hello do
+  #       # just use the index as the flag
+  #     end
+  #   end
+  # == One Flag
+  #   app = CommandLion::Command.build do
+  #     command :hello do
+  #       flag "--hello"
+  #     end
+  #   end
+  # == Short & Long Flags
+  #   app = CommandLion::Command.build do
+  #     command :hello do
+  #       flags do
+  #         short "-e"
+  #         long  "--example"
+  #       end
+  #     end
+  #   end
   class Flags < Base
     simple_attrs :short, :long
   end

data/lib/command_lion/option.rb

@@ -1,3 +1,21 @@
 module CommandLion
+
+  # The Option class is a direct sub-class of the Command class. In pretty much
+  # every way it is just a command under the hood. However, instead of being indexed
+  # in an application's commands index, it will be available in whatever command's
+  # options index.
+  #
+  # == Example
+  #
+  #   app = CommandLion::App.build do
+  #     command :example_command do
+  #         # ...
+  #       option :example_option do
+  #         # ...
+  #       end
+  #     end
+  #   end
+  #
+  #   app.commands[:example_command].options[:example_option]
   class Option < Command; end
 end

data/lib/command_lion/version.rb

@@ -1,3 +1,3 @@
 module CommandLion
-  VERSION = "1.0.1"
+  VERSION = "1.0.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: command_lion
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Kent 'picat' Gruber
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-08-30 00:00:00.000000000 Z
+date: 2017-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler