simple_scripting 0.9.0

data/README.md

@@ -0,0 +1,87 @@
+[![Build Status][BS img]](https://travis-ci.org/saveriomiroddi/simple_scripting)
+
+# SimpleScripting
+
+`SS` is a library composed of two modules (`Argv` and `Configuration`) which simplify two common scripting tasks:
+
+- implementing the commandline options parsing (and the related help)
+- loading and decoding the configuration for the script/application
+
+`SS` is an interesting (and useful) exercise in design, aimed at finding the simplest and most expressive data/structures which accomplish the given task(s). For this reason, the library can be useful for people who frequently write small scripts (eg. devops or nerds).
+
+## SimpleScripting::Argv
+
+`SS::A` is a module which acts as frontend to the standard Option Parser library (`optparse`), giving a very convenient format for specifying the arguments. `SS::A` also generates the help.
+
+This is a definition example:
+
+    result = SimpleOptParse::Argv.decode(
+      ['-s', '--only-scheduled-days',     'Only print scheduled days'                           ],
+      ['-d', '--print-defaults TEMPLATE', 'Print the default activities from the named template'],
+      'schedule',
+      '[weeks]',
+      long_help: 'This is the long help! It can span multiple lines.'
+    )
+
+which:
+
+- optionally accepts the `-s`/`--only-scheduled-days` switch, interpreting it as boolean,
+- optionally accepts the `-d`/`--print-defaults` switch, interpreting it as string,
+- requires the `schedule` argument,
+- optionally accepts the `weeks` argument,
+- automatically adds the `-h` and `--help` switches,
+- prints all the options and the long help if the help is invoked,
+- prints the help and exits if invalid parameters are passed (eg. too many).
+
+This is a sample result:
+
+    {
+      only_scheduled_days: true,
+      print_defaults:      'my_defaults',
+      schedule:            'schedule.txt',
+      weeks:               '3',
+    }
+
+This is the corresponding help:
+
+    Usage: tmpfile [options] <schedule> [<weeks>]
+        -s, --only-scheduled-days        Only print scheduled days
+        -d, --print-defaults TEMPLATE    Print the default activities from the named template
+        -h, --help                       Help
+
+    This is the long help! It can span multiple lines.
+
+For the guide, see the [wiki page](https://github.com/saveriomiroddi/simple_scripting/wiki/SimpleScripting::Argv-Guide).
+
+## SimpleScripting::Configuration
+
+`SS::C` is a module which acts as frontend to the ParseConfig gem (`parseconfig`), giving compact access to the configuration and its values, and adding a few helpers for common tasks.
+
+Say one writes a script (`foo_my_bar.rb`), with a corresponding (`$HOME/.foo_my_bar`) configuration, which contains:
+
+    some_relative_file_path=foo
+    some_absolute_file_path=/path/to/bar
+    my_password=uTxllKRD2S+IH92oi30luwu0JIqp7kKA
+
+    [a_group]
+    group_key=baz
+
+This is the workflow and functionality offered by `SS::C`:
+
+    # Picks up automatically the configuration file name, based on the calling program
+    #
+    configuration = SimpleScripting::Configuration.load(passwords_key: 'encryption_key')
+
+    configuration.some_relative_file_path.full_path # '$HOME/foo'
+    configuration.some_absolute_file_path           # '/path/to/bar'
+    configuration.some_absolute_file_path.full_path # '/path/to/bar' (recognized as absolute)
+
+    configuration.my_password.decrypted             # 'encrypted_value'
+
+    configuration.a_group.group_key                 # 'baz'; also supports #full_path and #decrypted
+
+### Encryption note
+
+The purpose of encryption in this library is just to avoid displaying passwords in plaintext; it's not considered safe against attacks.
+
+[BS img]: https://travis-ci.org/saveriomiroddi/simple_scripting.svg?branch=master

data/Rakefile

@@ -0,0 +1,5 @@
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/simple_scripting/argv.rb

@@ -0,0 +1,126 @@
+require 'optparse'
+
+module SimpleScripting
+
+  module Argv
+
+    extend self
+
+    def decode(*params_definition, arguments: ARGV, long_help: nil, output: $stdout)
+      # If the param is a Hash, we have multiple commands. We check and if the command is correct,
+      # recursively call the function with the specific parameters.
+      #
+      if params_definition.first.is_a?(Hash)
+        command = arguments.shift
+        commands_definition = params_definition.first
+
+        if command == '-h' || command == '--help'
+          print_optparse_commands_help(commands_definition, output, false)
+          output == $stdout ? exit : return
+        end
+
+        command_params_definition = commands_definition[command]
+
+        if command_params_definition.nil?
+          print_optparse_commands_help(commands_definition, output, true)
+          output == $stdout ? exit : return
+        else
+          return [command, decode(*command_params_definition, arguments: arguments, output: output)]
+        end
+      end
+
+      result           = {}
+      parser_opts_ref  = nil  # not available outside the block
+      args             = {}   # { 'name' => mandatory? }
+
+      OptionParser.new do | parser_opts |
+        params_definition.each do | param_definition |
+          case param_definition
+          when Array
+            if param_definition[1] && param_definition[1].start_with?('--')
+              key = param_definition[1].split(' ')[0][2 .. -1].gsub('-', '_').to_sym
+            else
+              key = param_definition[0][1 .. -1].to_sym
+            end
+
+            parser_opts.on(*param_definition) do |value|
+              result[key] = value || true
+            end
+          when String
+            if param_definition.start_with?('[')
+              arg_name = param_definition[1 .. -2].to_sym
+
+              args[arg_name] = false
+            else
+              arg_name = param_definition.to_sym
+
+              args[arg_name] = true
+            end
+          else
+            raise "Unrecognized value: #{param_definition}"
+          end
+        end
+
+        parser_opts.on( '-h', '--help', 'Help' ) do
+          print_optparse_help( parser_opts, args, long_help, output )
+          output == $stdout ? exit : return
+        end
+
+        parser_opts_ref = parser_opts
+      end.parse!(arguments)
+
+      first_arg_name = args.keys.first.to_s
+
+      # Varargs
+      if first_arg_name.start_with?('*')
+        # Mandatory?
+        if args.fetch(first_arg_name.to_sym)
+          if arguments.empty?
+            print_optparse_help( parser_opts_ref, args, long_help, output )
+            output == $stdout ? exit : return
+          else
+            name = args.keys.first[ 1 .. - 1 ].to_sym
+
+            result[ name ] = arguments
+          end
+        # Optional
+        else
+          name = args.keys.first[ 1 .. - 1 ].to_sym
+
+          result[ name ] = arguments
+        end
+      else
+        min_args_size = args.count { | name, mandatory | mandatory }
+
+        case arguments.size
+        when (min_args_size .. args.size)
+          arguments.zip(args) do | value, (name, mandatory) |
+            result[name] = value
+          end
+        else
+          print_optparse_help(parser_opts_ref, args, long_help, output)
+          output == $stdout ? exit : return
+        end
+      end
+
+      result
+    end
+
+    private
+
+    def print_optparse_commands_help(commands_definition, output, is_error)
+      output.print "Invalid command. " if is_error
+      output.puts "Valid commands:", "", "  " + commands_definition.keys.join(', ')
+    end
+
+    def print_optparse_help(parser_opts, args, long_help, output)
+      args_display = args.map { | name, mandatory | mandatory ? "<#{ name }>" : "[<#{ name }>]" }.join(' ')
+      parser_opts_help = parser_opts.to_s.sub!(/^(Usage: .*)/, "\\1 #{args_display}")
+
+      output.puts parser_opts_help
+      output.puts "", long_help if long_help
+    end
+
+  end
+
+end

data/lib/simple_scripting/configuration.rb

@@ -0,0 +1,46 @@
+require_relative 'configuration/value'
+
+require 'ostruct'
+require 'parseconfig'
+
+module SimpleScripting
+
+  module Configuration
+
+    extend self
+
+    def load(config_file: default_config_file, passwords_key: nil)
+      configuration = ParseConfig.new(config_file)
+
+      convert_to_cool_format(OpenStruct.new, configuration.params, passwords_key)
+    end
+
+    private
+
+    def default_config_file
+      base_config_filename = '.' + File.basename($PROGRAM_NAME).chomp('.rb')
+
+      File.expand_path(base_config_filename, '~')
+    end
+
+    # Performs two conversions:
+    #
+    # 1. the configuration as a whole is converted to an OpenStruct
+    # 2. the values are converted to SimpleScripting::Configuration::Value
+    #
+    def convert_to_cool_format(result_node, configuration_node, encryption_key)
+      configuration_node.each do |key, value|
+        if value.is_a?(Hash)
+          result_node[key] = OpenStruct.new
+          convert_to_cool_format(result_node[key], value, encryption_key)
+        else
+          result_node[key] = Value.new(value, encryption_key)
+        end
+      end
+
+      result_node
+    end
+
+  end
+
+end

data/lib/simple_scripting/configuration/value.rb

@@ -0,0 +1,61 @@
+require 'openssl'
+require 'base64'
+
+module SimpleScripting
+
+  module Configuration
+
+    # The purpose of encryption in this library is just to avoid displaying passwords in
+    # plaintext; it's not considered safe against attacks.
+    #
+    class Value < String
+
+      ENCRYPTION_CIPHER = 'des3'
+
+      def initialize(string, encryption_key = nil)
+        super(string)
+
+        if encryption_key
+          @encryption_key = encryption_key + '*' * (24 - encryption_key.bytesize)
+        end
+      end
+
+      def full_path
+        start_with?('/') ? self : File.expand_path(self, '~')
+      end
+
+      def decrypted
+        raise "Encryption key not provided!" if @encryption_key.nil?
+
+        ciphertext = Base64.decode64(self)
+
+        cipher = OpenSSL::Cipher::Cipher.new(ENCRYPTION_CIPHER)
+        cipher.decrypt
+
+        cipher.key = @encryption_key
+
+        cipher.iv = ciphertext[0...cipher.iv_len]
+        plaintext = cipher.update(ciphertext[cipher.iv_len..-1]) + cipher.final
+
+        plaintext
+      end
+
+      def encrypted
+        cipher = OpenSSL::Cipher::Cipher.new(ENCRYPTION_CIPHER)
+        cipher.encrypt
+
+        iv = cipher.random_iv
+
+        cipher.key = @encryption_key
+        cipher.iv  = iv
+
+        ciphertext = iv + cipher.update(self) + cipher.final
+
+        Base64.encode64(ciphertext).rstrip
+      end
+
+    end
+
+  end
+
+end

data/lib/simple_scripting/version.rb

@@ -0,0 +1,5 @@
+module SimpleScripting
+
+  VERSION = "0.9.0"
+
+end

data/simple_scripting.gemspec

@@ -0,0 +1,28 @@
+# encoding: UTF-8
+
+$LOAD_PATH << File.expand_path("../lib", __FILE__)
+
+require "simple_scripting/version"
+
+Gem::Specification.new do |s|
+  s.name        = "simple_scripting"
+  s.version     = SimpleScripting::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ["Saverio Miroddi"]
+  s.date        = "2017-06-27"
+  s.email       = ["saverio.pub2@gmail.com"]
+  s.homepage    = "https://github.com/saveriomiroddi/simple_scripting"
+  s.summary     = "Library for simplifying some typical scripting functionalities."
+  s.description = "Simplifies options parsing and configuration loading."
+  s.license     = "GPL-3.0"
+
+  s.add_runtime_dependency     "parseconfig", "~> 1.0"
+
+  s.add_development_dependency "rake",        "~> 12.0"
+  s.add_development_dependency "rspec",       "~> 3.6"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- spec/*`.split("\n")
+  s.executables   = []
+  s.require_paths = ["lib"]
+end

data/spec/simple_scripting/argv_spec.rb

@@ -0,0 +1,222 @@
+require_relative '../../lib/simple_scripting/argv.rb'
+
+require 'stringio'
+
+describe SimpleScripting::Argv do
+
+  let(:output_buffer) do
+    StringIO.new
+  end
+
+  describe 'Basic functionality' do
+
+    let(:decoder_params) {[
+      ['-a'                                        ],
+      ['-b',                     '"-b" description'],
+      ['-c', '--c-switch'                          ],
+      ['-d', '--d-switch',       '"-d" description'],
+      ['-e', '--e-switch VALUE'                    ],
+      ['-f', '--f-switch VALUE', '"-f" description'],
+      'mandatory',
+      '[optional]',
+      long_help: 'This is the long help!',
+      output:     output_buffer,
+    ]}
+
+    it 'should implement the help' do
+      decoder_params.last[:arguments] = ['-h']
+
+      described_class.decode(*decoder_params)
+
+      expected_output = %Q{\
+Usage: rspec [options] <mandatory> [<optional>]
+    -a
+    -b                               "-b" description
+    -c, --c-switch
+    -d, --d-switch                   "-d" description
+    -e, --e-switch VALUE
+    -f, --f-switch VALUE             "-f" description
+    -h, --help                       Help
+
+This is the long help!
+}
+
+      expect(output_buffer.string).to eql(expected_output)
+    end
+
+    it "should implement basic switches and arguments (all set)" do
+      decoder_params.last[:arguments] = ['-a', '-b', '-c', '-d', '-ev_swt', '-fv_swt', 'm_arg', 'o_arg']
+
+      actual_result = described_class.decode(*decoder_params)
+
+      expected_result = {
+        a:          true,
+        b:          true,
+        c_switch:   true,
+        d_switch:   true,
+        e_switch:   'v_swt',
+        f_switch:   'v_swt',
+        mandatory:  'm_arg',
+        optional:   'o_arg',
+      }
+
+      expect(actual_result).to eql(expected_result)
+    end
+
+    it "should implement basic switches and arguments (no optional argument)" do
+      decoder_params.last[:arguments] = ['m_arg']
+
+      actual_result = described_class.decode(*decoder_params)
+
+      expected_result = {
+        mandatory: 'm_arg',
+      }
+
+      expect(actual_result).to eql(expected_result)
+    end
+
+  end
+
+  describe 'Varargs' do
+
+    describe '(mandatory)' do
+
+      let(:decoder_params) {[
+        '*varargs',
+        output:     output_buffer,
+      ]}
+
+      it "should be decoded" do
+        decoder_params.last[:arguments] = ['varval1', 'varval2']
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = {
+          varargs:   ['varval1', 'varval2'],
+        }
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+      it "should exit when they are not specified" do
+        decoder_params.last[:arguments] = []
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = nil
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+    end
+
+    describe '(optional)' do
+
+      let(:decoder_params) {[
+        '[*varargs]',
+        output:     output_buffer,
+      ]}
+
+      it "should be decoded" do
+        decoder_params.last[:arguments] = ['varval1', 'varval2']
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = {
+          varargs:   ['varval1', 'varval2'],
+        }
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+      it "should be allowed not to be specified" do
+        decoder_params.last[:arguments] = []
+
+        actual_result = described_class.decode(*decoder_params)
+
+        expected_result = {
+          varargs:   [],
+        }
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+    end
+
+  end
+
+  describe 'Multiple commands' do
+
+    describe 'regular case' do
+
+      let(:decoder_params) {{
+        'command1' => [
+          'arg1'
+        ],
+        'command2' => [
+          'arg2'
+        ],
+        output:     output_buffer,
+      }}
+
+      it 'should be decoded' do
+        decoder_params[:arguments] = ['command1', 'value1']
+
+        actual_result = described_class.decode(decoder_params)
+
+        expected_result = ['command1', arg1: 'value1']
+
+        expect(actual_result).to eql(expected_result)
+      end
+
+      it 'print a message on wrong command' do
+        decoder_params[:arguments] = ['pizza']
+
+        described_class.decode(decoder_params)
+
+        expected_output = %Q{\
+Invalid command. Valid commands:
+
+  command1, command2
+}
+
+        expect(output_buffer.string).to eql(expected_output)
+      end
+
+      it 'should implement the help' do
+        decoder_params[:arguments] = ['-h']
+
+        described_class.decode(decoder_params)
+
+        expected_output = %Q{\
+Valid commands:
+
+  command1, command2
+}
+
+        expect(output_buffer.string).to eql(expected_output)
+      end
+
+    end
+
+    describe 'pitfall' do
+
+      let(:decoder_params) {{
+        output:     output_buffer,
+      }}
+
+      # Make sure that the options (in this case, :output) are not interpreted as commands definition.
+      #
+      it 'should be avoided' do
+        decoder_params[:arguments] = ['pizza']
+
+        actual_result = described_class.decode(decoder_params)
+
+        expect(actual_result).to be(nil)
+      end
+
+    end
+
+  end
+
+end