cli-console 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile

@@ -0,0 +1,10 @@
+source 'http://rubygems.org'
+
+group :development, :test do
+    gem 'highline', '=> 1.6.16'
+    gem 'rspec'
+    gem 'simplecov'
+    gem 'yard'
+    gem 'redcarpet'
+end
+

data/README.md

@@ -0,0 +1,65 @@
+# CLI::Console
+
+
+Basic library for making interactive command-line applications much easier.
+
+
+## Features
+
+* Easy way to add commands and help info to them so it can be shown to user.
+* Auto-completion for commands.
+* Command aliasing.
+
+
+## Installation
+
+Simply
+
+    `gem install cli-console`
+
+### Dependecies
+
+This library doesn't have any dependencies.
+Well actually there's no direct dependencies.
+But in reality need HighLine and Readline.
+Then why I said there's no dependencies?
+Because `CLI::Console` will accept any IO class with implements those few functions which currently are provided by HighLine.
+
+
+## Usage Example
+
+Take a look at [/examples/shell.rb](/davispuh/examples/shell.rb)
+
+
+## Documentation
+
+YARD with markdown is used for documentation (`redcarpet` required)
+
+## Specs
+
+RSpec and simplecov are required, to run tests just `rake spec`
+code coverage will also be generated
+
+## Authors
+
+Currently everything (all functions, files, text) in this repository are made by me @davispuh and I've dedicated this repository to public domain.
+
+
+## Unlicense
+
+All text, documentation, code and files in this repository are in public domain (including this text, README).
+It means you can copy, modify, distribute and include in your own work/code, even for commercial purposes, all without asking permission.
+
+
+## Contributing
+
+Feel free to improve anything what you see is improvable.
+
+
+**Warning**: By sending pull request to this repository you dedicate any and all copyright interest in pull request (code files and all other) to the public domain. (files will be in public domain even if pull request doesn't get merged)
+
+Also before sending pull request you acknowledge that you own all copyrights or have authorization to dedicate them to public domain.
+
+If you don't want to dedicate code to public domain or if you're not allowed to (eg. you don't own required copyrights) then DON'T send pull request.
+
+

data/Rakefile

@@ -0,0 +1,10 @@
+require 'rspec/core/rake_task'
+
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc 'Run specs'
+RSpec::Core::RakeTask.new(:spec) do |t|
+end
+

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+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 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.
+
+For more information, please refer to <http://unlicense.org/>

data/cli-console.gemspec

@@ -0,0 +1,20 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'cli-console/version'
+
+
+Gem::Specification.new do |gem|
+    gem.name          = 'cli-console'
+    gem.version       = CLI::Console::VERSION
+    gem.authors       = ['Dāvis']
+    gem.email         = ['davispuh@gmail.com']
+    gem.description   = 'Basic library for making interactive command-line applications much easier'
+    gem.summary       = 'Create CLI applications easily'
+    gem.homepage      = 'https://github.com/davispuh/CLI-Console'
+
+    gem.files         = `git ls-files`.split($/)
+    gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+    gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+    gem.require_paths = ['lib']
+end

data/examples/shell.rb

@@ -0,0 +1,46 @@
+require 'highline'
+require 'cli-console'
+
+
+class ShellUI
+    private
+    extend CLI::Task
+
+    public
+
+    usage 'Usage: ls'
+    desc 'List file information about current directory'
+    def ls(params)
+        Dir.foreach(Dir.pwd) do |file|
+            puts file
+        end
+    end
+
+    usage 'Usage: pwd'
+    desc 'Display current directory'
+
+    def pwd(params)
+        puts "Current directory: #{Dir.pwd}"
+    end
+
+    usage 'Usage: cd <Directory>'
+    desc 'Change current directory'
+
+    def cd(params)
+        Dir.chdir(params[0]) unless params.empty?
+    end
+end
+
+io = HighLine.new
+shell = ShellUI.new
+console = CLI::Console.new(io)
+
+console.addCommand('ls', shell.method(:ls), 'List files')
+console.addCommand('pwd', shell.method(:pwd), 'Current directory')
+console.addCommand('cd', shell.method(:cd), 'Change directory')
+console.addHelpCommand('help', 'Help')
+console.addExitCommand('exit', 'Exit from program')
+console.addAlias('quit', 'exit')
+
+console.start("%s> ",[Dir.method(:pwd)])
+

data/lib/cli-console.rb

@@ -0,0 +1,301 @@
+require 'cli-console/version'
+require 'cli-console/task'
+
+
+# Command-line interface module
+module CLI
+    # Console class
+    #
+    # ```ruby
+    #   # io some input/output class (like HighLine)
+    #   console = CLI::Console.new(io)
+    # ```
+    class Console
+        private
+        def initialize(io)
+            @Commands = {}
+            @Aliases = {}
+            @IO = io
+            @Seperator = '-'
+            @SepCount = 30
+            @Backtrace = false
+            @Partial = true
+            @ExitCode = -100
+            @UseReadline = true
+        end
+
+        # Outputs nicely formated exception
+        # displays backtrace if @Backtrace
+        # @param [Exception] exception to display
+        def showException(exception)
+            @IO.say "Exception: #{exception.message.strip}"
+            if @Backtrace
+                @IO.say 'Backtrace:'
+                @IO.indent do |io|
+                    exception.backtrace.each do |b|
+                        io.say b
+                    end
+                end
+            end
+        end
+
+        public
+        attr_accessor :Partial
+        attr_accessor :ExitCode
+        attr_accessor :Seperator
+        attr_accessor :SepCount
+        attr_accessor :Backtrace
+        attr_accessor :UseReadline
+
+        # Adds command
+        # @param commandName [String] name of command
+        # @param command [Method] command method
+        # @param commandDescription [String] short description about command
+        # @param commandLongDescription [String] long description about command
+        # @param commandUsage [String] usage information about command
+        # @return [Array] command information
+        def addCommand(commandName, command, commandDescription='', commandLongDescription = nil, commandUsage = nil)
+            commandLongDescription = command.owner.get_description(command.name) if commandLongDescription == nil
+            commandUsage = command.owner.get_usage(command.name) if commandUsage == nil
+            @Commands[commandName] = [command, commandDescription, commandLongDescription, commandUsage]
+        end
+
+        # Adds name for exit command
+        # @param commandName [String] name of exit command
+        # @param commandDescription [String] short description about command
+        # @param commandLongDescription [String] long description about command
+        # @param commandUsage [String] usage information about command
+        # @return [Array] command information
+        def addExitCommand(commandName, commandDescription='', commandLongDescription = nil, commandUsage = nil)
+            commandLongDescription = 'Exit...' unless commandLongDescription
+            commandUsage = ['exit'] unless commandUsage
+            @Commands[commandName] = [method(:end), commandDescription, commandLongDescription, commandUsage]
+        end
+
+        # Adds name for help command
+        # @param commandName [String] name of exit command
+        # @param commandDescription [String] short description about command
+        # @param commandLongDescription [String] long description about command
+        # @param commandUsage [String] usage information about command
+        # @return [Array] command information
+        def addHelpCommand(commandName, commandDescription='', commandLongDescription = nil, commandUsage = nil)
+            commandLongDescription = 'Display Help for <command>' unless commandLongDescription
+            commandUsage = ['help <command>'] unless commandUsage
+            @Commands[commandName] = [method(:help), commandDescription, commandLongDescription, commandUsage]
+        end
+
+        # Adds alias for command
+        # @param aliasName [String] name of for alias
+        # @param commandNameParms [String] command to alias
+        # @param commandDescription [String] short description about alias
+        # @param commandLongDescription [String] long description about alias
+        # @param commandUsage [String] usage information about alias
+        # @return [Array] alias information
+        def addAlias(aliasName, commandNameParms, commandDescription=nil, commandLongDescription = nil, commandUsage = nil)
+            @Aliases[aliasName] = [commandNameParms, commandDescription, commandLongDescription, commandUsage]
+        end
+
+        # Waits till user enters command
+        # @param inputText [String] text to show to user
+        # @return [String] entered command
+        def getCommand(inputText)
+            @LastCommand = @IO.ask(inputText) do |h|
+                h.whitespace = :strip_and_collapse
+                h.validate = nil
+                h.readline = @UseReadline
+                h.completion = @Commands.keys+@Aliases.keys
+            end
+            @LastCommand = '' if (not @LastCommand.to_s.empty? and @LastCommand[0] == '#')
+            return @LastCommand
+        end
+
+        # @param command [String]
+        # @return [Array]
+        def commandMatch(command)
+            matches = []
+            commandStrings = @Commands.merge(@Aliases)
+            commandStrings.each do |key, value|
+                matches.push([key, value]) if (@Partial and key.start_with?(command)) or key == command
+            end
+            matches
+        end
+
+        # displays matched commands
+        # @param matches [Array]
+        def showMatches(matches)
+            @IO.say('Matches:')
+            matches.each do |value|
+                text = value[0].to_s
+                text += ' - '+value[1][1].to_s unless value[1][1].to_s.empty?
+                @IO.indent(1, text )
+            end
+        end
+
+        # Executes command with parameters
+        # @param commandString [String]
+        # @return command result or error number
+        def processCommand(commandString)
+            return 0 if commandString.to_s.empty?
+            commandWords = []
+            commandString.scan(/([^\s"']+)|"([^"]*)"|'([^']*)'/) do |m|
+                commandWords << m[0] unless m[0].nil?
+                commandWords << m[1] unless m[1].nil?
+                commandWords << m[2] unless m[2].nil?
+            end
+            command = commandWords.shift.downcase
+
+            if (not @Commands.key?(command) and not @Aliases.key?(command))
+                matches = commandMatch(command)
+                if matches.length == 1
+                    if matches[0][1][0].class == String
+                        oldCommandWords = [matches[0][1][0]]
+                    commandWords = @Aliases[matches[0][0]][0].split
+                    command = commandWords.shift.downcase
+                    commandWords += oldCommandWords
+                    else
+                    command = matches[0][0]
+                    end
+                elsif matches.length > 0
+                    @IO.say('Ambiguous command.')
+                    showMatches(matches)
+                return -3
+                else
+                    @IO.say("Command \"#{command}\" not recognized.")
+                return -2
+                end
+            elsif @Aliases.key?(command)
+            oldCommandWords = commandWords
+            commandWords = @Aliases[command][0].split
+            command = commandWords.shift.downcase
+            commandWords += oldCommandWords
+            end
+            begin
+                return @Commands[command][0].call(commandWords)
+            rescue Exception => e
+                showException(e)
+            end
+            return -1
+        end
+
+        # Starts main CLI loop, waits for user input
+        # @param formatString [String]
+        # @param formatValues [Array]
+        # @return [Fixnum]
+        def start(formatString, formatValues)
+            indent_level = @IO.indent_level
+            loop do
+                begin
+                    currentValues = []
+                    formatValues.each do |value|
+                        if value.respond_to?("call")
+                        currentValues.push(value.call)
+                        else
+                        currentValues.push(value)
+                        end
+                    end
+                    command = getCommand( formatString % currentValues )
+                    @IO.indent_level+=1
+                    result = processCommand(command)
+                    @IO.indent_level-=1
+                    return 0 if result == @ExitCode
+                rescue Exception => e
+                    showException(e)
+                @IO.indent_level=indent_level
+                end
+            end
+            -1
+        end
+
+        # Displays seperator line
+        def printSeperator
+            @IO.say(@Seperator*@SepCount)
+        end
+
+        # Displays help about command
+        # @param command [String] command for which display help
+        def commandHelp(command)
+            if @Commands.key?(command)
+                printSeperator
+                if not @Commands[command][3].to_a.empty?
+                    @IO.indent do |io|
+                        @Commands[command][3].each { |c| io.say c}
+                        io.newline
+                    end
+                end
+                @IO.say(@Commands[command][2]) unless @Commands[command][2].to_s.empty?
+                printSeperator
+            end
+        end
+
+        # Displays usage
+        def usage
+            @IO.say('Type "help" to display available commands')
+        end
+
+        # Shows message to inform how to get more information about command
+        # @param helpCommand [String] command for which display message
+        def command_usage(helpCommand='help')
+            @IO.say("You can type \"#{helpCommand} <command>\" for more info")
+        end
+
+        # Shows help information about command
+        # @param params [Array] command for which show help
+        def help(params=[])
+            if not params.to_a.empty?
+                command = params[0].downcase
+                if (not @Commands.key?(command) and not @Aliases.key?(command))
+                    matches = commandMatch command
+                    if (matches.length == 1)
+                        commandHelp(matches[0][0])
+                    elsif matches.length > 0
+                        @IO.say('Help for ambiguous command.')
+                        showMatches matches
+                    else
+                        @IO.say("Help for command \"#{params[0]}\" not found!")
+                    end
+                elsif @Aliases.key?(command)
+                    if not @Aliases[command][2].to_s.empty?
+                    @IO.say(@Aliases[command][2])
+                    else
+                        commandHelp(@Aliases[command][0].split()[0])
+                    end
+                else
+                    commandHelp(command)
+                end
+            else
+                helpCommand = 'help'
+                printSeperator
+                @IO.indent do |io|
+                    @Commands.each do |key,value|
+                        if (value[0].name != 'help')
+                            helpText = key
+                            if (not value[1].to_s.empty?)
+                                helpText += ' - '+value[1]
+                            end
+                        io.say(helpText)
+                        else
+                        helpCommand = value[0].name
+                        end
+                    end
+                    @Aliases.each do |key, value|
+                        helpText = key
+                        if (not value[1].to_s.empty?)
+                            helpText += ' - '+value[1]
+                        else
+                            helpText += ' - alias to "'+value[0]+'"'
+                        end
+                        io.say(helpText)
+                    end
+                end
+                command_usage(helpCommand)
+                printSeperator
+            end
+        end
+
+        # @param params [Array] unused
+        # @return [Fixnum]
+        def end(params=[])
+            @ExitCode
+        end
+    end
+end

data/lib/cli-console/task.rb

@@ -0,0 +1,64 @@
+module CLI
+    # Task module which must be included in class which provides commands
+    #
+    # Example:
+    #
+    # ```ruby
+    #   class UI
+    #     extend CLI::Task
+    #
+    #     usage 'Usage: command'
+    #     desc 'command desciption'
+    #
+    #     def command(params)
+    #     end
+    #
+    #   end
+    # ```
+    module Task
+        private
+        @@__usage__ = {}
+        @@__desc__ = {}
+
+        # sets usage for command
+        # @param usage [String]
+        # @return @usage
+        def usage(usage)
+            usage = [usage.to_s] unless usage.class == Array
+            @usage = usage
+        end
+
+        # sets description for command
+        # @param desc [String] description
+        # @return @desc
+        def desc(desc)
+            @desc = desc
+        end
+
+        def method_added(method)
+            name = method.to_s
+            return unless name != 'initialize' and (public_instance_methods.include?(name) or public_instance_methods.include?(name.to_sym))
+            @@__desc__[method]=@desc unless @@__desc__.key?(method)
+            @@__usage__[method]=@usage unless @@__usage__.key?(method)
+            @desc = nil
+            @usage = nil
+        end
+
+        public
+
+        # description for command
+        # @param name [String] name of command
+        # @return [String] description
+        def get_description(name)
+            return @@__desc__[name] if @@__desc__.key?(name)
+        end
+
+        # usage information for command
+        # @param name [String] name of command
+        # @return [String] usage
+        def get_usage(name)
+            return @@__usage__[name] if @@__usage__.key?(name)
+        end
+
+    end
+end

data/lib/cli-console/version.rb

@@ -0,0 +1,6 @@
+module CLI
+    class Console
+        # Version for gem
+        VERSION = "0.1.0"
+    end
+end

data/spec/cli-console_spec.rb

@@ -0,0 +1,108 @@
+require 'spec_helper'
+
+
+class UI
+    private
+    extend CLI::Task
+
+    public
+
+    usage 'Usage: try'
+    desc 'try exception'
+    def try(params)
+        raise Exception, params[0]
+    end
+end
+
+describe CLI::Console do
+    let(:input) { StringIO.new }
+    let(:output) { StringIO.new }
+    let(:io) { HighLine.new(input, output) }
+    let(:console) { CLI::Console.new(io) }
+    let(:ui) { UI.new }
+
+    def init
+        console.UseReadline = false
+        console.addCommand('try',ui.method(:try))
+        console.addHelpCommand('help')
+        console.addExitCommand('exit')
+        console.addAlias('trymore','try')
+        console.addAlias('quit','exit')
+    end
+
+    describe '#initialize' do
+        it 'should return cli-console instance' do
+            console.should be_kind_of(CLI::Console)
+        end
+    end
+
+    describe '#addCommand' do
+        it 'should return array of command data' do
+            commandData = [:test, 'short desc', 'long desc', 'usage']
+            console.addCommand('test', *commandData).should eq(commandData)
+        end
+    end
+
+    describe '#addExitCommand' do
+        it 'should return array of exit command data' do
+            commandData = [console.method(:end), 'exit', 'Exit from program', 'usage']
+            console.addExitCommand('test', commandData[1], commandData[2], commandData[3]).should eq(commandData)
+        end
+    end
+
+    describe '#addHelpCommand' do
+        it 'should return array of help command data' do
+            commandData = [console.method(:help), 'help', 'Help', 'usage']
+            console.addHelpCommand('test', commandData[1], commandData[2], commandData[3]).should eq(commandData)
+        end
+    end
+
+    describe '#addAlias' do
+        it 'should return array of help command data' do
+            commandData = ['command', 'short desc', 'long desc', 'usage']
+            console.addAlias('alias', *commandData).should eq(commandData)
+        end
+    end
+
+    describe '#usage' do
+        it 'should display usage' do
+            console.usage
+            output.string.should eq("Type \"help\" to display available commands\n")
+        end
+    end
+
+    describe '#processCommand' do
+        it 'should execute succesfully' do
+            init
+            console.processCommand('tr')
+            console.processCommand('try more')
+            console.processCommand('q')
+            console.processCommand('quit')
+            console.processCommand('help')
+            console.processCommand('help tr')
+            console.processCommand('help try')
+            console.processCommand('help not')
+            console.processCommand('help e')
+        end
+    end
+
+    describe '#start' do
+        def left
+            'left'
+        end
+
+        it 'should start CLI' do
+            input << "try lol\nnot found\nexit\n"
+            input.rewind
+            init
+            console.start('%s> ',[method(:left)]).should eq(0)
+            out = 'left>    Exception: lol
+left>    Command "not" not recognized.
+left> '
+
+            output.string.should eq(out)
+        end
+    end
+
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+require 'simplecov'
+
+
+SimpleCov.start
+
+require_relative '../lib/cli-console.rb'
+require 'highline'
+
+
+if HighLine::CHARACTER_MODE == "Win32API"
+  class HighLine
+    # Override Windows' character reading so it's not tied to STDIN.
+    def get_character( input = STDIN )
+      input.getc
+    end
+  end
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: cli-console
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Dāvis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-02 00:00:00.000000000 Z
+dependencies: []
+description: Basic library for making interactive command-line applications much easier
+email:
+- davispuh@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Gemfile
+- README.md
+- Rakefile
+- UNLICENSE
+- cli-console.gemspec
+- examples/shell.rb
+- lib/cli-console.rb
+- lib/cli-console/task.rb
+- lib/cli-console/version.rb
+- spec/cli-console_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/davispuh/CLI-Console
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Create CLI applications easily
+test_files:
+- spec/cli-console_spec.rb
+- spec/spec_helper.rb
+has_rdoc: