documentation for Shell
"Konrad Meyer" <[email protected]> Sat, 7 Oct 2006 22:54:57 -0700
| Newsgroups | gmane.comp.lang.ruby.documentation |
|---|---|
| Message-ID | <[email protected]> |
See attached; I tried to make sure there was at least a one line
explanation of all methods, but I might have made mistakes, done
something stupid, whatever. Comments *greatly* welcome. In some places
I fixed whitespace (for consistancy), but mostly left it alone. I
believe there were two methods like:
def foo
@foo
end
that I changed to attr_reader :foo. That's all, please, feedback!
--
Konrad Meyer
shell.patch
(text/x-patch, 30.4 KB)
? shell/.filter.rb.swp
Index: shell.rb
===================================================================
RCS file: /src/ruby/lib/shell.rb,v
retrieving revision 1.9
diff -p -u -1 -r1.9 shell.rb
--- shell.rb 20 Jul 2006 17:35:26 -0000 1.9
+++ shell.rb 8 Oct 2006 05:47:06 -0000
@@ -1,11 +1,9 @@
#
-# shell.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.8 $
-# $Date: 2001/03/19 09:01:11 $
-# by Keiju ISHITSUKA(Nippon Rational Inc.)
+# = shell.rb: Emulate a system shell
#
-# --
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
-#
+# Rubifies working with a local shell. See Shell for documentation, and
+# Net::Telnet for working with remote shells.
#
@@ -19,2 +17,15 @@ require "shell/process-controller"
+#
+# Shell is the parent class for working with the ruby representation of the
+# shell.
+#
+# Directory related methods:
+# Shell#cwd (or #dir, #getwd, or #pwd),
+# Shell#chdir (or #cd),
+# Shell#pushdir (or #pushd),
+# Shell#popdir (or #popd),
+# Shell#mkdir, and
+# Shell#rmdir.
+#
+
class Shell
@@ -40,2 +51,6 @@ class Shell
+ #
+ # If +val+ evaulates to true, turns on verbose. In all cases, sets
+ # @debug to +debug+.
+ #
def debug=(val)
@@ -45,2 +60,6 @@ class Shell
+ #
+ # Creates a new Shell, changes its working directory to +path+, and
+ # returns the new shell object.
+ #
def cd(path)
@@ -51,2 +70,6 @@ class Shell
+ #
+ # Returns @default_system_path, or if that isn't set, the
+ # environmental variable _PATH_ split into an array.
+ #
def default_system_path
@@ -59,2 +82,5 @@ class Shell
+ #
+ # Setter for @default_system_path.
+ #
def default_system_path=(path)
@@ -63,2 +89,5 @@ class Shell
+ #
+ # Returns @default_record_separator, or if that isn't set, $/.
+ #
def default_record_separator
@@ -71,2 +100,5 @@ class Shell
+ #
+ # Sets the value of @default_record_separator.
+ #
def default_record_separator=(rs)
@@ -76,2 +108,5 @@ class Shell
+ #
+ # Creates a new Shell object.
+ #
def initialize
@@ -93,2 +128,5 @@ class Shell
+ #
+ # Sets the system path, and rehashes.
+ #
def system_path=(path)
@@ -101,2 +139,6 @@ class Shell
+ #
+ # Turns on debugging if +val+ evaluates to true. Also turns on verbose if
+ # +val+ evaluates to true.
+ #
def debug=(val)
@@ -112,2 +154,5 @@ class Shell
+ #
+ # Expands a relative +path+ to a full path, using File.expand_path.
+ #
def expand_path(path)
@@ -116,14 +161,2 @@ class Shell
- # Most Shell commands are defined via CommandProcessor
-
- #
- # Dir related methods
- #
- # Shell#cwd/dir/getwd/pwd
- # Shell#chdir/cd
- # Shell#pushdir/pushd
- # Shell#popdir/popd
- # Shell#mkdir
- # Shell#rmdir
-
attr :cwd
@@ -136,4 +169,6 @@ class Shell
- # If called as iterator, it restores the current directory when the
- # block ends.
+ #
+ # Changes working directory. If passed a block, it restores the
+ # current directory when the block ends.
+ #
def chdir(path = nil)
@@ -157,2 +192,14 @@ class Shell
+ #
+ # Push current directory on to the directory stack, and change to the
+ # directory +path+. If +path+ isn't given, pop the topmost directory
+ # stack entry, and go there. If a block is given, +self+ is yielded to
+ # the block after +path+ is pushed, and once the block finishes, popdir
+ # is called.
+ #
+ # Example:
+ # require 'shell'
+ #
+ # Shell.new.pushdir("/etc") { |sh| ... }
+ #
def pushdir(path = nil)
@@ -183,2 +230,5 @@ class Shell
+ #
+ # Pop the top directory off of the directory stack and chdir to it.
+ #
def popdir
@@ -195,5 +245,6 @@ class Shell
- #
- # process management
- #
+ #
+ # Returns active and waiting jobs in an array. See
+ # ProcessController#jobs.
+ #
def jobs
@@ -202,2 +253,5 @@ class Shell
+ #
+ # Kills a job, with signal +sig+ if applicable.
+ #
def kill(sig, command)
@@ -207,3 +261,3 @@ class Shell
#
- # command definitions
+ # Defines a system command. See CommandProcessor.def_system_command.
#
@@ -213,2 +267,6 @@ class Shell
+ #
+ # Undefines a system command. Opposite of def_system_command. See
+ # CommandProcessor.undef_system_command.
+ #
def Shell.undef_system_command(command)
@@ -217,2 +275,5 @@ class Shell
+ #
+ # Creates an alias to a command. See CommandProcessor.alias_command.
+ #
def Shell.alias_command(ali, command, *opts, &block)
@@ -221,2 +282,6 @@ class Shell
+ #
+ # Removes an alias to a command; opposite of alias_command. See
+ # CommandProcessor.unalias_command.
+ #
def Shell.unalias_command(ali)
@@ -225,2 +290,6 @@ class Shell
+ #
+ # Installs system commands with prefix +pre+. +pre+ defaults to "sys_".
+ # See CommandProcessor.install_system_commands.
+ #
def Shell.install_system_commands(pre = "sys_")
@@ -229,2 +298,5 @@ class Shell
+ #
+ # If debugging is on higher than 2, calls super. Otherwise, it just
+ # runs to_s.
#
@@ -238,22 +310,25 @@ class Shell
+ #
+ # NOTE: wtf?
+ #
def self.notify(*opts, &block)
Thread.exclusive do
- if opts[-1].kind_of?(String)
- yorn = verbose?
- else
- yorn = opts.pop
- end
- return unless yorn
-
- _head = true
- print opts.collect{|mes|
- mes = mes.dup
- yield mes if iterator?
- if _head
- _head = false
- "shell: " + mes
+ if opts[-1].kind_of?(String)
+ yorn = verbose?
else
- " " + mes
+ yorn = opts.pop
end
- }.join("\n")+"\n"
+ return unless yorn
+
+ _head = true
+ puts opts.collect{|mes|
+ mes = mes.dup
+ yield mes if iterator?
+ if _head
+ _head = false
+ "shell: " + mes
+ else
+ " " + mes
+ end
+ }.join("\n")
end
Index: shell/builtin-command.rb
===================================================================
RCS file: /src/ruby/lib/shell/builtin-command.rb,v
retrieving revision 1.1
diff -p -u -1 -r1.1 builtin-command.rb
--- shell/builtin-command.rb 17 May 2001 10:02:48 -0000 1.1
+++ shell/builtin-command.rb 8 Oct 2006 05:47:07 -0000
@@ -1,11 +1,10 @@
#
-# shell/builtin-command.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.1 $
-# $Date: 2001/05/17 10:02:48 $
-# by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)
+# = shell/builtin-command.rb: Built-in ruby commands
#
-# --
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
-#
+# This file contains multiple virtual commands that are actually ruby. See
+# Shell::BuiltInCommand, Shell::Echo, Shell::Cat, Shell::Glob,
+# Shell::AppendIO, Shell::AppendFile, Shell::Tee, and Shell::Concat.
#
@@ -15,2 +14,6 @@ require "shell/filter"
class Shell
+ #
+ # The BuiltInCommand class, from which the built-in commands are
+ # constructed. Pretends to be a SystemCommand.
+ #
class BuiltInCommand<Filter
@@ -24,2 +27,3 @@ class Shell
+ # Implementation of echo.
class Echo < BuiltInCommand
@@ -30,5 +34,6 @@ class Shell
+ # Runs through @strings split by +rs+, and sends each to the block.
def each(rs = nil)
rs = @shell.record_separator unless rs
- for str in @strings
+ for str in @strings
yield str + rs
@@ -38,2 +43,3 @@ class Shell
+ # Built-in cat command.
class Cat < BuiltInCommand
@@ -44,2 +50,3 @@ class Shell
+ # Yields every line of @cat_files to the block.
def each(rs = nil)
@@ -55,2 +62,3 @@ class Shell
+ # Built-in glob class.
class Glob < BuiltInCommand
@@ -71,5 +79,6 @@ class Shell
+ # For each file, yield the name postfix record seperator +rs+.
def each(rs = nil)
rs = @shell.record_separator unless rs
- for f in @files
+ for f in @files
yield f+rs
@@ -93,2 +102,5 @@ class Shell
+ #
+ # Sucks output out of +filter+ and appends it to +io+.
+ #
class AppendIO < BuiltInCommand
@@ -100,2 +112,6 @@ class Shell
+ #
+ # Set the input to a filter, and runs #each on @input, appending each
+ # line to +io+.
+ #
def input=(filter)
@@ -109,2 +125,3 @@ class Shell
+ # Same as AppendIO, but appends to a file.
class AppendFile < AppendIO
@@ -125,2 +142,3 @@ class Shell
+ # Takes stdin and writes to a file as well as stdout.
class Tee < BuiltInCommand
@@ -141,2 +159,3 @@ class Shell
+ # Concatenates multiple jobs.
class Concat < BuiltInCommand
Index: shell/command-processor.rb
===================================================================
RCS file: /src/ruby/lib/shell/command-processor.rb,v
retrieving revision 1.10
diff -p -u -1 -r1.10 command-processor.rb
--- shell/command-processor.rb 18 Apr 2004 23:19:47 -0000 1.10
+++ shell/command-processor.rb 8 Oct 2006 05:47:08 -0000
@@ -1,11 +1,8 @@
#
-# shell/command-controller.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.10 $
-# $Date: 2004/04/18 23:19:47 $
-# by Keiju ISHITSUKA(Nippon Rational Inc.)
+# = shell/command-processor.rb: Process commands
+#
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
-# --
-#
-#
+# Subclass of Shell that handles commands. See Shell::CommandProcessor.
#
@@ -22,9 +19,13 @@ require "shell/builtin-command"
class Shell
+ #
+ # CommandProcessor is a subclass of Shell that assists in handling
+ # shell and ruby commands.
+ #
class CommandProcessor
-# include Error
+
+ NoDelegateMethods = ["initialize", "expand_path"]
#
- # initialize of Shell and related classes.
+ # Initialization of Shell and related classes.
#
- NoDelegateMethods = ["initialize", "expand_path"]
def self.initialize
@@ -38,2 +39,5 @@ class Shell
+ #
+ # See add_delegate_command_to_shell.
+ #
def self.method_added(id)
@@ -44,3 +48,3 @@ class Shell
#
- # include run file.
+ # Include ruby shell rc file.
#
@@ -59,2 +63,5 @@ class Shell
+ #
+ # Creates a new CommandProcessor object with the passed Shell instance.
+ #
def initialize(shell)
@@ -65,6 +72,3 @@ class Shell
#
- # CommandProcessor#expand_path(path)
- # path: String
- # return: String
- # returns the absolute path for <path>
+ # Returns the absolute path for +path+.
#
@@ -75,18 +79,5 @@ class Shell
#
- # File related commands
- # Shell#foreach
- # Shell#open
- # Shell#unlink
- # Shell#test
- #
- # -
- #
- # CommandProcessor#foreach(path, rs)
- # path: String
- # rs: String - record separator
- # iterator
- # Same as:
- # File#foreach (when path is file)
- # Dir#foreach (when path is directory)
- # path is relative to pwd
+ # This is the same as File#foreach, when +path+ is a file, or
+ # Dir#foreach, when +path+ is a directory. +path+ is relative to the
+ # current working directory.
#
@@ -104,10 +95,5 @@ class Shell
#
- # CommandProcessor#open(path, mode)
- # path: String
- # mode: String
- # return: File or Dir
- # Same as:
- # File#open (when path is file)
- # Dir#open (when path is directory)
- # mode has an effect only when path is a file
+ # This is the same as File#open, when +path+ is a file, or Dir#open,
+ # when +path+ is a directory. +mode+ only has an effect when +path+ is
+ # a file.
#
@@ -126,6 +112,4 @@ class Shell
#
- # CommandProcessor#unlink(path)
- # same as:
- # Dir#unlink (when path is directory)
- # File#unlink (when path is file)
+ # Same as Dir#unlink or File#unlink, when +path+ is a directory or a
+ # file, respectively.
#
@@ -141,17 +125,7 @@ class Shell
#
- # CommandProcessor#test(command, file1, file2)
- # CommandProcessor#[command, file1, file2]
- # command: char or String or Symbol
- # file1: String
- # file2: String(optional)
- # return: Boolean
- # same as:
- # test() (when command is char or length 1 string or symbol)
- # FileTest.command (others)
- # example:
- # sh[?e, "foo"]
- # sh[:e, "foo"]
- # sh["e", "foo"]
- # sh[:exists?, "foo"]
- # sh["exists?", "foo"]
+ # This is the same as test(), when the command is one letter long, or
+ # FileTest.command() otherwise. Example usage:
+ # sh[:e, "foo"]
+ # sh["e", "foo"]
+ # sh["exists?", "foo"]
#
@@ -189,7 +163,5 @@ class Shell
#
- #--
+
#
- # CommandProcessor#mkdir(*path)
- # path: String
- # same as Dir.mkdir()
+ # Same as Dir.mkdir().
#
@@ -202,5 +174,3 @@ class Shell
#
- # CommandProcessor#rmdir(*path)
- # path: String
- # same as Dir.rmdir()
+ # Same as Dir.rmdir().
#
@@ -213,10 +183,3 @@ class Shell
#
- # CommandProcessor#system(command, *opts)
- # command: String
- # opts: String
- # return: SystemCommand
- # Same as system() function
- # example:
- # print sh.system("ls", "-l")
- # sh.system("ls", "-l") | sh.head > STDOUT
+ # Same as the Kernel#system() method.
#
@@ -234,4 +197,3 @@ class Shell
#
- # ProcessCommand#rehash
- # clear command hash table.
+ # Clears 'commands' hash.
#
@@ -242,3 +204,3 @@ class Shell
#
- # ProcessCommand#transact
+ # See ProcessController#wait_all_jobs_execution.
#
@@ -249,2 +211,5 @@ class Shell
+ #
+ # Evaluates the passed block in the context of the Shell instance.
+ #
def transact(&block)
@@ -258,3 +223,3 @@ class Shell
#
- # internal commands
+ # Passes the given block to transact, and prints the output to +dev+.
#
@@ -264,2 +229,5 @@ class Shell
+ #
+ # See Echo.new.
+ #
def echo(*strings)
@@ -268,2 +236,5 @@ class Shell
+ #
+ # See Cat.new.
+ #
def cat(*filenames)
@@ -276,2 +247,5 @@ class Shell
+ #
+ # See Glob.new.
+ #
def glob(pattern)
@@ -280,2 +254,5 @@ class Shell
+ #
+ # Appends +filter+ to +to+.
+ #
def append(to, filter)
@@ -291,2 +268,5 @@ class Shell
+ #
+ # See Tee.new.
+ #
def tee(file)
@@ -295,2 +275,5 @@ class Shell
+ #
+ # See Concat.new.
+ #
def concat(*jobs)
@@ -299,3 +282,6 @@ class Shell
- # %pwd, %cwd -> @pwd
+ #
+ # Calls Shell.notify on +opts+, replacing %cwd and %pwd with the
+ # current working directory.
+ #
def notify(*opts, &block)
@@ -330,2 +316,5 @@ class Shell
+ #
+ # Looks up and returns the command +command+.
+ #
def find_system_command(command)
@@ -355,6 +344,4 @@ class Shell
#
- # CommandProcessor.def_system_command(command, path)
- # command: String
- # path: String
- # define 'command()' method as method.
+ # Defines '+command+()' as a method. +command+ is a string, and
+ # +path+ is as well. +path+ defaults to +command+.
#
@@ -362,5 +349,7 @@ class Shell
begin
- eval((d = %Q[def #{command}(*opts)
- SystemCommand.new(@shell, '#{path}', *opts)
- end]), nil, __FILE__, __LINE__ - 1)
+ eval((d = %Q[
+ def #{command}(*opts)
+ SystemCommand.new(@shell, '#{path}', *opts)
+ end
+ ]), nil, __FILE__, __LINE__ - 1)
rescue SyntaxError
@@ -370,5 +359,8 @@ class Shell
Shell.notify("Definition of #{command}: ", d,
- Shell.debug.kind_of?(Integer) && Shell.debug > 1)
+ Shell.debug.kind_of?(Integer) && Shell.debug > 1)
end
+ #
+ # Undefine '+command+()' as a method. Opposite of def_system_command.
+ #
def self.undef_system_command(command)
@@ -381,8 +373,6 @@ class Shell
- # define command alias
- # ex)
- # def_alias_command("ls_c", "ls", "-C", "-F")
- # def_alias_command("ls_c", "ls"){|*opts| ["-C", "-F", *opts]}
- #
@alias_map = {}
+ #
+ # Attribute getter.
+ #
def self.alias_map
@@ -390,2 +380,8 @@ class Shell
end
+
+ #
+ # Define command alias. Example:
+ #
+ # alias_command("ls_c", "ls", "-C", "-F")
+ #
def self.alias_command(ali, command, *opts, &block)
@@ -397,12 +393,16 @@ class Shell
- eval((d = %Q[def #{ali}(*opts)
- @shell.__send__(:#{command},
- *(CommandProcessor.alias_map[:#{ali}].call *opts))
- end]), nil, __FILE__, __LINE__ - 1)
+ eval((d = %Q[
+ def #{ali}(*opts)
+ @shell.__send__(:#{command},
+ *(CommandProcessor.alias_map[:#{ali}].call *opts))
+ end
+ ]), nil, __FILE__, __LINE__ - 1)
else
- args = opts.collect{|opt| '"' + opt + '"'}.join(",")
- eval((d = %Q[def #{ali}(*opts)
- @shell.__send__(:#{command}, #{args}, *opts)
- end]), nil, __FILE__, __LINE__ - 1)
+ args = opts.collect{|opt| '"' + opt + '"'}.join(",")
+ eval((d = %Q[
+ def #{ali}(*opts)
+ @shell.__send__(:#{command}, #{args}, *opts)
+ end
+ ]), nil, __FILE__, __LINE__ - 1)
end
@@ -415,3 +415,3 @@ class Shell
Shell.notify("Definition of #{ali}: ", d,
- Shell.debug.kind_of?(Integer) && Shell.debug > 1)
+ Shell.debug.kind_of?(Integer) && Shell.debug > 1)
self
@@ -419,2 +419,5 @@ class Shell
+ #
+ # Undefine a command alias. Opposite of alias_command.
+ #
def self.unalias_command(ali)
@@ -426,11 +429,9 @@ class Shell
#
- # CommandProcessor.def_builtin_commands(delegation_class, command_specs)
- # delegation_class: Class or Module
- # command_specs: [[command_name, [argument,...]],...]
- # command_name: String
- # arguments: String
- # FILENAME?? -> expand_path(filename??)
- # *FILENAME?? -> filename??.collect{|f|expand_path(f)}.join(", ")
- # define command_name(argument,...) as
- # delegation_class.command_name(argument,...)
+ # Defines +command_name+(+argument+, ...) as
+ # +delegation_class+.+command_name+(+argument+, ...).
+ #
+ # +delegation_class+ is a Class or Module.
+ # +command_specs+ is an array of form [[+command_name+, [+argument+,
+ # ...]], ...].
+ # +command_name+ is a string, +arguments+ are strings.
#
@@ -451,8 +452,10 @@ class Shell
}.join(", ")
- d = %Q[def #{meth}(#{arg_str})
- #{delegation_class}.#{meth}(#{call_arg_str})
- end]
+ d = %Q[
+ def #{meth}(#{arg_str})
+ #{delegation_class}.#{meth}(#{call_arg_str})
+ end
+ ]
Shell.notify "Define #{meth}(#{arg_str})", Shell.debug?
Shell.notify("Definition of #{meth}: ", d,
- Shell.debug.kind_of?(Integer) && Shell.debug > 1)
+ Shell.debug.kind_of?(Integer) && Shell.debug > 1)
eval d
@@ -462,9 +465,8 @@ class Shell
#
- # CommandProcessor.install_system_commands(pre)
- # pre: String - command name prefix
- # defines every command which belongs in default_system_path via
- # CommandProcessor.command(). It doesn't define already defined
- # methods twice. By default, "pre_" is prefixes to each method
- # name. Characters that may not be used in a method name are
- # all converted to '_'. Definition errors are just ignored.
+ # Defines every command which belongs in default_system_path via
+ # CommandProcessor.command(). It doesn't define already defined
+ # methods. By default, "pre_" is prefixed to each method
+ # name, but setting +pre+ can change the prefix. Characters that may
+ # not be used in a method name are all converted to '_'.
+ # Definition errors are just ignored.
#
@@ -499,2 +501,7 @@ class Shell
#----------------------------------------------------------------------
+
+ #
+ # Adds the method +id+ to Shell. If it already exists, aliases it to
+ # +id+ with a postfix of '_org'.
+ #
def self.add_delegate_command_to_shell(id)
@@ -503,4 +510,4 @@ class Shell
if Shell.method_defined?(id)
- Shell.notify "warn: override definnition of Shell##{name}."
- Shell.notify "warn: alias Shell##{name} to Shell##{name}_org.\n"
+ Shell.notify "warn: overriding definition of Shell##{name}."
+ Shell.notify "warn: aliasing Shell##{name} to Shell##{name}_org.\n"
Shell.module_eval "alias #{name}_org #{name}"
@@ -508,15 +515,17 @@ class Shell
Shell.notify "method added: Shell##{name}.", Shell.debug?
- Shell.module_eval(%Q[def #{name}(*args, &block)
- begin
- @command_processor.__send__(:#{name}, *args, &block)
- rescue Exception
- [email protected]_if{|s| /:in `__getobj__'$/ =~ s} #`
- [email protected]_if{|s| /^\\(eval\\):/ =~ s}
- raise
- end
- end], __FILE__, __LINE__)
+ Shell.module_eval(%Q[
+ def #{name}(*args, &block)
+ begin
+ @command_processor.__send__(:#{name}, *args, &block)
+ rescue Exception
+ [email protected]_if{|s| /:in `__getobj__'$/ =~ s}
+ [email protected]_if{|s| /^\\(eval\\):/ =~ s}
+ raise
+ end
+ end
+ ], __FILE__, __LINE__)
if Shell::Filter.method_defined?(id)
- Shell.notify "warn: override definnition of Shell::Filter##{name}."
- Shell.notify "warn: alias Shell##{name} to Shell::Filter##{name}_org."
+ Shell.notify "warn: overriding definition of Shell::Filter##{name}."
+ Shell.notify "warn: aliasing Shell##{name} to Shell::Filter##{name}_org."
Filter.module_eval "alias #{name}_org #{name}"
@@ -524,11 +533,13 @@ class Shell
Shell.notify "method added: Shell::Filter##{name}.", Shell.debug?
- Filter.module_eval(%Q[def #{name}(*args, &block)
- begin
- self | @shell.__send__(:#{name}, *args, &block)
- rescue Exception
- [email protected]_if{|s| /:in `__getobj__'$/ =~ s} #`
- [email protected]_if{|s| /^\\(eval\\):/ =~ s}
- raise
- end
- end], __FILE__, __LINE__)
+ Filter.module_eval(%Q[
+ def #{name}(*args, &block)
+ begin
+ self | @shell.__send__(:#{name}, *args, &block)
+ rescue Exception
+ [email protected]_if{|s| /:in `__getobj__'$/ =~ s}
+ [email protected]_if{|s| /^\\(eval\\):/ =~ s}
+ raise
+ end
+ end
+ ], __FILE__, __LINE__)
end
@@ -536,3 +547,3 @@ class Shell
#
- # define default builtin commands
+ # Define default built-in commands.
#
Index: shell/error.rb
===================================================================
RCS file: /src/ruby/lib/shell/error.rb,v
retrieving revision 1.2
diff -p -u -1 -r1.2 error.rb
--- shell/error.rb 7 Feb 2003 19:00:21 -0000 1.2
+++ shell/error.rb 8 Oct 2006 05:47:08 -0000
@@ -1,12 +1,8 @@
#
-# shell/error.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.2 $
-# $Date: 2003/02/07 19:00:21 $
-# by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)
+# = shell/error.rb: Map exceptions to messages
#
-# --
-#
-#
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
+# Simple mapping of exceptions to messages. See: Shell::Error.
@@ -15,2 +11,3 @@ require "e2mmap"
class Shell
+ # Maps exception symbols to strings.
module Error
Index: shell/filter.rb
===================================================================
RCS file: /src/ruby/lib/shell/filter.rb,v
retrieving revision 1.4
diff -p -u -1 -r1.4 filter.rb
--- shell/filter.rb 21 Mar 2004 12:17:56 -0000 1.4
+++ shell/filter.rb 8 Oct 2006 05:47:08 -0000
@@ -1,18 +1,26 @@
#
-# shell/filter.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.4 $
-# $Date: 2004/03/21 12:17:56 $
-# by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)
+# = shell/filter.rb: Simulate parts of bash
#
-# --
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
-#
+# Shell::Filter defines some methods to make ruby more like bash.
#
+#
+# Shell is the parent class for working with the ruby representation of the
+# shell.
+#
+# Directory related methods:
+# Shell#cwd (or #dir, #getwd, or #pwd),
+# Shell#chdir (or #cd),
+# Shell#pushdir (or #pushd),
+# Shell#popdir (or #popd),
+# Shell#mkdir, and
+# Shell#rmdir.
+#
class Shell
+
#
- # Filter
- # A method to require
- # each()
+ # Filter is a class to allow bash-isms in ruby.
#
@@ -26,8 +34,8 @@ class Shell
- attr_reader :input
+ attr_accessor :input
- def input=(filter)
- @input = filter
- end
-
+ #
+ # Yields each +rs+-seperated chunk of @input to the passed block, or if
+ # +rs+ isn't passed, @shell.record_separator defaults.
+ #
def each(rs = nil)
@@ -39,2 +47,5 @@ class Shell
+ #
+ # Use bash-style file input.
+ #
def < (src)
@@ -52,2 +63,5 @@ class Shell
+ #
+ # Use bash-style file output.
+ #
def > (to)
@@ -69,2 +83,5 @@ class Shell
+ #
+ # Bash-style append-to-file.
+ #
def >> (to)
@@ -77,2 +94,5 @@ class Shell
+ #
+ # Bash-y pipe to another Filter object.
+ #
def | (filter)
@@ -85,2 +105,5 @@ class Shell
+ #
+ # Joins another filter with self.
+ #
def + (filter)
@@ -89,2 +112,3 @@ class Shell
+ # Based off of Filter#each.
def to_a
@@ -95,2 +119,3 @@ class Shell
+ # Based off of Filter#each.
def to_s
Index: shell/process-controller.rb
===================================================================
RCS file: /src/ruby/lib/shell/process-controller.rb,v
retrieving revision 1.3
diff -p -u -1 -r1.3 process-controller.rb
--- shell/process-controller.rb 16 Oct 2003 17:47:19 -0000 1.3
+++ shell/process-controller.rb 8 Oct 2006 05:47:08 -0000
@@ -1,11 +1,9 @@
#
-# shell/process-controller.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.3 $
-# $Date: 2003/10/16 17:47:19 $
-# by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)
+# = shell/process-controller.rb: Control processes
#
-# --
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
-#
+# This file contains the class that controls running processes. See:
+# Shell::ProcessController.
#
@@ -17,2 +15,5 @@ require "sync"
class Shell
+ #
+ # This class controls running processes.
+ #
class ProcessController
@@ -24,2 +25,3 @@ class Shell
+ # Lock the controller, run block, and unlock.
def process_controllers_exclusive
@@ -33,2 +35,3 @@ class Shell
+ # Activate a process.
def activate(pc)
@@ -40,2 +43,3 @@ class Shell
+ # Deactivate a process.
def inactivate(pc)
@@ -50,2 +54,5 @@ class Shell
+ #
+ # Pass each active process object to a block.
+ #
def each_active_object
@@ -59,2 +66,5 @@ class Shell
+ #
+ # Creates new ProcessController object when passed an instance of Shell
+ #
def initialize(shell)
@@ -69,2 +79,3 @@ class Shell
+ # Array of active and waiting jobs.
def jobs
@@ -78,10 +89,5 @@ class Shell
- def active_jobs
- @active_jobs
- end
-
- def waiting_jobs
- @waiting_jobs
- end
+ attr_reader :active_jobs, :waiting_jobs
+ # Are there any jobs left?
def jobs_exist?
@@ -92,2 +98,3 @@ class Shell
+ # Are there any active jobs left?
def active_jobs_exist?
@@ -98,2 +105,3 @@ class Shell
+ # Are there any jobs waiting to run?
def waiting_jobs_exist?
@@ -104,3 +112,3 @@ class Shell
- # schedule a command
+ # Schedule a command.
def add_schedule(command)
@@ -116,3 +124,3 @@ class Shell
- # start a job
+ # Start a job.
def start_job(command = nil)
@@ -136,2 +144,3 @@ class Shell
+ # Is this +job+ waiting?
def waiting_job?(job)
@@ -142,2 +151,3 @@ class Shell
+ # Is this +job+ active?
def active_job?(job)
@@ -148,3 +158,3 @@ class Shell
- # terminate a job
+ # Terminate a job.
def terminate_job(command)
@@ -159,3 +169,3 @@ class Shell
- # kill a job
+ # Kill a job.
def kill_job(sig, command)
@@ -179,3 +189,3 @@ class Shell
- # wait for all jobs to terminate
+ # Wait for all jobs to terminate.
def wait_all_jobs_execution
@@ -192,3 +202,3 @@ class Shell
- # simple fork
+ # Simple fork.
def sfork(command, &block)
Index: shell/system-command.rb
===================================================================
RCS file: /src/ruby/lib/shell/system-command.rb,v
retrieving revision 1.3
diff -p -u -1 -r1.3 system-command.rb
--- shell/system-command.rb 21 Mar 2004 12:17:56 -0000 1.3
+++ shell/system-command.rb 8 Oct 2006 05:47:08 -0000
@@ -1,11 +1,9 @@
#
-# shell/system-command.rb -
-# $Release Version: 0.6.0 $
-# $Revision: 1.3 $
-# $Date: 2004/03/21 12:17:56 $
-# by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)
+# = shell/system-command.rb: Represent system commands
#
-# --
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#
-#
+# Virtual system commands, and interactions with them. See
+# Shell::SystemCommand for documentation.
#
@@ -15,3 +13,10 @@ require "shell/filter"
class Shell
+ #
+ # This subclass of Shell represents 'real' shell commands.
+ #
class SystemCommand < Filter
+ #
+ # Create a new instance of SystemCommand. +sh+ is an instance of Shell,
+ # +command+ is a command, and +opts+ options to the command.
+ #
def initialize(sh, command, *opts)
@@ -33,2 +38,3 @@ class Shell
+ # Check if this command is a waiting job.
def wait?
@@ -37,2 +43,3 @@ class Shell
+ # Check if this command is an active job.
def active?
@@ -41,2 +48,3 @@ class Shell
+ # Sets input.
def input=(inp)
@@ -48,2 +56,5 @@ class Shell
+ #
+ # Runs the actual command on the system.
+ #
def start
@@ -59,2 +70,5 @@ class Shell
+ #
+ # Flushes the outgoing pipe.
+ #
def flush
@@ -63,2 +77,5 @@ class Shell
+ #
+ # Closes stdin and stdout of the running command.
+ #
def terminate
@@ -74,2 +91,3 @@ class Shell
+ # Kill ourselves with signal +sig+.
def kill(sig)
@@ -80,3 +98,5 @@ class Shell
-
+ #
+ # Starts getting input from the running command.
+ #
def start_import
@@ -115,2 +135,5 @@ class Shell
+ #
+ # Sends our input through to the running program.
+ #
def start_export
@@ -143,2 +166,6 @@ class Shell
alias super_each each
+ #
+ # Goes through all of the input queue and yields each value to the
+ # given block.
+ #
def each(rs = nil)
@@ -149,8 +176,6 @@ class Shell
- # ex)
- # if you wish to output:
- # "shell: job(#{@command}:#{@pid}) close pipe-out."
- # then
- # mes: "job(%id) close pipe-out."
- # yorn: Boolean(@shell.debug? or @shell.verbose?)
+ #
+ # Calls Shell#notify, replacing '%id', '%name', and '%pid' with
+ # appropriate variables.
+ #
def notify(*opts, &block)
Index: shell/version.rb
===================================================================
RCS file: /src/ruby/lib/shell/version.rb,v
retrieving revision 1.1
diff -p -u -1 -r1.1 version.rb
--- shell/version.rb 17 May 2001 10:02:48 -0000 1.1
+++ shell/version.rb 8 Oct 2006 05:47:08 -0000
@@ -1,11 +1,6 @@
#
-# version.rb - shell version definition file
-# $Release Version: 0.6.0$
-# $Revision: 1.1 $
-# $Date: 2001/05/17 10:02:48 $
-# by Keiju ISHITSUKA(Nihon Rational Software Co.,Ltd)
+# = version.rb: Version of Shell
#
-# --
-#
-#
+# Author:: Keiju Ishitsuka
+# Documentation:: Konrad Meyer
#