optplus 0.0.8

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDU0ODg5OTM1ZjZlNjQ3ZWM4NzA0NGNmYTRhOWY4NWYxYzI0NzJhZg==
+  data.tar.gz: !binary |-
+    NDMzYjM4Y2EyZmQ3MDU4N2RmNjA1MDQ0YTkyM2M4MjdiYTRkMTIxZg==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    NjRmMGU3Zjg3ZjJmOGI3MDE1MDJlODBlM2U5NWQ1NjA3ZjQyYzBmODg3OWM5
+    MzA5YTE1ODRlMDNmMTdmYmNjYjhjNmQzNmRmZmRhMDM3YmZkMzJhOWQ5MGFj
+    ZGM0Y2FkNmJjOTRlYjkwN2ZmOGE2MDY5MzkyYzMwZGUzZTY1YzA=
+  data.tar.gz: !binary |-
+    YWZkNDdlMzBmNzI5OTMwOTc4MGFlNDU5Njg4NGViNDE0Njk0ZDFhOTcwMmU3
+    NDQ4ZDI1NTFmMjQ3ODQzODQ5MmM2NzJlZmYyZTZmMjVmOGZlOWFlMTc5YTUz
+    MDUyYWFkYzI2MTI1MzUwOWQ0MzRiNGE4MzY0ZDZiOWM2ZmE5NWI=

data/Bugs.rdoc

@@ -0,0 +1,5 @@
+== Outstanding Bugs and Change Requests for Optplus
+
+[30-Aug-2013]
+
+  * Need to implement the project!

data/Gemfile

@@ -0,0 +1,3 @@
+# Gemfile for a Jerbil Service
+
+gem 'colored'

data/History.txt

@@ -0,0 +1,39 @@
+# @markup rdoc
+# @title Change History
+
+== History
+[optplus-0.0.8 13-Sep-2013]
+
+  Release Candidate with nesting etc.
+
+[optplus-0.0.7 11-Sep-2013]
+
+  Add flag to actions that have their own help
+
+[optplus-0.0.6 11-Sep-2013]
+
+  Fix typo in hasty release
+
+[optplus-0.0.5 11-Sep-2013]
+
+  Add a general error handler to the run! method to make it easier to handle argument errors
+
+[optplus-0.0.4 11-Sep-2013]
+
+  Add a couple of next_argument variants for defaults and exceptions
+
+[optplus-0.0.3 03-Sep-2013]
+
+  Fix Gemfile to remove unwanted and cyclic dependencies
+
+[optplus-0.0.2 03-Sep-2013]
+
+  Include Nested Parser
+
+[optplus-0.0.1 01-Sep-2013]
+
+  Initial release
+
+[optplus-0.0.0 30-Aug-2013]
+
+  New application generated

data/Intro.txt

@@ -0,0 +1,3 @@
+Wraps Optparser into a class to enable thor-like scripting with a few meta-methods
+and a built-in command or action dispatcher. Its much smaller than Thor and aimed
+at saving time when scripting with Optparser.

data/LICENCE.rdoc

