parse-argv 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '08c6221625a88b034352b5dbb8fb673bf2224ab76c3d535ef1fe43c5b33ae1fa'
+  data.tar.gz: faf7ef2645091f3cf6de86ea23104105830530cfbc03e1237cd0bad16d077658
+SHA512:
+  metadata.gz: '0486e25acc34d509335f469a30bfb2fb32d038ca7de45a3ab5ff19039f34110f01adade82a47d0c277403c97767182c0881fef734950ff63c22ccaf2d464bdd4'
+  data.tar.gz: a6c629bfd3c6103a1cf09c80b7efbe38036b24051b473d2f488e47b8b4c6b15045ae92910f9583e2be749ddabf5458ecd0db1ddfa6c7e48da55328f32922e580

data/.yardopts

@@ -0,0 +1,5 @@
+--readme README.md
+--title 'ParseArgv Documentation'
+--charset utf-8
+--markup markdown
+'lib/**/*.rb' - 'syntax.md' 'LICENSE'

data/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2017-2021, Mike Blumtritt. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/ReadMe.md

@@ -0,0 +1,101 @@
+# ParseArgv
+
+A command line parser that only needs your help text.
+
+- Gem: [rubygems.org](https://rubygems.org/gems/parse-argv)
+- Source: [github.com](https://github.com/mblumtritt/parse-argv)
+- Help: [rubydoc.info](https://rubydoc.info/gems/parse-argv)
+
+## Description
+
+Just write the help text for your application and ParseArgv will take care of your command line. It works sort of the other way around than OptParse, where you write a lot of code to get a command line parser and generated help text. ParseArgv simply takes your help text and parses the command line and presents you the results.
+
+You can use ParseArgv for simpler programs just as well as for CLI with multi-level sub-commands (git-like commands). ParseArgv is easy to use, fast and also helps you convert the data types of command line arguments.
+
+## Example
+
+The given help text
+
+```
+usage: test [options] <infile> [<outfile>]
+
+This is just a demonstration.
+
+options:
+  -f, --format <format>   specify the format
+  --verbose               enable verbose mode
+  -h, --help              print this help text
+```
+
+will be interpreted as
+
+- there is a command "test"
+- which requires and argument "infile"
+- optionally accepts an  second argument "outfile"
+- accepts an option named "format" when `-f` or `--format` are given
+- defines the boolean option "verbose" when `--verbose` is given
+- defines the boolean option "help" when `-h` or `--help` are given
+
+## How To Use
+
+Please, see the [Gem's help](https://rubydoc.info/gems/parse-argv) for detailed information, or have a look at the  [`./examples`](./examples) directory which contains some commands to play around.
+
+The supported help text syntax and the command line interface syntax are described in the [syntax help](./syntax.md).
+
+In general you just specify the help text and get the parsed command line:
+
+```ruby
+require 'parse-argv'
+
+args = ParseArgv.from <<~HELP
+  usage: test [options] <infile> [<outfile>]
+
+  This is just a demonstration.
+
+  options:
+    -f, --format <format>   specify the format
+    --verbose               enable verbose mode
+    -h, --help              print this help text
+HELP
+
+args.verbose?
+#=> true, when "--verbose" argument was specified
+#=> false, when "--verbose" argument was not specified
+
+args[:infile].as(File, :readable)
+#=> file name
+
+args.outfile?
+#=> true, when second argument was specified
+args.outfile
+#=> second argument or nil when not specified
+```
+
+## Installation
+
+Use [Bundler](http://gembundler.com/) to add ParseArgv in your own project:
+
+Include in your `Gemfile`:
+
+```ruby
+gem 'parse-argv'
+```
+
+and install it by running Bundler:
+
+```bash
+bundle
+```
+
+To install the gem globally use:
+
+```bash
+gem install parse-argv
+```
+
+After that you need only a single line of code in your project to have it on board:
+
+```ruby
+require 'parse-argv'
+```
+

data/examples/ReadMe.md

@@ -0,0 +1,29 @@
+# Examples
+
+This directory contains some examples for using ParseArgv. Play around and get an impression how an application will handle the command line by using ParseArgv.
+
+To run an example just start with:
+
+```shell
+ruby examples/simple.rb --help
+```
+
+## check.rb
+
+Can be used to test your help text syntax. Try the following to see it in action:
+
+```shell
+ruby examples/check.rb examples/multi.rb
+```
+
+## conversion.rb
+
+This example demonstrates the conversion capabilities.
+
+## multi.rb
+
+This is an example of a "git-like" command - a command with subcommands.
+
+## simple.rb
+
+A simple and very basic demonstration.

data/examples/check.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/parse-argv'
+
+ARGS = ParseArgv.from <<~HELP
+  Test the syntax of your help text for ParseArgv.
+
+  Usage: check [options] <files>...
+
+  Options:
+    -f, --format <format>   display format: default, json, usage
+    -c, --command <name>    display command with <name> only
+    -h, --help              display this help
+    -v, --version           display version information
+HELP
+
+puts(ARGS) or exit if ARGS.help?
+puts("check v#{ParseArgv::VERSION}") or exit if ARGS.version?
+
+cmds =
+  begin
+    ParseArgv.parse(ARGS[:files].as(:file_content).join("\n"))
+  rescue ArgumentError => e
+    ARGS.error!("invalid syntax - #{e}")
+  end
+
+def find_command(all, name)
+  command = all.find { |cmd| cmd[:full_name] == name || cmd[:name] == name }
+  command or ARGS.error!("no such command - #{name}")
+end
+
+cmds = [find_command(cmds, ARGS[:name].as(:string))] if ARGS.name?
+
+module Format
+  class Json
+    def self.show(commands)
+      commands.each { |command| command.delete(:help) }
+      require('json')
+      puts(JSON.dump(commands))
+    end
+  end
+
+  class Usage
+    def self.show(commands)
+      puts(commands.map { |command| new(command) }.join("\n"))
+    end
+
+    def initialize(command)
+      @command = command
+    end
+
+    def to_s
+      name, args = @command.fetch_values(:full_name, :arguments)
+      ret = "usage: #{name}"
+      args.each_pair { |arg_name, info| ret << as_str(arg_name, info) }
+      ret
+    end
+
+    def as_str(name, info)
+      case info[:type]
+      when :argument
+        info[:required] ? " <#{name}>" : " [<#{name}>]"
+      when :argument_array
+        info[:required] ? " <#{name}>..." : " [<#{name}>...]"
+      when :option
+        names = info[:names].map { |n| n.size == 1 ? "-#{n}" : "--#{n}" }
+        " [#{names.join(', ')} <#{name}>]"
+      when :switch
+        names = info[:names].map { |n| n.size == 1 ? "-#{n}" : "--#{n}" }
+        " [#{names.join(', ')}]"
+      end
+    end
+  end
+
+  class Default < Usage
+    def self.show(commands)
+      puts(commands.map { |command| new(command) }.join("\n\n"))
+    end
+
+    def to_s
+      full_name, name, args =
+        @command.fetch_values(:full_name, :name, :arguments)
+      ret = ["#{full_name == name ? 'Command' : 'Subcommand'}: #{name}"]
+      return ret if args.empty?
+      width = args.keys.max_by(&:size).size
+      args.each_pair do |arg_name, info|
+        ret << "   #{arg_name.to_s.ljust(width)}   #{as_str(info)}"
+      end
+      ret.join("\n")
+    end
+
+    def as_str(info)
+      case info[:type]
+      when :argument
+        info[:required] ? 'argument: required' : 'argument'
+      when :argument_array
+        info[:required] ? 'arguments array: required' : 'arguments array'
+      when :option, :switch
+        names = info[:names].map { |n| n.size == 1 ? "-#{n}" : "--#{n}" }
+        "#{info[:type]} #{names.join(', ')}"
+      end
+    end
+  end
+end
+
+Format.const_get(
+  ARGS[:format].as(%w[default json usage], default: 'default').capitalize
+).show(cmds)

data/examples/conversion.rb

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/parse-argv'
+
+ARGS = ParseArgv.from <<~HELP
+  ParseARGS Demo about conversions
+  This example demonstrates the build-in conversions.
+
+  usage: conversion [options]
+
+  options:
+    -s, --string <string>      accept any non-empty String
+    -a, --array <array>        accept an array of String
+    -r, --regexp <regexp>      convert to a regular expression
+    -i, --integer <integer>    convert to Integer
+    -f, --float <float>        convert to Float
+    -n, --number <number>      convert to Numeric (Integer or Float)
+    -b, --byte <byte>          convert to number of byte
+    -d, --date <date>          convert to Date
+    -t, --time <time>          convert to Time
+    -N, --filename <filename>  convert to a (relative) file name String
+    -F, --fname <file>         accept name of an existing file
+    -D, --dname <dir>          accept name of an existing directory
+    -A, --files <files>        accept an array of file names
+    -1, --one <oneof>          accept one of 'foo', 'bar', 'baz'
+    -h, --help                 print this help
+HELP
+
+puts(ARGS) or exit if ARGS.help?
+
+puts <<~RESULT
+  string    #{ARGS[:string].as(String).inspect}
+  array     #{ARGS[:array].as(Array).inspect}
+  filename  #{ARGS[:filename].as(:file_name).inspect}
+  regexp    #{ARGS[:regexp].as(Regexp).inspect}
+  integer   #{ARGS[:integer].as(Integer)}
+  float     #{ARGS[:float].as(Float)}
+  number    #{ARGS[:number].as(Numeric)}
+  byte      #{ARGS[:byte].as(:byte)}
+  date      #{ARGS[:date].as(:date)}
+  time      #{ARGS[:time].as(Time)}
+  file      #{ARGS[:file].as(File).inspect}
+  dir       #{ARGS[:dir].as(Dir).inspect}
+  files     #{ARGS[:files].as([File]).inspect}
+  oneof     #{ARGS[:oneof].as(%w[foo bar baz])}
+RESULT

data/examples/multi.rb

@@ -0,0 +1,79 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/parse-argv'
+
+ARGS = ParseArgv.from <<~HELP
+  ParseARGS Demo for a CLI with subcommands
+  This example demonstrates a CLI with subcommands. It processes an imganinary
+  key/value store that can be synchronized with a server.
+
+  usage: multi <command>
+
+  commands:
+    var             get a variable
+    var add         add a variable
+    var remove      remove a variable
+    push            push all vars
+    pull            pull all vars
+    help            show command specific help
+    -h, --help      show this help
+    -v, --version   show version information
+
+  Play with different command line parameters and options to see how it works!
+
+  usage: multi var <name>
+
+  Get variable <name>.
+
+  usage: multi var add [options] <name> <value>...
+
+  Add a variable <name> with given <value>.
+
+  options:
+    -f, --force   allow to overwrite existing variable <name>
+
+  usage: multi var remove <name>
+
+  Remove variable <name>.
+
+  usage: multi push [options] <url>
+
+  Push all variables to server at <url>.
+
+  options:
+    -t, --token <token>   user token
+    -f, --force           force push
+
+  usage: multi pull [options] <url>
+
+  Pull all variables from server at <url>.
+
+  options:
+    -t, --token <token>   user token
+    -f, --force           force pull (override local variables)
+
+  usage: multi help [<command>...]
+
+  Show help for given <command>.
+HELP
+
+case ARGS.current_command.name
+when 'multi'
+  puts(ARGS.help? ? ARGS : 'multi sample v1.0.0')
+when 'help'
+  if ARGS.command?
+    command = ARGS.find_command(ARGS.command)
+    ARGS.error!("unknown command - #{ARGS.command.join(' ')}") if command.nil?
+    puts(command.help)
+  else
+    puts(ARGS.main_command.help)
+  end
+else
+  puts "command '#{ARGS.current_command}':"
+  arguments = ARGS.to_h
+  width = arguments.keys.max_by(&:size).size + 3
+  arguments.each_pair do |name, value|
+    puts("   #{name.to_s.ljust(width)}#{value.inspect}")
+  end
+end

data/examples/simple.rb

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/parse-argv'
+
+ARGS = ParseArgv.from <<~HELP
+  Simple ParseArgv Demo
+
+  This is a demo for the command `simple`, which requires an <input> argument and
+  accepts optional an <output> argument. It accepts also some options.
+
+  Usage: simple [options] <input> [<output>]
+
+  Options:
+    -f, --format <format>  select a format: txt, html, md
+    -c, --count <count>    set a count (default 10)
+
+  The command's options can be defined in different paragraphs.
+
+  More Options:
+    -h, --help      display this help
+    -v, --version   display version information
+    --verbose       enable verbose mode
+
+  Play with different command line parameters and options to see how it works!
+HELP
+
+puts(ARGS) or exit if ARGS.help?
+puts('simple v1.0.0') or exit if ARGS.version?
+puts <<~RESULT
+  arguments:
+    input    #{ARGS.input}
+    output   #{ARGS.output}
+    format   #{ARGS[:format].as(%w[txt html md], default: 'txt')}
+    count    #{ARGS[:count].as(Integer, :positive, default: 10)}
+    verbose  #{ARGS.verbose}
+RESULT