prompt 1.1.0 → 1.2.0

data/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 This is updated when a new version is pushed to http://rubygems.org
 
+## 1.2.0 (Apr 21, 2012)
+
+* DSL change: Command descriptions can be provided using `desc`.  You can still
+  pass the description as an argument to `command`, but will be deprecated
+  in a future version. (thanks @kowsik)
+* Partially-typed strings are now passed when calling a parameter's block.  You
+  can use this to more efficiently build the list of completions.  This is
+  especially useful for things like database queries or other remote API calls.
+
 ## 1.1.0 (Apr 18, 2012)
 
 * Format help command so that descriptions are always aligned

data/README.md

@@ -1,5 +1,3 @@
-# Prompt
-
 ## What is this?
 
 Prompt makes it easy to build slick command-line applications with Tab Completion, Command History, and Built-in Help
@@ -8,7 +6,7 @@ Prompt makes it easy to build slick command-line applications with Tab Completio
 
     gem install prompt
 
-## An example
+## Overview
 
 Commands are defined with a Sinatra-inspired DSL:
 
@@ -20,17 +18,20 @@ group "Move"
 
 param :direction, "A cardinal direction", %w(north east south west)
 
-command "go :direction", "Walk in the specified direction" do |direction|
+desc "Walk in the specified direction"
+command "go :direction" do |direction|
   puts "You walked #{direction} and were eaten by a grue."
 end
 
 group "Interact"
 
-command "look", "Look around" do
+desc "Look around"
+command "look" do
   puts "You're in a dark room."
 end
 
-command "say :something", "Say something" do |something|
+desc "Say something"
+command "say :something" do |something|
   puts "You say '#{something}'"
 end
 
@@ -68,18 +69,31 @@ The `help` command is built-in.  It will print all of the commands that you've d
     > help
     Console commands
 
-      help                                     List all commands
-      help -v                                  List all commands, including parameters
-      exit
+      help               List all commands
+      help -v            List all commands, including parameters
+      exit               Exit the console
 
     Move
 
-      go <direction>                           Walk in the specified direction
+      go <direction>     Walk in the specified direction
 
     Interact
 
-      look                                     Look around
-      say <something>                          Say something
+      look               Look around
+      say <something>    Say something
+
+## Describing commands
+
+You can provide a description for a command before defining it.  Descriptions
+are displayed next to each comand in the built-in help.
+
+```ruby
+desc "Look around"
+command "look" do
+  ...
+end
+```
+
 
 ## Grouping commands
 
@@ -141,6 +155,16 @@ param :file, "JPG file" do
 end
 ```
 
+A dynamic parameter's block may optionally take the partially-typed word as
+a parameter, to further limit the completions.
+
+```ruby
+param :username do |starting_with|
+  # slow DB query
+  User.where("username LIKE '?%'", starting_with).map(&:username)
+end
+```
+
 ## Configuration options
 
 The default prompt `"> "` can be changed before starting the console, or while it's running.

data/examples/file_manager

@@ -11,18 +11,21 @@ end
 @pwd = File.expand_path Dir.pwd
 change_prompt @pwd
 
-param :dir, "Directory" do
+desc "Directory"
+param :dir do
   Dir.entries(@pwd).select do |e|
     File.directory?(File.join(@pwd, e))
   end
 end
 
-command "cd :dir", "Change directory" do |dir|
+desc "Change directory"
+command "cd :dir" do |dir|
   @pwd = File.expand_path File.join(@pwd, dir)
   change_prompt @pwd
 end
 
-command "ls", "List files" do
+desc "List files"
+command "ls" do
   puts @pwd
   Dir.entries(@pwd).select do |e|
     path = File.join(@pwd, e)
@@ -34,17 +37,20 @@ command "ls", "List files" do
   end
 end
 
-command "pwd", "Print current directory" do
+desc "Print current directory"
+command "pwd" do
   puts @pwd
 end
 
-param :file, "File" do
+desc "File"
+param :file do
   Dir.entries(@pwd).select do |e|
     File.file?(File.join(@pwd, e))
   end
 end
 
-command "cp *file :dir", "Copy one or more files to dest" do |files, dir|
+desc "Copy one or more files to dest"
+command "cp *file :dir" do |files, dir|
   puts "Copying #{files.length} file(s) to #{dir}"
   # doesn't actually do it...
 end

data/examples/mud

@@ -11,7 +11,8 @@ group "Move"
 
 param :direction, "A cardinal direction", %w(north east south west)
 
-command "go :direction", "Walk in the specified direction" do |direction|
+desc "Walk in the specified direction"
+command "go :direction" do |direction|
   puts "You walked #{direction}"
   @moves += 1
   if @moves > GRUE
@@ -22,7 +23,8 @@ end
 
 group "Interact"
 
-command "look", "Look around" do
+desc "Look around"
+command "look" do
   if @moves < GRUE
   	puts "You're in a nice, well-lit room"
   else
@@ -30,7 +32,8 @@ command "look", "Look around" do
   end
 end
 
-command "say *something", "Say something" do |something|
+desc "Say something"
+command "say *something" do |something|
   puts "You say '#{something.join(" ")}'"
 end
 

data/lib/prompt/application.rb

@@ -61,7 +61,7 @@ module Prompt
     def all_completions(args, partial_arg)
       commands.select { |c| c.could_match? args }.map do |c|
         c.completions(args.length, partial_arg)
-      end.flatten(1)
+      end.flatten(1).sort.uniq
     end
 
     def current_command_group

data/lib/prompt/dsl.rb

@@ -12,18 +12,26 @@ module Prompt
       end
       Prompt.application.select_group(name)
     end
+    
+    def desc text
+      @@last_desc = text
+    end
 
     def group desc
       Prompt.application.select_group(desc)
     end
 
     def command(name, desc = nil, &block)
+      desc ||= @@last_desc
+      @@last_desc = nil
       words = DSLHelper.words(name, @parameters || [])
       command = Command.new(words, desc, &block)
       Prompt.application.add_command(command)
     end
 
-    def param(name, desc, values = nil, &block)
+    def param(name, desc = nil, values = nil, &block)
+      desc ||= @@last_desc
+      @@last_desc = nil
       @parameters = [] unless defined? @parameters
       raise "parameter :#{name} is already defined" if @parameters.find {|v| v.name == name}
       @parameters << if block

data/lib/prompt/parameter.rb

@@ -9,15 +9,16 @@ module Prompt
       @desc = desc
       @values = values || []
       @proc = block if block_given?
+      @cached_values = {}
     end
 
     def clear_cached_values
-      @cached_values = nil
+      @cached_values = {}
     end
 
     def completions(starting_with = "")
       all = if @proc
-        @cached_values ||= @proc.call
+        @cached_values[starting_with] ||= @proc.call(starting_with)
       else
         @values
       end

data/lib/prompt/prompt_module.rb

@@ -1,5 +1,5 @@
 module Prompt
-  VERSION = "1.1.0"
+  VERSION = "1.2.0"
 
   class << self
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: prompt
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-04-18 00:00:00.000000000 Z
+date: 2012-04-21 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