@@ -0,0 +1,159 @@
+= LICENCE
+
+This software is licensed for use under the Open Software Licence v. 3.0
+The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+and below. Under the terms of this licence, all derivative works
+must themselves be licensed under the Open Software Licence v. 3.0
+
+Open Source Initiative OSI - The Open Software Licence 3.0:Licensing
+[OSI Approved Licence]
+Open Software Licence ("OSL") v. 3.0
+
+This Open Software Licence (the "Licence") applies to any original work of authorship
+(the "Original Work") whose owner (the "Licensor") has placed the following licensing
+notice adjacent to the copyright notice for the Original Work:
+
+Licensed under the Open Software Licence version 3.0
+
+1) Grant of Copyright Licence. Licensor grants You a worldwide, royalty-free, non-exclusive,
+sublicensable license, for the duration of the copyright, to do the following:
+
+a) to reproduce the Original Work in copies, either alone or as part of a collective work;
+
+b) to translate, adapt, alter, transform, modify, or arrange the Original Work, thereby
+creating derivative works ("Derivative Works") based upon the Original Work;
+
+c) to distribute or communicate copies of the Original Work and Derivative Works to
+the public, with the proviso that copies of Original Work or Derivative Works that
+You distribute or communicate shall be licensed under this Open Software Licence;
+
+d) to perform the Original Work publicly; and
+
+e) to display the Original Work publicly.
+
+2) Grant of Patent Licence. Licensor grants You a worldwide, royalty-free, non-exclusive,
+sublicensable license, under patent claims owned or controlled by the Licensor that are
+embodied in the Original Work as furnished by the Licensor, for the duration of the
+patents, to make, use, sell, offer for sale, have made, and import the Original Work
+and Derivative Works.
+
+3) Grant of Source Code Licence. The term "Source Code" means the preferred form of
+the Original Work for making modifications to it and all available documentation
+describing how to modify the Original Work. Licensor agrees to provide a machine-readable
+copy of the Source Code of the Original Work along with each copy of the Original Work
+that Licensor distributes. Licensor reserves the right to satisfy this obligation by
+placing a machine-readable copy of the Source Code in an information repository reasonably
+calculated to permit inexpensive and convenient access by You for as long as Licensor
+continues to distribute the Original Work.
+
+4) Exclusions From Licence Grant. Neither the names of Licensor, nor the names of
+any contributors to the Original Work, nor any of their trademarks or service marks,
+may be used to endorse or promote products derived from this Original Work without
+express prior permission of the Licensor. Except as expressly stated herein, nothing
+in this Licence grants any license to Licensor's trademarks, copyrights, patents,
+trade secrets or any other intellectual property. No patent license is granted to
+make, use, sell, offer for sale, have made, or import embodiments of any patent claims
+other than the licensed claims defined in Section 2. No license is granted to the
+trademarks of Licensor even if such marks are included in the Original Work. Nothing
+in this Licence shall be interpreted to prohibit Licensor from licensing under terms
+different from this Licence any Original Work that Licensor otherwise would have a
+right to license.
+
+5) External Deployment. The term "External Deployment" means the use, distribution,
+or communication of the Original Work or Derivative Works in any way such that the
+Original Work or Derivative Works may be used by anyone other than You, whether those
+works are distributed or communicated to those persons or made available as an application
+intended for use over a network. As an express condition for the grants of license hereunder,
+You must treat any External Deployment by You of the Original Work or a Derivative Work
+as a distribution under section 1(c).
+
+6) Attribution Rights. You must retain, in the Source Code of any Derivative Works
+that You create, all copyright, patent, or trademark notices from the Source Code of
+the Original Work, as well as any notices of licensing and any descriptive text identified
+therein as an "Attribution Notice." You must cause the Source Code for any Derivative Works
+that You create to carry a prominent Attribution Notice reasonably calculated to inform
+recipients that You have modified the Original Work.
+
+7) Warranty of Provenance and Disclaimer of Warranty. Licensor warrants that the copyright
+in and to the Original Work and the patent rights granted herein by Licensor are owned by
+the Licensor or are sublicensed to You under the terms of this Licence with the permission
+of the contributor(s) of those copyrights and patent rights. Except as expressly stated in
+the immediately preceding sentence, the Original Work is provided under this Licence on an
+"AS IS" BASIS and WITHOUT WARRANTY, either express or implied, including, without limitation,
+the warranties of non-infringement, merchantability or fitness for a particular purpose.
+THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS WITH YOU. This DISCLAIMER OF WARRANTY
+constitutes an essential part of this Licence. No license to the Original Work is granted
+by this Licence except under this disclaimer.
+
+8) Limitation of Liability. Under no circumstances and under no legal theory, whether
+in tort (including negligence), contract, or otherwise, shall the Licensor be liable
+to anyone for any indirect, special, incidental, or consequential damages of any character
+arising as a result of this Licence or the use of the Original Work including, without
+limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction,
+or any and all other commercial damages or losses. This limitation of liability shall not
+apply to the extent applicable law prohibits such limitation.
+
+9) Acceptance and Termination. If, at any time, You expressly assented to this Licence,
+that assent indicates your clear and irrevocable acceptance of this Licence and all of its
+terms and conditions. If You distribute or communicate copies of the Original Work or a
+Derivative Work, You must make a reasonable effort under the circumstances to obtain the
+express assent of recipients to the terms of this Licence. This Licence conditions your
+rights to undertake the activities listed in Section 1, including your right to create
+Derivative Works based upon the Original Work, and doing so without honoring these
+terms and conditions is prohibited by copyright law and international treaty. Nothing
+in this Licence is intended to affect copyright exceptions and limitations (including
+"fair use" or "fair dealing"). This Licence shall terminate immediately and You may no
+longer exercise any of the rights granted to You by this Licence upon your failure to
+honor the conditions in Section 1(c).
+
+10) Termination for Patent Action. This Licence shall terminate automatically and
+You may no longer exercise any of the rights granted to You by this Licence as of
+the date You commence an action, including a cross-claim or counterclaim, against
+Licensor or any licensee alleging that the Original Work infringes a patent. This
+termination provision shall not apply for an action alleging patent infringement
+by combinations of the Original Work with other software or hardware.
+
+11) Jurisdiction, Venue and Governing Law. Any action or suit relating to this Licence
+may be brought only in the courts of a jurisdiction wherein the Licensor resides or
+in which Licensor conducts its primary business, and under the laws of that jurisdiction
+excluding its conflict-of-law provisions. The application of the United Nations Convention
+on Contracts for the International Sale of Goods is expressly excluded. Any use of
+the Original Work outside the scope of this Licence or after its termination shall be
+subject to the requirements and penalties of copyright or patent law in the appropriate
+jurisdiction. This section shall survive the termination of this Licence.
+
+12) Attorneys' Fees. In any action to enforce the terms of this Licence or seeking
+damages relating thereto, the prevailing party shall be entitled to recover its costs
+and expenses, including, without limitation, reasonable attorneys' fees and costs
+incurred in connection with such action, including any appeal of such action. This
+section shall survive the termination of this Licence.
+
+13) Miscellaneous. If any provision of this Licence is held to be unenforceable,
+such provision shall be reformed only to the extent necessary to make it enforceable.
+
+14) Definition of "You" in This Licence. "You" throughout this Licence, whether in
+upper or lower case, means an individual or a legal entity exercising rights under,
+and complying with all of the terms of, this Licence. For legal entities, "You" includes
+any entity that controls, is controlled by, or is under common control with you. For
+purposes of this definition, "control" means (i) the power, direct or indirect, to cause
+the direction or management of such entity, whether by contract or otherwise, or (ii)
+ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+ownership of such entity.
+
+15) Right to Use. You may use the Original Work in all ways not otherwise restricted or
+conditioned by this Licence or by law, and Licensor promises not to interfere with or be
+responsible for such uses by You.
+
+16) Modification of This Licence. This Licence is Copyright © 2005 Lawrence Rosen.
+Permission is granted to copy, distribute, or communicate this Licence without modification.
+Nothing in this Licence permits You to modify this Licence as applied to the Original Work
+or to Derivative Works. However, You may modify the text of this Licence and copy, distribute
+or communicate your modified version (the "Modified Licence") and apply it to other original
+works of authorship subject to the following conditions: (i) You may not indicate in any way
+that your Modified Licence is the "Open Software Licence" or "OSL" and you may not use those
+names in the name of your Modified Licence; (ii) You must replace the notice specified in the
+first paragraph above with the notice "Licensed under <insert your license name here>" or
+with a notice of your own that is not confusingly similar to the notice in this Licence;
+and (iii) You may not claim that your original works are open source software unless your
+Modified Licence has been approved by Open Source Initiative (OSI) and You comply with
+its license review and certification process.

