Module: Command

Defined in:
lib/command-set/command-set.rb,
lib/command-set/og.rb,
lib/command-set/dsl.rb,
lib/command-set/critic.rb,
lib/command-set/command.rb,
lib/command-set/results.rb,
lib/command-set/subject.rb,
lib/command-set/arguments.rb,
lib/command-set/structural.rb,
lib/command-set/result-list.rb,
lib/command-set/interpreter/base.rb,
lib/command-set/interpreter/text.rb,
lib/command-set/interpreter/quick.rb,
lib/command-set/standard-commands.rb,
lib/command-set/standard-commands.rb,
lib/command-set/interpreter/recording.rb

Overview

Command::CommandSet is a tight little library that lets you clearly and easily describe a set of commands for an interactive application. The command set can then be handed to one of a number of interpreters that will facilitate interaction with the user.

CommandSet has a number of pretty neat features:

  • A command line text interpreter, with tab completion etc. compliments of

readline.

  • A handy little DSL for describing commands and what they do. There are

other CLI engines that map to ruby methods, but frankly, I'm not sure
that's the most useful mapping.  The CommandSet DSL lets you specify the
type of commands, control how they tab complete, mark some arguments as
optional, etc.

  • Modularized commands. The StandardCommands class is a good example.

Basically, any time you have a command that might be generally
applicable, you can compose it into another set, and cherrypick specific
commands out.  For example:

  CommandSet.define_commands do
    command(:example) do |example|
      ...stuff...
    end

    include(other_set)
    include(cluttered_set, :useful)

    sub_command(:sub) do |sub|
      sub.include(yet_another_set)
    end
  end

  • Results processing. Basically, any puts, p or print call in the

context of a command will (instead of outputing directly to +$stdout+)
instead fire events in Formatter objects.  The default behavior of which is
... to output directly to +STDOUT+.  The catch here is that that behavior can
be changed, and the events can include the beginnings and ends of nesting
lists, so you have this whole tree of results from your command execution
that can be manipulated on it's way to the user.
As a for instance, you can spin off threads to do processing of parts of
a command, and be confidant that you'll be able to make sense of the
output for the user.

  • Extensible Command, Argument, and BaseInterpreter make power

functionality easy to add.  The modular design means that a CommandSet
written for use with the TextInterpreter, can also be used to process the
command line arguments to the program or passed to a batch interpreter.
WebApp (a separate gem) uses this feature so that a web application
automatically gets a command line version, for testing or administrator's
convenience.

:include: doc/GUIDED_TOUR

Defined Under Namespace

Modules: CommandClassMethods, Common, Critic, DSL, OgCommands, Results, StandardCommand, StandardCommands Classes: AlternatingArgument, AnchoredCommandSetup, Argument, ArgumentDecoration, ArgumentDecorator, ArgumentInvalidException, ArgumentUnrecognizedException, ArrayArgument, BaseInterpreter, Command, CommandError, CommandException, CommandFinder, CommandSet, CommandSetup, CompletionsLister, ContextBoundary, CritiqueLoader, FiddlyArgument, FileArgument, MultiArgument, Named, NoValidateProcArgument, NumberArgument, OgArgument, Optional, OutOfArgumentsException, OutputStandin, ParentArgument, PermissiveSubject, PlaybackInterpreter, ProcArgument, QuickInterpreter, RecordingInterpreter, RegexpArgument, Repeating, RequirementsCollector, RestOfLineArgument, ResumeFrom, ResumeFromOnlyThis, RootCommand, SetItem, SetVisitor, StringArgument, Subject, SubjectImage, TextInterpreter, UndoStack

Class Method Summary collapse

Class Method Details

.raw_stderr ⇒ Object

See Command::raw_stdout



40
41
42
43
44
45
46
 
# File 'lib/command-set/results.rb', line 40

def raw_stderr
  if $stderr.respond_to?(:__getobj__)
    $stderr.__getobj__
  else
    $stderr
  end
end

.raw_stdout ⇒ Object

If you need the actual IO for /dev/stdout, you can call this to get it. Useful inside of Results::Formatter subclasses, for instance, so that they can actually send messages out to the user.



25
26
27
28
29
30
31
 
# File 'lib/command-set/results.rb', line 25

def raw_stdout
  if $stdout.respond_to?(:__getobj__)
    $stdout.__getobj__
  else
    $stdout
  end
end

.wrap_stderr ⇒ Object

See Command::wrap_stdout



34
35
36
37
 
# File 'lib/command-set/results.rb', line 34

def wrap_stderr
  return if $stdout.respond_to?(:add_dispatcher)
  $stderr = OutputStandin.new($stderr)
end

.wrap_stdout ⇒ Object

Call anywhere to be sure that $stdout is replaced by an OutputStandin that delegates to the original STDOUT IO. This by itself won’t change output behavior. Requiring ‘command-set/command-set’ does this for you. Multiple calls are safe though.



17
18
19
20
 
# File 'lib/command-set/results.rb', line 17

def wrap_stdout
  return if $stdout.respond_to?(:add_dispatcher)
  $stdout = OutputStandin.new($stdout)
end