simple_cli 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5768544b4fccdc2dbb36b729e523b1aa81b74766
-  data.tar.gz: 940525cc250b4e256fa69c7e4233f34a01afb8c9
+  metadata.gz: 6d5397a030dc3cbe0065b382f3c82396e11dd3bb
+  data.tar.gz: b9abf7884e67d5714cde8a845613868bae36023a
 SHA512:
-  metadata.gz: 96ac5469e10c38bf40de54005938e28048ae4030d32ca9ae5f7246abf1180e799598b748bc6395e68b9f3d0ea9143fef678a0aabeecc9b507bb0eb586595d02a
-  data.tar.gz: cb8b4fb40c64b396cf6a307b5fe64de3ce9849e8a209b267f152a4d5aba1d4a442167746f4a349a06f6d192a9cde81224042dec0e14c439eb28be92298a9f49d
+  metadata.gz: e9dd2c16e2d19fbdfa952889c36515fe73269d54d5212e4c9dc4848da972ee32c81c75578207a4a5c7ebac973c0ea8df99145fbb0dc9d5747db36fe1eae4840a
+  data.tar.gz: 3d1a6b579b22c0fb80af1a5c73db31f945712ada8c15f116a8cbbc54f58c0762f9addf514fd76174b367ae1fb8c84428051e2b69bb8186647c5f68940b438df9

data/README.md

@@ -1,2 +1,61 @@
 # simple_cli