data/README.md

@@ -0,0 +1,296 @@
+# OPTPLUS
+
+Optplus is a wrapper around optparse aimed at making optparse-based scripts easier to write and
+offering enhanced functions for little extra effort. It has a Thor-like structure but is
+strictly optparse based with none of the complications that thor presents.
+
+**GitHub:** [https://github.com/osburn-sharp/optplus](https://github.com/osburn-sharp/optplus)
+
+**RubyDoc:** [http://rubydoc.info/github/osburn-sharp/optplus/frames](http://rubydoc.info/github/osburn-sharp/optplus/frames)
+
+**RubyGems:** [https://rubygems.org/gems/optplus](https://rubygems.org/gems/optplus)
+
+## Installation
+
+Optplus is available as a gem. To install:
+
+    # gem install optplus
+    
+To use optplus, just require it. See below for examples.
+
+## Getting Started
+
+To use Optplus, first define a class that inherits from {Optplus::Parser}, add an options
+method to include your own options (Optplus defines a few for you) and then define some
+action methods to do the work. After the class definition use the {Optplus::Parser.run!}
+class method to run the parser. 
+
+### Simple Example
+
+Here is a simple example:
+
+    require 'optplus'
+    
+    class Mycli < Optplus::Parser
+    
+      usage "actions [params] [options]"
+      
+      description "a brief description",
+        "that can extend over multiple lines"
+        
+      def options(opts)
+      
+        # define your own options just like with optparse
+        opts.on('-a', '--all', 'show all the items') do
+          # optplus provides a convenient way to set and get options
+          set_option :all
+        end
+        
+      end
+      
+      describe :show, 'show all of the items that match the string given'
+      def show
+        matches = next_argument_or_error('You must provide a string to match')
+        
+        # do the stuff
+        
+      end
+      help :show, "A more details description of the show action",
+        "that can again spread over multiple lines",
+        "and is displayed when the user types mycli show -h"
+        
+    end
+    
+    Mycli.run! # don't forget!
+    
+Optplus allows minimal unambiguous abbreviations for actions using the Array#abbrev
+method. Single letters will not be recognised but two or more are generally enough.
+It is worth planning your action names to enable convenient abbreviations to be used.
+
+## General Description
+
+Optplus is nothing more than a convenient wrapper around Optparse aimed at accelerating
+the writing of useful scripts that work in the style of actions, parameters and options.
+It uses Optparse#permute to evaluate the command line so that options can be scattered
+anywhere on the command line and will be evaluated all in the same level. It also
+provides the ability to nest a parser so that actions can have sub-actions - see below
+for further details.
+
+Using Optplus involves the following:
+
+* define a class that inherits from {Optplus::Parser}
+
+* specify some preamble help information using the following meta-methods
+
+> **usage** -- define the order of any actions, parameters or options to display in
+  the usage line. Does not need "Usage etc" cos this is provided automatically
+
+> **description** -- multiline description displayed at the top of the help text. If
+  you want more details, use the readme action.
+  
+* define a **#before_all** method if you need something to be done before any optparse
+  methods or anything else. It expects no parameters.
+
+* define an **#options** method to add your own option switches in the same manner as Optparse.
+  You must provide a parameter to pass in the optparse object (e.g. opts).
+  There are some convenience methods that can also be called with the optparse object
+  to add some common option switches. See below for more details.
+  
+* define a **#before_actions** method -- this method is called after the optplus parser has
+  been evaluated but before any actions are executed. Use this to set up common objects
+  for these actions. It expects no parameters.
+  
+* For each action you need to define the following
+  
+> **describe** -- links an action (as a symbol) to a one line description.
+
+> **action_ method** -- for the action itself, having the same name as the symbol above
+
+> **help** - links the action to multi-line help text that will be displayed when
+  the --help option is used with the action
+
+* And finally, if you need to tidy up afterwards you can define an after_actions
+  method.
+
+Within an action method you can obtain parameters using the {Optplus::Parser#next_argument}
+method. This will return nil if there is no next argument, but to make life a little easier
+you can use {Optplus::Parser#next_argument_or} to define a default if there is no argument, or
+{Optplus::Parser#next_argument_or_error} to specify an error message if there is no argument.
+The latter will raise an exception that is trapped by {Optplus::Parser.run!} to display
+as a sensible error message.
+
+Note that Optparser may raise a number of exceptions, for example where a type is defined
+but the wrong type entered, and Optplus will trap these and display appropriate error 
+messages when this occurs so you don't have to worry about them.
+
+There are a couple of example scripts that can be used to see what Optplus does.
+See Tests below.
+
+### Default and Extra Option Switches
+
+Optplus provides a -h or --help option switch by default. Two other option switches can be added
+simply by calling helper methods:
+
+    debug_option(opts) # add a debug switch (-D, --debug)
+    
+    puts "In debug mode" if get_option(:debug)
+    
+    verbose_option(opts) # add a verbose switch (-V, --verbose)
+    
+    puts "In verbose mode" if get_option(:verbose)
+    
+You can change the short-form switch by adding a different one:
+
+    debug_option(opts, '-d') 
+
+### Options helpers
+
+To make things a little easier there are a couple of methods to set and read local
+options:
+
+**{Optplus::Parser#set_option}** that can be used to set an option with the given :key
+  to either true (if no object is passed as the second parameter) or to the given object.
+  
+**{Optplus::Parser#get_option}** returns the value of the set option for the given :key
+
+**{Optplus::Parser#option?}** returns true if the given option has been defined
+
+For example:
+
+    set_option :all
+    set_option :config, path
+    set_option :environment, env
+    
+    if option? :all then
+      # do something
+      params = get_config(get_option(:config))
+    end
+    
+You can always define instance variables if you prefer.
+
+### Handling Errors
+
+Optplus should take care of parsing errors and the like without you having to get involved.
+However, there may be circumstances when you need to exit the script in a hurry and
+you may need to tidy up if you have already set something up (e.g. in a before_actions method).
+The {Optplus::Parser#exit_on_error} method is provided to help. Calling the method
+will raise an exception that will be trapped to ensure that, if necessary, the 
+{Optplus::Parser#after_actions} method is called and the script exits with code 1. It will
+also display the message if provided.
+
+## Nesting Actions
+
+Optplus allows you to define sub-actions or sub-commands for an action if you want to.
+The general syntax would be: action sub [param] [options].
+
+First you need to define a nested parser class, inheriting from {Optplus::NestedParser}
+instead of {Optplus::Parser}. This is similar to the main parser but should only contain
+a usage and description call, action methods, descriptions and help text.
+
+Once this nested class is defined you must define the action to which it will belong
+using the {Optplus::Parser.nest_parser} method. Here is a simple example:
+
+    class MyParser < Optplus::Parser
+      
+      usage "action [param] [options]"
+      
+      description "simple parser"
+      
+      def options(opts)
+        # etc
+      end
+      
+      class SubParser < Optplus::NestedParser
+      
+        usage "action subaction [params] [options]"
+        
+        description "do things relating to action"
+        
+        describe :list, 'list actions'
+        def list
+          # do the listing
+        end
+        help :list 'describe what list does'
+        
+      end
+      
+      nest_parser :action, SubParser, 'do things with actions'
+      
+    end
+    
+    MyParser.run!
+    
+The methods for getting arguments and options etc that are available in MyParser are
+also available in SubParser but you cannot set_option in SubParser and you cannot add
+option switches that are specific to the action. If you want to get into that you may
+be better trying Thor.
+
+Help for nested commands works like this:
+
+* the help/usage text for the script should contain the name of the action and the
+  description provided with {Optplus::Parser#nest_parser} just like all of the other
+  actions.
+  
+* applying the -h switch with the action will display the usage, description and sub-actions
+  just as for the main help but will not repeat the option switches. There is a note
+  to remind you how to see them though (plain -h)
+  
+* applying the -h switch to an action and sub-action that has defined its own help text will
+  do exactly the same as it would if it was just an action
+  
+And finally, don't forget that sub-actions can take parameters but obviously the action
+to which they belong cannot (cos it will be interpreted as a sub-action)
+    
+## Code Walkthrough
+
+The code is simple. The class methods that are called in defining a parser use class
+instance variables to store the data defined (e.g. describe stores the action and the description
+in a hash). The {Optplus::Parser.run!} method creates an instance of the parser class
+and the constructor will call the before methods, build the Optparse object with all
+the tedious separators, call the options method to add your own option switches, and
+then read the first argument as an action.
+
+It uses Array#abbrev to convert abbreviated action names into the full action and then
+calls the method. Optparse exceptions and Optplus exceptions are trapped for convenient
+error messaging.
+
+## Dependencies
+
+Ruby  1.9.3
+abbrev standard library
+colored gem
+
+Check the {file:Gemfile} for dependencies.
+
+## Documentation
+
+Documentation is best viewed using Yard and is available online 
+at [RubyDoc](http://rdoc.info/github/osburn-sharp/optplus/frames)
+
+## Testing/Modifying
+
+There are no rspec tests provided, but there are two test scripts: {file:test/my_parser.rb}
+and {file:test/my_nested_parser.rb}. They are not comprehensive, but they do test 
+out various things.
+
+## Bugs
+
+Details of any unresolved bugs and change requests are in {file:Bugs.rdoc Bugs}
+
+## Changelog
+
+See {file:History.txt} for a summary change history
+
+## Copyright and Licence
+
+Copyright (c) 2013 Robert Sharp
+
+This software is licensed under the terms defined in {file:LICENCE.rdoc}
+
+The author may be contacted by via [GitHub](http://github.com/osburn-sharp)
+
+## Warranty
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantibility and fitness for a particular purpose.