dreck 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: eaaec798888ca9a462d16bf380853aafa47eba29
+  data.tar.gz: e3657ca419dc6a331a292af9778402d1e6d37e6e
+SHA512:
+  metadata.gz: f77bdc510acefb7c00223ed0e49d160c9f19749e92a9ea100539cdcfd0cb9798b1f11314828a906a67771f4cc3e7460939c2499b046680d93bc839a3df35ed85
+  data.tar.gz: 0ced355c2e535154d7702ca4e47eb1dc3469aaa8789b05ec367d84e16b462827a784aab812efeefcb316c0f8923cd7bdad936d8a4a2387589f8337951fdc8285

data/.yardopts

@@ -0,0 +1 @@
+--no-private --markup-provider=redcarpet --markup=markdown - *.md LICENSE

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 William Woodruff <william @ yossarian.net>
+
+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,61 @@
+dreck
+=====
+
+A stupid parser for trailing arguments.
+
+### Motivation
+
+There are lots of good argument parsers for Ruby:
+[OptionParser](https://ruby-doc.org/stdlib/libdoc/optparse/rdoc/OptionParser.html),
+[Slop](https://github.com/leejarvis/slop), [trollop](https://manageiq.github.io/trollop/),
+[cocaine](https://github.com/thoughtbot/cocaine), etc.
+
+Most of these are great for parsing and typechecking options, but none provide a good
+interface to the arguments that often *trail* the options.
+
+Dreck does exactly that. Give it a specification of arguments (and their
+types) to expect, and it will give you a nicely typechecked result.
+
+### Installation
+
+```bash
+$ gem install dreck
+```
+
+### Usage
+
+Dreck is best used in conjunction with an option parser like
+[Slop](https://github.com/leejarvis/slop), which can provide an array of
+arguments with options already filtered out:
+
+```ruby
+opts = Slop.parse do |s|
+  # ...
+end
+
+opts.args # => [ "/dev/urandom", "/dev/sda", "512" ]
+
+results = Dreck.parse opts.args, strict: true do
+  file   :input
+  symbol :output
+  int    :blocksize
+end
+
+results[:input] # => "/dev/urandom"
+results[:output] # => :"/dev/sda"
+results[:blocksize] # => 512
+```
+
+Lists are also supported:
+
+```ruby
+result = Dreck.parse opts.args do
+  string :uuid
+  list   :file, :inputs, count: 2
+  list   :int, :nums
+end
+
+result[:id] # => "01aa84ab-5b2c-4861-adc9-fcc6990a5ca5"
+result[:inputs] # => ["/tmp/foo", "/tmp/bar"]
+result[:nums] # => [1, 2, 3, 4, 5]
+```

data/lib/dreck.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "dreck/result"
+
+# The primary namespace for {Dreck}.
+module Dreck
+  # {Dreck}'s current version.
+  VERSION = "0.0.1"
+
+  # Parse the given arguments and produce a result.
+  # @param args [Array<String>] the arguments to parse
+  # @param strict [Boolean] whether or not to be strict about argument absorption
+  # @return [Result] the parsing result
+  def self.parse(args = ARGV, strict: true, &block)
+    result = Result.new(args, strict: strict)
+    result.instance_eval(&block)
+    result.parse!
+  end
+end

data/lib/dreck/exceptions.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Dreck
+  # A generic error class for all {Dreck} errors.
+  class DreckError < RuntimeError
+  end
+
+  # Raised during argument absorption if arguments are either left over
+  # or are insufficient to populate the expected results.
+  class AbsorptionError < DreckError
+  end
+
+  # Raised during parsing if a given type cannot be produced from the corresponding
+  # argument.
+  class ParserError < DreckError
+  end
+end

data/lib/dreck/parser.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "parser"
+
+module Dreck
+  # Type and other constraint testing methods for {Dreck}.
+  class Parser
+    # @return [Array<Symbol>] the scalar types recognized by {Dreck}.
+    # @api private
+    SCALAR_TYPES = %i[int float path file directory symbol string].freeze
+
+    class << self
+      # @param int [String] the string to coerce into an integer
+      # @return [Integer] the integer value of the string
+      # @raise [ParserError] if the string cannot be converted
+      def parse_int(int)
+        Integer int rescue raise ParserError, "#{int}: not an integer"
+      end
+
+      # @param float [String] the string to coerce into a float
+      # @return [Float] the floating-point value of the string
+      # @raise [ParserError] if the string cannot be converted
+      def parse_float(float)
+        Float float rescue raise ParserError, "#{float}: not a float"
+      end
+
+      # @param path [String] the string to check for path-ness
+      # @return [String] the string itself, if it is a path
+      # @raise [ParserError] if the string is not a valid path on disk
+      def parse_path(path)
+        raise ParserError, "#{path}: no such path" unless File.exist?(path)
+        path
+      end
+
+      # @param file [String] the string to check for file-ness
+      # @return [String] the string itself, if it is a filename
+      # @raise [ParserError] if the string is not a valid regular file on disk
+      def parse_file(file)
+        raise ParserError, "#{file}: no such file" unless File.file?(file)
+        file
+      end
+
+      # @param dir [String] the string to check for directory-ness
+      # @return [String] the string itself, if it is a directory
+      # @raise [ParserError] if the string is not a valid directory on disk
+      def parse_directory(dir)
+        raise ParserError, "#{dir}: no such directory" unless File.directory?(dir)
+        dir
+      end
+
+      # @param sym [String] the string to coerce into a symbol
+      # @return [Symbol] the coerced symbol
+      def parse_symbol(sym)
+        sym.to_sym
+      end
+
+      # @param str [String] the string to coerce into a string
+      # @return [String] the coerced string
+      # @note This does nothing.
+      def parse_string(str)
+        str
+      end
+
+      # @param type [Symbol] the type of each member of the list
+      # @param list [Array<String>] the value of each member
+      # @return [Object] the coerced results
+      def parse_list(type, list)
+        list.map { |arg| send "parse_#{type}", arg }
+      end
+    end
+  end
+end

data/lib/dreck/result.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require_relative "exceptions"
+require_relative "parser"
+
+module Dreck
+  # Represents the state and results of a {Dreck} parse.
+  class Result
+    # @return [Array] the type, name, and count information for arguments
+    attr_reader :expected
+
+    # @return [Hash] the parsing results hash
+    attr_reader :results
+
+    # @param args [Array<String>] the arguments to parse
+    # @param strict [Boolean] whether or not to be strict about argument absorption
+    def initialize(args, strict: true)
+      @args = args.dup
+      @strict = strict
+      @expected = []
+      @results = {}
+    end
+
+    # @param key [Symbol] the named argument to look up
+    # @return [Object] the parsed value
+    def [](key)
+      @results[key]
+    end
+
+    # @return [Boolean] whether the results were parsed strictly
+    def strict?
+      @strict
+    end
+
+    Parser::SCALAR_TYPES.each do |type|
+      define_method type do |sym|
+        @expected << [type, sym]
+      end
+    end
+
+    # Specifies a list of arguments of a given type to be parsed.
+    # @param type [Symbol] the type of the arguments
+    # @param sym [Symbol] the name of the argument in {results}
+    # @param count [Integer] the number of arguments in the list
+    def list(type, sym, count: nil)
+      @expected << [:list, type, sym, count]
+    end
+
+    # Perform the actual parsing.
+    # @return [Result] this instance
+    # @api private
+    def parse!
+      check_absorption!
+
+      @expected.each do |type, *rest|
+        case type
+        when :list
+          parse_list!(*rest)
+        else
+          parse_type!(type, *rest)
+        end
+      end
+
+      self
+    end
+
+    # Check whether the expected arguments absorb all supplied arguments.
+    # @raise [AbsoptionError] if absorption fails and {strict?} is not true
+    # @api private
+    def check_absorption!
+      count = count_expected
+
+      return if count.nil?
+      raise AbsoptionError, "too few arguments" if count > @args.size && strict?
+      raise AbsoptionError, "too many arguments" if count < @args.size && strict?
+    end
+
+    # Count the number of arguments expected to be supplied.
+    # @raise [Integer, nil] the number of expected arguments, or nil if a list
+    #  of indeterminate size is specified
+    # @api private
+    def count_expected
+      @expected.inject(0) do |n, exp|
+        case exp.first
+        when :list
+          # if the list is greedy, all arguments have to be absorbed
+          break unless exp[3]
+
+          n + exp[3]
+        else
+          n + 1
+        end
+      end
+    end
+
+    # Parse a one or more expected arguments of a given type and add them to
+    #  the results.
+    # @param type [Symbol] the type of the individual elements of the list
+    # @param sym [Symbol] the key to store the results under in {results}
+    # @param count [Integer, nil] the size of the list, or nil if the list
+    #  absorbs all following arguments
+    # @api private
+    def parse_list!(type, sym, count)
+      args = if count
+               @args.shift count
+             else
+               @args
+             end
+
+      @results[sym] = Parser.parse_list type, args
+    end
+
+    # Parse one expected argument of a given scalar type and add it to the results.
+    # @param type [Symbol] the type of the expected argument
+    # @param sym [Symbol] the key to store the result under in {results}
+    # @api private
+    def parse_type!(type, sym)
+      arg = @args.shift
+
+      @results[sym] = Parser.send("parse_#{type}", arg)
+    end
+  end
+end

metadata

@@ -0,0 +1,50 @@
+--- !ruby/object:Gem::Specification
+name: dreck
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- William Woodruff
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-06-22 00:00:00.000000000 Z
+dependencies: []
+description: Typechecks and coerces non-option arguments.
+email: william@tuffbizz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".yardopts"
+- LICENSE
+- README.md
+- lib/dreck.rb
+- lib/dreck/exceptions.rb
+- lib/dreck/parser.rb
+- lib/dreck/result.rb
+homepage: https://github.com/woodruffw/dreck
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: dreck - A stupid parser for trailing arguments.
+test_files: []