prompt 0.0.1

data/README.md

@@ -0,0 +1,143 @@
+# Prompt
+
+## What is this?
+
+Prompt makes it easy to build slick command-line applications with [Tab Completion](#tabcompletion), [Command History](#commandhistory), and [Built-in Help](#built-inhelp)
+
+## Installation
+
+    gem install prompt
+
+## An example
+
+Commands are defined with a Sinatra-inspired DSL:
+
+```ruby
+require 'prompt'
+extend Prompt::DSL
+
+desc "Move"
+
+variable :direction, "A cardinal direction", %w(north east south west)
+
+command "go :direction", "Walk in the specified direction" do |direction|
+  puts "You walked #{direction} and were eaten by a grue."
+end
+
+desc "Interact"
+
+command "look", "Look around" do
+  puts "You're in a dark room."
+end
+
+command "say :something", "Say something" do |something|
+  puts "You say '#{something}'"
+end
+
+Prompt::Console.start
+```
+
+### Tab completion
+
+Tab completion is hooked up automatically after you define your commands and variables
+
+    $ my_app
+    > g<TAB>
+    > go <TAB>
+    go east   go north  go south  go west
+    > go n<TAB>
+    > go north
+
+### Command history
+
+Command history is enabled automatically.  You can scroll through the history with the UP and DOWN keys.  You can search the history with CTRL-R.
+
+You can preserve the history between runs by specifying a history filename when starting the console
+
+```ruby
+history_file = File.join(ENV["HOME"], ".my-history")
+Prompt::Console.start history_file
+```
+
+
+### Built-in help
+
+The `help` command is built-in.  It will print all of the commands that you've defined in your app.
+
+    $ my_app
+    > help
+    Console commands
+
+      help -v
+      help
+      exit
+
+    Move
+
+      go <direction>                           Walk in the specified direction
+
+    Interact
+
+      look                                     Look around
+      say <something>                          Say something
+
+## Grouping commands
+
+You can put commands in logical groups.  This only affects how help is printed.
+
+```ruby
+desc "Taco commands"
+
+command ...
+command ...
+
+desc "Burger commands"
+
+command ...
+```
+
+## Using Variables
+
+Variables can be used in a command.
+
+```ruby
+command "name :first :last" do |first, last|
+  puts "Hi #{first} #{last}"
+end
+```
+
+Here, the variables are named `first` and `last`.  Their values are be passed as arguments to the command's block, in the order in which they appear.
+
+### Defining variables
+
+It's not necessary to define a variable before using it in a command, but doing so will allow you to provide a useful description and valid values for the variable.
+
+```ruby
+variable :name, "Description"
+```
+
+### Specifying a static list of valid values
+
+You can specify a static list of valid values for a variable.  These will be expanded when using tab completion.
+
+```ruby
+variable :name, "Description", %w(value1 value2)
+```
+
+### Specifying a dynamic list of valid values
+
+Instead of specifying a static list, you can specify a block that will dynamically return a list of valid values for a variable.  These will be expanded when using tab completion.  
+
+```ruby
+dynamic_variable :file, "JPG file" do
+  Dir.glob "*.jpg"
+end
+```
+
+## Configuration options
+
+The default prompt `"> "` can be changed before starting the console.
+
+```ruby
+Prompt::Console.prompt = "#{Dir.pwd}> "
+```

data/examples/file_manager

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+require 'prompt'
+
+extend Prompt::DSL
+
+@pwd = File.absolute_path Dir.pwd
+
+dynamic_variable :dir, "Directory" do
+  Dir.entries(@pwd).select do |e|
+    File.directory? e
+  end
+end
+
+command "cd :dir", "Change directory" do |dir|
+  @pwd = File.absolute_path File.join(@pwd, dir)
+end
+
+command "ls", "List files" do
+  puts @pwd
+  puts Dir.entries(@pwd)
+end
+
+command "pwd", "Print current directory" do
+  puts @pwd
+end
+
+Prompt::Console.start

data/examples/mud

@@ -0,0 +1,37 @@
+#!/usr/bin/env ruby
+
+require 'prompt'
+
+extend Prompt::DSL
+
+GRUE = 3
+@moves = 0
+
+desc "Move"
+
+variable :direction, "A cardinal direction", %w(north east south west)
+
+command "go :direction", "Walk in the specified direction" do |direction|
+  puts "You walked #{direction}"
+  @moves += 1
+  if @moves > GRUE
+  	puts "You have been eaten by a grue"
+  	exit
+  end
+end
+
+desc "Interact"
+
+command "look", "Look around" do
+  if @moves < GRUE
+  	puts "You're in a nice, well-lit room"
+  else
+  	puts "It is pitch black. You are likely to be eaten by a grue."
+  end
+end
+
+command "say :something", "Say something" do |something|
+  puts "You say '#{something}'"
+end
+
+Prompt::Console.start

data/lib/prompt.rb

@@ -0,0 +1,5 @@
+require 'prompt/application'
+require 'prompt/dsl'
+require 'prompt/prompt_module'
+require 'prompt/command_not_found'
+require 'prompt/console'

data/lib/prompt/application.rb

@@ -0,0 +1,53 @@
+require 'prompt/command_group'
+require 'prompt/command'
+
+module Prompt
+  class Application
+    attr :command_groups
+
+    def initialize
+      @command_groups = []
+    end
+
+    def use_command_group desc
+      @current_command_group_name = desc
+    end
+
+    def define_command name, desc = nil, variables, &block
+      current_command_group.commands << Command.new(name, desc, variables, &block)
+    end
+
+    def exec command_str
+      commands.each do |command|
+        args = command.match(command_str)
+        return command.run(args) if args
+      end
+      raise CommandNotFound.new(command_str)
+    end
+
+    def completions starting_with = nil
+      return all_expansions unless starting_with
+
+      all_expansions.grep /^#{Regexp.escape(starting_with)}/
+    end
+
+    private
+
+    def commands
+      @command_groups.map(&:commands).reduce [] { |a, b| a + b }
+    end
+
+    def all_expansions
+      commands.map(&:expansions).flatten
+    end
+
+    def current_command_group
+      command_groups.find { |cg| cg.name == @current_command_group_name } || begin
+        cg = CommandGroup.new(@current_command_group_name)
+        @command_groups << cg
+        cg
+      end
+    end
+
+  end
+end

data/lib/prompt/command.rb

@@ -0,0 +1,95 @@
+module Prompt
+  class Command
+
+    attr :name
+    attr :desc
+
+    def initialize(name, desc = nil, all_variables = [], &block)
+      @name = name
+      @desc = desc
+      @all_variables = all_variables
+      @action = block
+    end
+
+    def run args
+      @action.call *args
+    end
+
+    def match(str)
+      if m = regex.match(str.strip)
+        m[1..-1]
+      end
+    end
+
+    def variables
+      @variables ||= words.select {|w| w.kind_of? Variable}
+    end
+
+    def expansions
+      expand words
+    end
+
+    def usage
+      words.map do |word|
+        case word
+        when Variable
+          "<#{word.name}>"
+        else
+          word
+        end
+      end.join(" ")
+    end
+
+    private
+
+    def regex
+      @regex ||= begin
+        regex_strs = words.map do |word|
+           case word
+           when Variable
+             word.regex
+           else
+             Regexp.escape(word)
+           end
+        end
+        Regexp.new("^#{regex_strs.join("\s+")}$")
+      end
+    end
+
+    def words
+      @words ||= @name.split(/\s/).map do |word|
+         if word[0] == ":"
+           sym = word[1..-1].to_sym
+           @all_variables.find {|v| v.name == sym} || Variable.new(sym, sym.to_s)
+         else
+           word
+         end
+      end
+    end
+
+    def expand a
+      return [] if a.empty?
+
+      head = a[0]
+      tail = a[1..-1]
+
+      case head
+      when Variable
+        head = head.expansions
+      else
+        head = [head]
+      end
+
+      return head if tail.empty?
+
+      result = []
+      head.each do |h|
+        expand(tail).each do |e|
+          result << "#{h} #{e}"
+        end
+      end
+      result
+    end
+
+  end
+end

data/lib/prompt/command_group.rb

@@ -0,0 +1,12 @@
+module Prompt
+  class CommandGroup
+    attr_accessor :name
+    attr :commands
+
+    def initialize name
+      @name = name
+      @commands = []
+    end
+
+  end
+end

data/lib/prompt/command_not_found.rb

@@ -0,0 +1,7 @@
+module Prompt
+  class CommandNotFound < RuntimeError
+    def initialize(command_str)
+      super "Command not found: #{command_str}"
+    end
+  end
+end

data/lib/prompt/console.rb

@@ -0,0 +1,2 @@
+require 'prompt/console/console_module'
+require 'prompt/console/builtins'

data/lib/prompt/console/builtins.rb

@@ -0,0 +1,44 @@
+require 'prompt/dsl'
+
+module Prompt
+  module Console
+
+    class Builtins
+      extend DSL
+
+      desc "Console commands"
+
+      command "help -v" do
+        print_help true
+      end
+
+      command "help" do
+        print_help
+      end
+
+      command "exit" do
+        exit
+      end
+
+      private
+
+      def self.print_help verbose = false
+        Prompt.application.command_groups.each do |cg|
+          puts
+          puts cg.name
+          puts
+          cg.commands.each do |cmd|
+            puts "  %-40s %s" % [cmd.usage, cmd.desc]
+            if verbose
+              cmd.variables.each do |v|
+                puts " "*43 + ("%-10s %s" % ["<#{v.name}>", "#{v.desc}"])
+              end
+            end
+          end
+        end
+      end
+
+    end # class Builtins
+
+  end
+end

data/lib/prompt/console/console_module.rb

@@ -0,0 +1,66 @@
+require 'readline'
+require 'prompt'
+
+module Prompt
+  module Console
+
+    HISTORY_MAX_SIZE = 100
+    PROMPT = "> "
+
+    CompletionProc = proc do |s|
+      Prompt.application.completions(s)
+    end
+
+    def self.start(history_file = nil)
+      @prompt = PROMPT
+
+      # Store the state of the terminal
+      stty_save = `stty -g`.chomp
+      # and restore it when exiting
+      at_exit do
+        system('stty', stty_save)
+        save_history history_file if history_file
+      end
+
+      Readline.basic_word_break_characters = ""
+      Readline.completion_append_character = " "
+      Readline.completion_proc = CompletionProc
+
+      load_history history_file if history_file
+
+      while line = Readline.readline(@prompt, true)
+        begin
+          Prompt.application.exec(line).nil?
+        rescue ::Prompt::CommandNotFound => e
+          STDERR.puts e.message
+        end
+      end
+    end
+
+    def self.prompt= prompt
+      @prompt = prompt
+    end
+
+    def self.prompt
+      @prompt
+    end
+
+    def self.save_history file
+      history_no_dups = Readline::HISTORY.to_a.reverse.uniq[0,HISTORY_MAX_SIZE].reverse
+      File.open(file, "w") do |f|
+        history_no_dups.each do |line|
+          f.puts line
+        end
+      end
+    end
+
+    def self.load_history file
+      if File.exist? file
+        File.readlines(file).each do |line|
+          Readline::HISTORY.push line.strip
+        end
+      end
+    end
+
+  end # module Console
+end

data/lib/prompt/dsl.rb

@@ -0,0 +1,37 @@
+require 'prompt/variable'
+require 'prompt/proc_variable'
+
+module Prompt
+  module DSL
+
+    def self.extended(base)
+      name = if base.respond_to? :name
+        base.name
+      else
+        "Commands"
+      end
+      Prompt.application.use_command_group(name)
+    end
+
+    def desc desc
+      Prompt.application.use_command_group(desc)
+    end
+
+    def command(name, desc = nil, &block)
+      Prompt.application.define_command(name, desc, @variables || {}, &block)
+    end
+
+    def variable(name, desc, values = nil)
+      @variables = [] unless defined? @variables
+      raise "variable :#{name} is already defined" if @variables.find {|v| v.name == name}
+      @variables << Variable.new(name, desc, values)
+    end
+
+    def dynamic_variable(name, desc, &block)
+      @variables = [] unless defined? @variables
+      raise "variable :#{name} is already defined" if @variables.find {|v| v.name == name}
+      @variables << ProcVariable.new(name, desc, &block)
+    end
+
+  end
+end

data/lib/prompt/proc_variable.rb

@@ -0,0 +1,14 @@
+module Prompt
+  class ProcVariable < Variable
+
+    def initialize(name, desc, &block)
+      super(name, desc, nil)
+      @proc = block
+    end
+
+    def values
+      @proc.call
+    end
+
+  end
+end

data/lib/prompt/prompt_module.rb

@@ -0,0 +1,10 @@
+module Prompt
+  class << self
+
+    # Singleton instance
+    #
+    def application
+      @application ||= Application.new
+    end
+  end
+end

data/lib/prompt/variable.rb

@@ -0,0 +1,27 @@
+module Prompt
+  class Variable
+
+    attr :name
+    attr :desc
+    attr :values
+
+    def initialize(name, desc, values = nil)
+      @name = name
+      @desc = desc
+      @values = values
+    end
+
+    def regex
+      if values
+        "(#{values.map{|v| Regexp.escape(v)}.join("|")})"
+      else
+        "([^\s]+)"
+      end
+    end
+
+    def expansions
+      values || ["<#{name}>"]
+    end
+
+  end
+end

data/spec/prompt/command_spec.rb

@@ -0,0 +1,105 @@
+require 'prompt/command'
+require 'prompt/variable'
+
+include Prompt
+
+describe Prompt::Command do
+
+  DIRECTIONS = %w{n e s w}
+  SPEEDS = %w{quickly slowly}
+
+  describe "#match" do
+    it "matches correctly" do
+      c = Command.new("hi")
+
+      c.match("hi").should == []
+      c.match("hi ").should == []
+      c.match(" hi").should == []
+
+      c.match("bye").should be_nil
+      c.match("h").should be_nil
+      c.match("").should be_nil
+    end
+
+    it "matches correctly with a variable" do
+      c = Command.new("hi :name")
+
+      c.match("hi guy").should == ["guy"]
+      c.match("higuy").should be_nil
+      c.match("higuy guy").should be_nil
+    end
+
+    it "matches correctly with a variable and multiple spaces" do
+      c = Command.new("hi :name")
+
+      c.match(" hi guy").should == ["guy"]
+      c.match("hi  guy").should == ["guy"]
+      c.match("hi guy ").should == ["guy"]
+    end
+
+    it "matches correctly with 2 variables" do
+      c = Command.new("hi :first :last")
+
+      c.match("hi agent smith").should == ["agent", "smith"]
+      c.match("hi agent").should be_nil
+      c.match("hi agent smith guy").should be_nil
+    end
+
+    it "matches correctly with variable value constraint" do
+      v = [Variable.new(:dir, "", DIRECTIONS)]
+      c = Command.new("go :dir", nil, v)
+
+      c.match("go n").should == ["n"]
+      c.match("go s").should == ["s"]
+      c.match("go x").should be_nil
+      c.match("go nn").should be_nil
+    end
+  end
+
+  describe "#variables" do
+    it "returns correctly" do
+      color = Variable.new(:color, "")
+      flavor = Variable.new(:flavor, "")
+
+      Command.new("one").variables.should == []
+      vs = Command.new("one :color").variables
+      vs.length.should == 1
+      vs.first.name.should == :color
+      Command.new("one :color", nil, [color]).variables.should == [color]
+      Command.new("one :color", nil, [color, flavor]).variables.should == [color]
+    end
+  end
+
+  describe "#expansions" do
+    it "expands correctly with no variables" do
+      Command.new("one").expansions.should == ["one"]
+    end
+
+    it "expands correctly with undefined variables" do
+      Command.new("go :dir").expansions.should == ["go <dir>"]
+    end
+
+    it "expands correctly with defined variables" do
+      v = [Variable.new(:dir, "", DIRECTIONS), Variable.new(:speed, "", SPEEDS)]
+      Command.new("go :dir", nil, v).expansions.should == ["go n", "go e", "go s", "go w"]
+      Command.new("go :dir :speed", nil, v).expansions.should ==
+        ["go n quickly", "go n slowly",
+         "go e quickly", "go e slowly",
+         "go s quickly", "go s slowly",
+         "go w quickly", "go w slowly"]
+    end
+  end
+
+  describe "#usage" do
+    it "returns correctly" do
+      color = Variable.new(:color, "")
+
+      Command.new("one").usage.should == "one"
+      Command.new("one :color").usage.should == "one <color>"
+      Command.new("one :color", nil, [color]).usage.should == "one <color>"
+      Command.new("one :color three").usage.should == "one <color> three"
+    end
+  end
+
+end
+

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: prompt
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mike Smith
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-17 00:00:00.000000000 Z
+dependencies: []
+description: Prompt makes it easy to build slick command-line applications with Tab
+  Completion, Command History, and Built-in Help
+email: mike@sticknet.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/prompt/application.rb
+- lib/prompt/command.rb
+- lib/prompt/command_group.rb
+- lib/prompt/command_not_found.rb
+- lib/prompt/console/builtins.rb
+- lib/prompt/console/console_module.rb
+- lib/prompt/console.rb
+- lib/prompt/dsl.rb
+- lib/prompt/proc_variable.rb
+- lib/prompt/prompt_module.rb
+- lib/prompt/variable.rb
+- lib/prompt.rb
+- spec/prompt/command_spec.rb
+- examples/file_manager
+- examples/mud
+homepage: http://github.com/mudynamics/prompt
+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: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: A small framework that makes it easy to build slick command-line applications
+test_files: []