miniparse 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: da37b3c087a37bccf31e7bbd7d5e45004da9bddf
+  data.tar.gz: 252751025abef7a40242c19649b99c76f402442c
+SHA512:
+  metadata.gz: f13f8964d343a8c70515e99bfcc6d8c14531c9dcff8f03be7ad052cc019eaa00c7491b2491d869e89cf0b959e513c68a17f5857d928fc5e56de2aa7243ff89f1
+  data.tar.gz: 59e8323b94edab1f83633dd37641bdfc30dff30cc5df688c3171f09020adb60d4f0182a6eaca703cdbdab70b1e943abaae4d475f2aeb84adf47573f1a503c3e0

data/.gitignore

@@ -0,0 +1,18 @@
+# editor files
+*.swp
+*~
+
+# temp files or dirs
+kk*
+/tmp/
+
+# generated dirs
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+

data/.rspec

@@ -0,0 +1,2 @@
+--color
+#--format doc

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.3.0
+before_install: gem install bundler -v 1.11.2

data/FAQ.md

@@ -0,0 +1,38 @@
+
+# Frequently Asked Questions
+
+---
+
+### What's the meaning of x.y.z in your version numbers?
+
+We use a [Semantic Versioning](http://semver.org/) like scheme of MAJOR.MINOR.PATCH:
+
+The MAJOR version numbers will only change when backwards incompatible changes are made to the public interface.
+
+The MINOR version number will change when adding new functionality or some extensive changes in code. But in any case the public interface will be fully backwards compatible.
+
+The PATCH number will change when fixing bugs or implementing internal or minor improvements. No changes will be made to the public interface.
+
+Additionally a `b` will be added for beta (i.e. pre-release) versions.
+
+---
+
+### Why have you `protected` methods in your classes?
+
+It is the tersest way we found of defining a public interface. Please note that the non-public interface can be changed at any time, even when just releasing minor patches.
+
+---
+
+### Nevertheless, I wish I could use that protected methods.
+
+You can. Just use `object.send(:desired_method)` or make the method public adding to your code the following:
+
+    module Miniparse
+      class DesiredClass
+        public :desired_method
+      end
+    end
+  
+---
+
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in miniparse.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Juanma Rodriguez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,76 @@
+
+# Miniparse
+
+**Miniparse is an easy to use yet flexible and powerful ruby library for parsing command-line options.**
+
+The main objetive of this implementation is minimun boiler plate with ease of use but keeping a self documenting specification. 
+
+Additionally the library is quite flexible and allows a lot of customization but always with sane defaults so **you don't need to learn nothing to start using it**.
+
+## How to use
+
+Please find below a short but meaningful example, then you can **[get more examples](https://github.com/jmrod4/miniparse/tree/master/examples)** at [Github miniparse repository](https://github.com/jmrod4/miniparse).
+
+Let's try putting the following code in `myprogram.rb`
+
+    require 'miniparse'
+    
+    parser = Miniparse::Parser.new("my program does something wonderful")
+    parser.add_option "--debug", "activate debugging"
+    parser.parse ARGV
+    
+    if parser.options[:debug]
+      puts "DEBUG ACTIVATED!"
+    else
+      puts "run silently"
+    end
+    
+Now you can run
+
+    $ ruby myprogram.rb
+
+    run silently
+
+or run
+    
+    $ ruby myprogram.rb --debug
+    
+    DEBUG ACTIVATED!
+
+or even get the auto generated help
+    
+    $ ruby yourprogram.rb --help
+    
+    my program does something wonderful
+    usage: ex01_readme.rb [--help] [--debug] <args>
+
+    Options:
+       --debug          activate debugging
+	   
+## Installation
+
+You can install it as an standard ruby gem with
+
+    $ gem install miniparse
+    
+then to use you can require it adding the following to the top of your ruby source file
+
+    require 'miniparse'
+    
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/jmrod4/miniparse.
+
+After checking out the repo you can:
+
+ * run `bin/setup` to install dependencies
+ * then run `rake test` to run the tests
+ * you can also run `bin/console` for an interactive prompt that will allow you to experiment
+ * run `bundle exec miniparse` to use the gem in this directory, ignoring other installed copies of this gem
+ * run `rake -T` to see the rake tasks defined
+
+## License
+
+This library is copyrighted software and it's available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+You can find the source code at https://github.com/jmrod4/miniparse.

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/gem_tasks"
+
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+#task :default => :test
+
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "miniparse"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/ex01_simple.rb

@@ -0,0 +1,22 @@
+# example from the project readme
+    
+require 'miniparse'
+
+parser = Miniparse::Parser.new("my program does something wonderful")
+parser.add_option "--debug", "activate debugging"
+parser.parse ARGV
+
+if parser.options[:debug]
+  puts "DEBUG ACTIVATED!"
+else
+  puts "run silently"
+end
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"

data/examples/ex02_options.rb

@@ -0,0 +1,27 @@
+require 'miniparse'
+
+parser = Miniparse::Parser.new
+
+parser.add_option("--sort", "always sort the output", shortable: true)
+parser.add_option("--pill", "just a silly option", shortable: true)
+
+# if description is nil, then the option won't appear in the help description, only in the usage string
+parser.add_option("--debug", nil)
+
+# for switches the default will be evaluated to true or false
+# for switch the default will be always false unless specified
+parser.add_option("--normal", "run normally", default: true)
+
+# for flags the typical default could be a string
+parser.add_option("--verbose LEVEL", nil, default: "0")
+
+parser.parse(ARGV)
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"

data/examples/ex03_commands.rb

@@ -0,0 +1,24 @@
+require 'miniparse'
+
+parser = Miniparse::Parser.new
+
+# if description is nil the command will appear in the help as "other commands"
+parser.add_command("list", nil)
+
+# you can use symbol or string to specify a command
+parser.add_command(:fly, "don't actually fly, just do an incredible approximate simulation")
+
+# this option is NOT global, but only applicable to the last specified command
+# ('fly' in this case)
+parser.add_option("--high", "set your flying level high")
+
+parser.parse(ARGV)
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"

data/examples/ex04_mixed.rb

@@ -0,0 +1,37 @@
+require 'miniparse'
+
+parser = Miniparse::Parser.new
+
+parser.add_option("--sort", "always sort the output", shortable: true)
+parser.add_option("--pilly", "just a silly option", shortable: true)
+
+# if description is nil, then the option won't appear in the help description, only in the usage string
+parser.add_option("--debug", nil)
+
+# for switches the default will be evaluated to true or false
+# for switch the default will be always false unless specified
+parser.add_option("--normal", "run normally", default: true)
+
+# for flags the typical default could be a string
+parser.add_option("--verbose LEVEL", nil, default: "0")
+
+# if description is nil the command will appear in the help as "other commands"
+parser.add_command("list", nil)
+
+# you can use symbol or string to specify a command
+parser.add_command(:fly, "don't actually fly, just do an incredible approximate simulation")
+
+# this option is NOT global, but only applicable to the last specified command
+# ('fly' in this case)
+parser.add_option("--high", "set your flying level high")
+
+parser.parse(ARGV)
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"

data/examples/ex05_block.rb

@@ -0,0 +1,31 @@
+require 'miniparse'
+
+parser = Miniparse::Parser.new
+
+# if `add_option` has a block it will execute (when method `parse` called) only if the 
+# option is specified in the parsed command-line (i.e. argv)
+#
+# the block will receive the option user specified value (a string) as argument 
+parser.add_option("--kill THING", "kill something") do |val|
+  puts "Die #{val}! DIE!"
+end 
+
+parser.add_command("list", nil)
+
+parser.add_command(:fly, "do an incredible approximate simulation of flying") do
+  puts "Look Ma! No hands!"
+end 
+parser.add_option("--high", "set your flying level high")
+
+
+# the blocks for the options or commands specified in ARGV will be executed now
+parser.parse(ARGV)
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"

data/examples/ex06_task_app.rb

@@ -0,0 +1,36 @@
+#/usr/bin/env ruby
+
+# example of a supposed task application, 
+# just demonstrate the self documenting feature
+
+require 'miniparse'
+
+parser = Miniparse::Parser.new("Provides an easy way to manage tasks.")
+
+parser.add_option("--debug", nil) do
+  puts "Debug activated!"
+end
+
+parser.add_option("--file FILE", "file for storing the tasks", 
+    default: "~/todos.txt")
+
+parser.add_command(:new, "creates a new todo in the default location")
+
+parser.add_command(:done, "complete a task")
+
+parser.add_command(:list, "list tasks")
+parser.add_option("--sort", "order everything!")
+
+parser.parse ARGV
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"
+
+
+

data/examples/ex07_controls.rb

@@ -0,0 +1,63 @@
+# example from the project readme
+    
+require 'miniparse'
+
+# following is just a copy of the controls defined in control.rb
+# you don't need to specify all, only the ones you want to change (maybe none)
+
+Miniparse.set_control( {
+    # gives an error if there is an unrecognized option either short or long
+    # (if not then passes them as arguments) 
+    raise_on_unrecognized: true, 
+    
+    # intercepts .parse ArgumentError (i.e. the commandline user introduced 
+    # wrong or invalid options) and exits with a helpful msg  
+    rescue_argument_error: true,
+    
+    # gives usage help and exits if commandline is empty
+    # useful if your app always needs args or options to work
+    help_cmdline_empty: false,
+    
+    # raises an ArgumentError if there are global args 
+    # (after parsing options and commands)
+    # useful if you don't expect any args
+    raise_global_args: false,
+
+    # formats help output with the width_... controls
+    formatted_help: true,
+    
+    width_display: 79,
+    width_indent: 3,
+    width_left: 18,
+    
+    # use a detailed options help usage msg or a generic one
+    detailed_usage: true,
+
+    # uses --no-... options for all options
+    # useful if you want all your options to be negatable by default
+    autonegatable: false,
+    
+    # uses short options (besides long ones) for all options
+    # useful if you want all your options to be shortable by default
+    autoshortable: false,
+    } )
+
+
+parser = Miniparse::Parser.new("does something wonderful")
+parser.add_option "--debug", "activate debugging"
+parser.parse ARGV
+
+if parser.options[:debug]
+  puts "DEBUG ACTIVATED!"
+else
+  puts "run silently"
+end
+
+# show results with the current used command line
+# for global options
+puts "args     #{parser.args.inspect}"
+puts "options  #{parser.options.inspect}"
+# for commands
+puts "parsed command  #{parser.command.inspect}"
+puts "command args    #{parser.command_args.inspect}"
+puts "command options #{parser.command_options.inspect}"