-A very opinionated Ruby library for building CLI tools. Extracted from my simple_configure project. 
+A very opinionated Ruby library for parsing CLI input. Extracted from my simple_configure project.
+
+## What exactly is simple_cli?
+simple_cli at its core is a command line parsing library combined with a little bit of magic. It takes a very declarative approach to building CLI tools. You describe your CLI tool in a json file. simple_cli takes that json file and Ruby's `ARGV` as parameters and builds a scaffold for your CLI tool. It outputs a Hash of options parsed from the CLI input if the CLI input is valid or else it outputs a help message. It allows you to focus only on the core of your CLI tool instead of focusing on parsing CLI options. 
+
+## Installation
+You can install simple_cli by running
+```
+gem install simple_cli
+```
+
+## Documentation
+To use simple_cli in a project, require the `simple_cli` module
+```ruby
+require 'simple_cli`
+```
+
+This should provide you access to the `SimpleCli` module. `SimpleCli` module has a `SimpleCliBuilder` class that can be used to develop a CLI parser. `SimpleCliBuilder` takes in two arguments. First one is a json file and the second one is the `ARGV` parameter from Ruby. Here is a simple CLI tool using this method
+
+```ruby
+#!/usr/bin/env ruby
+
+# This code was taken from https://github.com/lsegal/yard/blob/master/bin/yard. The code is licensed under the MIT License.
+
+# We do all this work just to find the proper load path
+path = __FILE__
+while File.symlink?(path)
+  path = File.expand_path(File.readlink(path), File.dirname(path))
+end
+$:.unshift(File.join(File.dirname(File.expand_path(path)), '..', 'lib'))
+
+require 'testcli'
+require 'simple_cli'
+
+parsed_cli_args = SimpleCliBuilder.new("testcli.json",ARGV)
+TestCli.run(parsed_cli_args)
+```
+
+### JSON File Format
+
+This file is at the heart of simple_cli. You declare all the parts of your CLI tool in this JSON file. This file helps the `SimpleCliBuilder` to extract information from the CLI input and present it to the tool in a meaningful way. The following are the available options that can be included inside the JSON file. 
+
+1. **name** - required - Name of the command line tool. This will be displayed in the automatically generated help message. 
+2. **description** - required - Description of the command line tool. This will be displayed in the automatically generated help message. 
+3. **commands** - required - This parameter should be a JSON object with all the commands in the command line tool. 
+
+## Errors
+`simple_cli` is built from the ground up to make your command line tool error free. It will do a lot of error checking while your tool is in development. So you might run into the following errors when you use `simple_cli` with your CLI tool. The error messages are in the process of being rewritten to make it explicit that these are errors caused by developers not the users. 
+
+### JSONFileNonExistantError
+This error indicates that the JSON file provided doesn't exist. With out the JSON file, `simple_cli` cannot proceed any further. 
+
+### UnParsableJSONError
+This error indicates that the JSON file provided is not a valid JSON. Please use a tool like http://jsonlint.com/ to fix the problems with your JSON. 
+
+### EmptyJSONError
+This error indicates that the JSON file provided is empty.There is nothing in a empty JSON file to configure `simple_cli`. So please add some configurations into that JSON file. 
+
+### NoNameError
+This error indicates that the `name` parameter is missing from the JSON file. The `name` parameter is very important because it will be displayed in the automatically generated help message. 

data/lib/simple_cli/core.rb

@@ -1,18 +1,100 @@
 require 'json'
+require_relative 'error'
+
 module SimpleCli
-  class SimpleCliBuilder
-    def initialize(config_file)
-      @allowable_arguments = config_file
-    end
+    class SimpleCliBuilder
+      def initialize(config_file, argv = [])
+        @config, @available_commands = parse_allowable_arguments(config_file)
+        @raw_argv = argv
+        @parsed_argv = parse_argv
+      end
+
+      private
+
+      def error_message(command)
+        return "Error: #{command} is not a valid command/option/argument!"
+      end
+
+      def build_help_message(config)
+        message = "Usage: #{config["name"]}\n"
+        message += "\n"
+        message += "#{config["description"]}\n"
+        message += "\n"
+        return message
+      end
+
+      def version_message(config)
+        message = "#{config["name"]} version #{config["version"]}\n\n"
+        return message
+      end
+
+      def parse_allowable_arguments(config_file)
+        user_note = "User Note: The developer made a mistake. So this tool is not currently functional!"
+        if File.exist?(config_file)
+          file = File.read(config_file)
+        else
+          raise JSONFileNonExistantError, "Developer Note: The JSON file you provided doesn't exist. Please provide a valid JSON file!\n" + user_note
+        end
+
+        begin
+          json_data = JSON.parse(file)
+        rescue
+          raise UnParsableJSONError, "Developer Note: The JSON file you provided is not a valid JSON file. Please fix this issue!\n" + user_note
+        end
+        return verify_config_file(json_data)
+      end
+
+      def verify_config_file(config)
+        user_note = "User Note: The developer made a mistake. So this tool is not currently functional!"
+
+        if config == {}
+          raise EmptyJSONError, "Developer Note: The JSON file you provided is empty. Please fix this issue!\n" + user_note
+        end
+
+        if config["name"].nil?
+          raise NoNameError, "Developer Note: A CLI app requires a name. But no name has been provided. Please fix this issue!\n" + user_note
+        elsif config["description"].nil?
+          raise NoDescriptionError, "Developer Note: A CLI app requires a description. But no description has been provided. Please fix this issue!\n" + user_note
+        elsif config["commands"].nil?
+          raise NoCommandsError, "Developer Note: A CLI app requires a list of commands. But no commands have been provided. Please fix this issue! If your CLI tool doesn't take any commands, please use the no_command option inside the commands object to indicate that behavior\n" + user_note
+        elsif config["commands"] == {}
+          raise EmptyCommandsError, "Developer Note: A CLI app requires a list of commands. You have provided a commands object. But it is empty. Please fix this issue!\n" + user_note
+        end
+
+        available_commands = {}
 
-    private
+        config["commands"].keys.each do |key|
+          if key != "no_command"
+            available_commands[key] = key
+            command = config["commands"][key]
+            unless command["alias"].nil?
+              available_commands[command["alias"]] = key
+            end
+          end
+        end
 
-    def parse_allowable_arguments(config_file)
-      return JSON.parse(config_file)
-    end
+        return config, available_commands
 
-    def verify_config_file
+      end
 
-    end
+      def parse_argv
+        parsed_argv = {}
+        @raw_argv.each do |arg|
+          case arg
+          when "-h", "--help", "help"
+            puts build_help_message(@config)
+          when "-v", "--version", "version"
+            puts version_message(@config)
+          when !@available_commands[arg].nil?
+            parsed_argv[available_commands[arg]] = true
+          else
+            puts "\n"
+            puts error_message(arg)
+            puts "\n"
+            abort
+          end
+        end
+        return parsed_argv
+      end
   end
 end

data/lib/simple_cli/error.rb

@@ -0,0 +1,20 @@
+class JSONFileNonExistantError < StandardError
+end
+
+class NoNameError < StandardError
+end
+
+class UnParsableJSONError < StandardError
+end
+
+class EmptyJSONError < StandardError
+end
+
+class NoDescriptionError < StandardError
+end
+
+class NoCommandsError < StandardError
+end
+
+class EmptyCommandsError < StandardError
+end

data/lib/simple_cli/version.rb

@@ -1,3 +1,3 @@
 module SimpleCli
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple_cli
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Adhithya Rajasekaran
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-06-14 00:00:00.000000000 Z
+date: 2015-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -69,6 +69,7 @@ files:
 - Rakefile
 - lib/simple_cli.rb
 - lib/simple_cli/core.rb
+- lib/simple_cli/error.rb
 - lib/simple_cli/version.rb
 - simple_cli.gemspec
 homepage: ''