clingon 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5abedd0654d50025ee7f73c7167dc19a37013edb
+  data.tar.gz: b84f98b0327be4704dd3d7269b9116e57606805c
+SHA512:
+  metadata.gz: 40db83ed840a2090c225a728a47d2a054f672dad3baf60a283b85d8a1e4fbe6861c3ba7c6891e84b60cf51499a154c2e995a44d44fcbc1cb20bd5598942db120
+  data.tar.gz: 51578191d232fd15be7397712ee13203261d8dfc9318672d81409db4554e497751db9f0b3e5866fcb805f555283c2f1d081a2272c066bdbe17e6ffde3b65121e

data/README.md

@@ -0,0 +1,218 @@
+# Clingon
+
+[![Gem](https://img.shields.io/gem/v/clingon.svg?style=flat-square)](https://rubygems.org/gems/clingon)
+[![GitHub issues](https://img.shields.io/github/issues/mardotio/clingon.svg?style=flat-square)](https://github.com/mardotio/clingon/issues)
+[![Gem](https://img.shields.io/gem/dtv/clingon.svg?style=flat-square)](https://rubygems.org/gems/clingon)
+
+## Overview
+
+The clingon gem can be used to easily parse command line input from a user.
+It can also be configured so that you can validate the inputs you receive. This 
+gem can be used to parse something like this:
+
+```
+--first_name bob --last_name smith --email bob.smith@email.com -h
+```
+
+into this:
+
+```ruby
+[
+  {
+    :name => 'first_name',
+    :value => 'bob'
+  },{
+    :name => 'last_name',
+    :value => 'smith'
+  },{
+    :name => 'email',
+    :value => 'bob.smith@email.com'
+  },{
+    :name => 'help',
+    :value => true
+  }
+]
+```
+
+## Table of Contents
+
+<!-- TOC -->
+
+- [Clingon](#clingon)
+  - [Overview](#overview)
+  - [Installation](#installation)
+  - [Setup](#setup)
+    - [Name](#name)
+    - [Short Name](#short-name)
+    - [Required](#required)
+    - [Empty](#empty)
+    - [Type](#type)
+    - [Check](#check)
+    - [Values](#values)
+  - [Use](#use)
+    - [Configuration](#configuration)
+    - [Parsing](#parsing)
+    - [Accessing Values](#accessing-values)
+  - [Examples](#examples)
+
+<!-- /TOC -->
+
+## Installation
+
+To install simply use Ruby's gem installer:
+
+```
+gem install clingon
+```
+
+## Setup
+
+In order to use the library, you must provide a structure that defines all
+of the values you expect. This structure is expected to be an array of hashes
+containing all the options you want. Each hash can contain any of the following
+options:
+
+|Option|Expected Value|Required|
+|------|--------------|:------:|
+|name|string|*|
+|short_name|string||
+|required|boolean||
+|empty|boolean||
+|type|string (see below)||
+|check|regex/string||
+|values|array||
+
+**All keys in each hash must be ruby symbols**
+
+`values`, `type`, and `check` are all used to validate that the received values
+match what you were expecting. The parser will only use one of these settings to
+validate an input, so you should only define the of those values per input. If
+more than one of these values are defined, the parser will use them in the
+following order: `values`, `type`, `check`.
+
+### Name
+
+This value will be used as the long name for the command line flag. This value
+must be defined in your structure for any value that you want to parse. This
+value should be a `string`.
+
+### Short Name
+
+The value will be used to create a shortened version of the flag. It is an
+optional value, and it is recommended that it be a single character if possible,
+but there is no limit on length.
+
+### Required
+
+Specifies if the flag must be present. If the flag is not found when parsing,
+it will throw an error. This value is optional, but if defined, value must
+be either `true` or `false`; defaults to `false`.
+
+### Empty
+
+This can be used if the flag does not require any value and is simply an option
+marker (i.e -r for recursive or -h for help). This value is optional, but if
+defined, value must be either `true` or `false`; defaults to `false`.
+
+The `empty` flag is used for flags that don't need an additional value. It is
+essentially a boolean value (`false` if absent `true` is present). If a value is
+required it should not have the `empty` flag. Required values that have and
+`empty` flag will simply ignore the `empty` option.
+
+### Type
+
+This option allows you to define what type of value the flag is expecting. If
+the received value does not match the expected type an error will be thrown.
+Currently supported types are:
+
+|Type|Description|
+|----|--------|
+|num|Any number, integer or float|
+|int|Any integer|
+|float|A decimal number|
+|bool|`true` or `false`|
+
+Additionally, when the values are parsed, the user input will be converted to
+the specified type (int, float, bool). If `num` is specified, input will be
+converted to either `float` or `int`. When specified in your structure, the type
+must be specified as a string.
+
+### Check
+
+Regular expression that should be used to check the input value against. This
+can be a string (it will be converted to a regular expression), or a a regular
+expression (i.e. `/^\d+$/`). If the received value does not match the specified
+regex, an error will be thrown.
+
+**If using a YAML configuration file, it is recommended that you use single
+quotes (`'`) when specifing a regular expression. Not doing so may cause the
+YAML parser to interpret some of the charaters as escape charaters.**
+
+### Values
+
+An array of values that are acceptable for the flag. All elements of the array
+should be strings since all inputs from a terminal are received by ruby as
+strings. If the received value is not a member of the array, an error will be
+thown.
+
+## Use
+
+### Configuration
+
+To use the parser, you must first configure the library with your structure and
+the inputs you wish to parse. There are four values you can configure.
+
+|Setting|Description|Value|Required|
+|-------|-----------|-----|:------:|
+|structure|The structure to be used|Array|*|
+|inputs|The inputs you need to parse|Array|*|
+|delimiter|Delimiter for the flags (defaults to `-`)|String||
+|strict|Whether parser should accept inputs that look like flags|Bool||
+
+Optionally, you can use a YAML configuration file to set some or all of these
+values (at the minimum, the file should contain the structure). To use this
+option, pass a relative or absolute path to a YAML file. The parser expects to
+find the same values as the table above as sybols (i.e `:structure`, `:strict`).
+The only value that cannot be configured through the file are the inputs. To
+use a file to configure the parser, just do:
+
+```ruby
+Clingon.configure do |c|
+  c.conf_file = 'conf_file.yaml'
+end
+```
+
+### Parsing
+
+After you have configured the parser, you simply need to call the `parse`
+method.
+
+```ruby
+Clingon.parse
+```
+
+### Accessing Values
+
+The parser has a `fetch` method that allows you to retrieve one or all of the
+parsed values. To access the parsed values, simply call the method with the
+value you want, or leave the arguments empty if you want to retrive all values.
+
+if you query for a specific value, you must use the `name` that was used in the
+configuration structure.
+
+```ruby
+# This will return all parsed values as an array of hashes
+all_values = Clingon.fetch
+
+# This will return a hash containing the value that was requested, or nil if the
+# value was not found
+name = Clingon.fetch('name')
+```
+
+## Examples
+
+[`structure.yaml`](/examples/structure.yaml) contains a structure in YAML
+format. [`example_1.rb`](/examples/example_1.rb) makes use of the YAML file
+configuration file. If you are not interested in using a YAML configuration
+file, and instead want to define your structure within your script,
+[`example_2.rb`](/examples/example_2.rb) defines an inline structure.

data/lib/clingon.rb

@@ -0,0 +1,151 @@
+require 'clingon/errors'
+require 'clingon/version'
+require 'clingon/helpers/input_store'
+require 'clingon/helpers/structure_checker'
+require 'clingon/checks/checks'
+require 'clingon/helpers/parser_configuration'
+require 'yaml'
+
+module Clingon
+  class << self
+    attr_accessor :conf, :store, :reserved
+  end
+
+  def self.configure
+    self.store ||= InputStore.new
+    self.conf ||= ParserConfiguration.new
+    yield(conf)
+    self.reserved = conf.structure.inject([]) do |all, current|
+      arr = ["#{conf.delimiter * 2}#{current[:name]}"]
+      arr << "#{conf.delimiter}#{current[:short_name]}" if current[:short_name]
+      all + arr
+    end
+  end
+
+  def self.fetch(value = nil)
+    if value
+      store.fetch(value)
+    else
+      store.inputs
+    end
+  end
+
+  def self.strict_parse
+    cli_inputs = conf.inputs.clone
+    cli_inputs.each do |input|
+      if input =~ /^#{conf.delimiter}{1,2}/ && !Clingon.reserved?(input)
+        raise(ReservedKeywordError.new(received: input, reserved: [/^-{1,2}/]))
+      end
+    end
+  end
+
+  def self.parse
+    Clingon.strict_parse if conf.strict
+    required_values = Clingon.get_required
+    Clingon.parse_required(required_values)
+    optional_values = Clingon.get_optional
+    Clingon.parse_optional(optional_values)
+  end
+
+  def self.get_required_value(flag)
+    name = "#{conf.delimiter * 2}#{flag[:name]}"
+    short_name = "#{conf.delimiter}#{flag[:short_name]}" if flag[:short_name]
+    index = conf.inputs.index(short_name) if short_name
+    index ||= conf.inputs.index(name)
+    raise(MissingArgumentError.new(name: name, short_name: short_name)) unless index
+    conf.inputs[index + 1]
+  end
+
+  def self.get_optional_value(flag)
+    empty = flag[:empty]
+    name = "#{conf.delimiter * 2}#{flag[:name]}"
+    short_name = "#{conf.delimiter}#{flag[:short_name]}" if flag[:short_name]
+    index = conf.inputs.index(short_name) if short_name
+    index ||= conf.inputs.index(name)
+    if index && empty
+      true
+    elsif empty
+      false
+    elsif index
+      conf.inputs[index + 1]
+    else
+      nil
+    end
+  end
+
+  def self.get_required
+    conf.structure.select { |flag| flag[:required] }
+  end
+
+  def self.get_optional
+    conf.structure.reject { |flag| flag[:required] }
+  end
+
+  def self.reserved?(value)
+    reserved.include?(value)
+  end
+
+  def self.convert_to_type(value, type)
+    value_to_convert = value.to_s
+    case type
+    when 'int'
+      value_to_convert.to_i
+    when 'float'
+      value_to_convert.to_f
+    when 'num'
+      if value_to_convert =~ /^\d+$/
+        value_to_convert.to_i
+      else
+        value_to_convert.to_f
+      end
+    when 'bool'
+      value_to_convert == 'true'
+    else
+      value_to_convert
+    end
+  end
+
+  def self.parse_required(required_structure)
+    required_structure.each do |flag|
+      check = flag[:check]
+      type = flag[:type]
+      allowed_values = flag[:values]
+      user_input = Clingon.get_required_value(flag)
+      if Clingon.reserved?(user_input)
+        raise(ReservedKeywordError.new(received: user_input, reserved: reserved))
+      end
+      if allowed_values
+        Clingon.check_allowed_value(user_input, allowed_values)
+      elsif type
+        Clingon.check_against_type(user_input, type)
+      elsif check
+        Clingon.check_against_regex(user_input, check)
+      end
+      store.store(flag[:name], user_input)
+    end
+  end
+
+  def self.parse_optional(optional_structure)
+    optional_structure.each do |flag|
+      check = flag[:check]
+      type = flag[:type]
+      allowed_values = flag[:values]
+      empty = flag[:empty]
+      user_input = Clingon.get_optional_value(flag)
+      if user_input && !empty
+        if Clingon.reserved?(user_input)
+          raise(ReservedKeywordError.new(received: user_input, reserved: reserved))
+        end
+        if allowed_values
+          Clingon.check_allowed_value(user_input, allowed_values)
+        elsif type
+          Clingon.check_against_type(user_input, type)
+          user_input = Clingon.convert_to_type(user_input, type)
+        elsif check
+          Clingon.check_against_regex(user_input, check)
+        end
+      end
+      store.store(flag[:name], user_input)
+    end
+  end
+end

data/lib/clingon/checks/checks.rb

@@ -0,0 +1,34 @@
+require 'clingon/checks/type_regex'
+
+module Clingon
+  def self.check_against_type(value, type)
+    case type
+    when 'int'
+      check = Clingon::INT.dup
+    when 'float'
+      check = Clingon::FLOAT.dup
+    when 'num'
+      check = Clingon::NUM.dup
+    when 'bool'
+      check = Clingon::BOOL.dup
+    else
+      raise(UnexpectedTypeError.new(received: type))
+    end
+
+    value_to_check = value.to_s
+
+    return if value_to_check =~ check
+    raise(TypeMatchError.new(expected: type, received: value))
+  end
+
+  def self.check_against_regex(value, check)
+    regex_check = Regexp.new(check)
+    return if value =~ regex_check
+    raise(MatchError.new(expected: regex_check, received: value))
+  end
+
+  def self.check_allowed_value(value, allowed)
+    return if allowed.index(value)
+    raise(UnexpectedValueError.new(expected: allowed, received: value))
+  end
+end

data/lib/clingon/checks/type_regex.rb

@@ -0,0 +1,6 @@
+module Clingon
+  INT   = /^\d+$/
+  FLOAT = /^\d*\.\d+$/
+  NUM   = /^(\d+|\d*\.\d+)$/
+  BOOL  = /^(false|true)$/
+end

data/lib/clingon/errors.rb

@@ -0,0 +1,68 @@
+module Clingon
+  class ConfigurationFileError < StandardError
+  end
+
+  class YAMLSyntaxError < StandardError
+  end
+
+  class MatchError < StandardError
+    attr_reader :expected, :received
+    def initialize(payload)
+      @expected = payload[:expected]
+      @received = payload[:received]
+      msg = "Value #{received} does not match #{expected}"
+      super(msg)
+    end
+  end
+
+  class MissingArgumentError < StandardError
+    attr_reader :name, :short_name
+    def initialize(payload)
+      @name = payload[:name]
+      @short_name = payload[:short_name]
+      name_arr = [name]
+      name_arr << short_name if short_name
+      msg = "Missing required input #{name_arr.join('/')}"
+      super(msg)
+    end
+  end
+
+  class UnexpectedValueError < StandardError
+    attr_reader :expected, :received
+    def initialize(payload)
+      @expected = payload[:expected]
+      @received = payload[:received]
+      msg = "Received #{received}, expected one of (#{expected.join(', ')})"
+      super(msg)
+    end
+  end
+
+  class UnexpectedTypeError < StandardError
+    attr_reader :received
+    def initialize(payload)
+      @received = payload[:received]
+      msg = "Type #{received} is not valid"
+      super(msg)
+    end
+  end
+
+  class TypeMatchError < StandardError
+    attr_reader :expected, :received
+    def initialize(payload)
+      @expected = payload[:expected]
+      @received = payload[:received]
+      msg = "Received #{received}, expected type #{expected}"
+      super(msg)
+    end
+  end
+
+  class ReservedKeywordError < StandardError
+    attr_reader :received, :reserved
+    def initialize(payload)
+      @received = payload[:received]
+      @reserved = payload[:reserved]
+      msg = "Value #{received} is a reserved keyword"
+      super(msg)
+    end
+  end
+end

data/lib/clingon/helpers/input_store.rb

@@ -0,0 +1,23 @@
+class InputStore
+  attr_reader :inputs
+  def initialize
+    @inputs = []
+  end
+
+  def store(name, value)
+    @inputs << {
+      name: name,
+      value: value
+    }
+  end
+
+  def fetch(value)
+    inputs.inject(nil) do |val, current|
+      if current[:name] == value
+        current
+      else
+        val
+      end
+    end
+  end
+end

data/lib/clingon/helpers/parser_configuration.rb

@@ -0,0 +1,43 @@
+module Clingon
+  class ParserConfiguration
+    attr_accessor :inputs, :delimiter, :strict
+    attr_reader :conf_file, :structure
+
+    def initialize
+      @delimiter = '-'
+      @strict = true
+    end
+
+    def conf_file=(file)
+      unless File.exist?(file)
+        msg = "Configuration file (#{file}) does not exist"
+        raise(Clingon::ConfigurationFileError, msg)
+      end
+      if File.directory?(file)
+        msg = "Configuration file (#{file}) is a directory"
+        raise(Clingon::ConfigurationFileError, msg)
+      end
+      if File.zero?(file)
+        msg = "Configuration file (#{file}) is empty"
+        raise(Clingon::ConfigurationFileError, msg)
+      end
+      begin
+        yaml_contents = YAML.load_file(file)
+      rescue Psych::SyntaxError => e
+        raise(Clingon::YAMLSyntaxError, e)
+      end
+      if yaml_contents.key?(:structure)
+        self.structure = yaml_contents[:structure]
+      else
+        msg = "Configuration file (#{file}) must contain :structure key"
+        raise(Clingon::ConfigurationFileError, msg)
+      end
+      self.strict = yaml_contents[:strict] if yaml_contents.key?(:strict)
+      self.delimiter = yaml_contents[:delimiter] if yaml_contents.key?(:delimiter)
+    end
+
+    def structure=(struct)
+      @structure = StructureChecker.check(struct)
+    end
+  end
+end

data/lib/clingon/helpers/structure_checker.rb

@@ -0,0 +1,24 @@
+module StructureChecker
+  def self.check(structure)
+    raise('Structure must be an array') unless structure.instance_of?(Array)
+    StructureChecker.verify_contents(structure)
+    structure
+  end
+
+  def self.verify_contents(structure)
+    structure.each do |el|
+      raise('Each element of structure must contain name key') unless el[:name]
+      if el[:type]
+        valid = [
+          'int',
+          'float',
+          'num',
+          'bool'
+        ]
+        unless valid.include?(el[:type])
+          raise("Valid types are: #{valid.join(', ')}")
+        end
+      end
+    end
+  end
+end

data/lib/clingon/version.rb

@@ -0,0 +1,3 @@
+module Clingon
+  VERSION = '0.0.1'.freeze
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: clingon
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Mario Lopez
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-04-06 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  Clingon is a parser for command line inputs. It can help you parse flags,
+      and options for your script, as well as convert user inputs to specific ruby
+      types. With clingon you can forget about dealing with user inputs, and focus
+      on adding functionality to your scripts.
+email: lopezrobles.mario@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- README.md
+- lib/clingon.rb
+- lib/clingon/checks/checks.rb
+- lib/clingon/checks/type_regex.rb
+- lib/clingon/errors.rb
+- lib/clingon/helpers/input_store.rb
+- lib/clingon/helpers/parser_configuration.rb
+- lib/clingon/helpers/structure_checker.rb
+- lib/clingon/version.rb
+homepage: https://github.com/mardotio/clingon
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.2
+signing_key: 
+specification_version: 4
+summary: Flexible command line parser.
+test_files: []