* doc/shell.rd, doc/shell.rd.ja: Removed stale doc files

* lib/shell.rb, lib/shell/*: Merge and updates docs from doc/shell.rd*


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@38201 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

lib/shell.rb

@@ -20,6 +20,72 @@ require "shell/command-processor"
 require "shell/process-controller"
 
 # Shell implements an idiomatic Ruby interface for common UNIX shell commands.
+#
+# It provides users the ability to execute commands with filters and pipes,
+# like +sh+/+csh+ by using native facilities of Ruby.
+#
+# == Examples
+#
+# === Temp file creation
+#
+# In this example we will create three +tmpFile+'s in three different folders
+# under the +/tmp+ directory.
+#
+#   sh = Shell.cd("/tmp") # Change to the /tmp directory
+#   sh.mkdir "shell-test-1" unless sh.exists?("shell-test-1")
+#   # make the 'shell-test-1' directory if it doesn't already exist
+#   sh.cd("shell-test-1") # Change to the /tmp/shell-test-1 directory
+#   for dir in ["dir1", "dir3", "dir5"]
+#     if !sh.exists?(dir)
+#       sh.mkdir dir # make dir if it doesnt' already exist
+#       sh.cd(dir) do
+#         # change to the `dir` directory
+# 	  f = sh.open("tmpFile", "w") # open a new file in write mode
+# 	  f.print "TEST\n"            # write to the file
+# 	  f.close                     # close the file handler
+#       end
+#       print sh.pwd                  # output the process working directory
+#     end
+#   end
+#
+# === Temp file creationg with self
+#
+# This example is identical to the first, except we're using
+# CommandProcessor#transact.
+#
+# CommandProcessor#transact executes the given block against self, in this case
+# +sh+; our Shell object. Within the block we can substitute +sh.cd+ to +cd+,
+# because the scope within the block uses +sh+ already.
+#
+#   sh = Shell.cd("/tmp")
+#   sh.transact do
+#     mkdir "shell-test-1" unless exists?("shell-test-1")
+#     cd("shell-test-1")
+#     for dir in ["dir1", "dir3", "dir5"]
+#       if !exists?(dir)
+# 	  mkdir dir
+# 	  cd(dir) do
+# 	    f = open("tmpFile", "w")
+# 	    f.print "TEST\n"
+# 	    f.close
+# 	  end
+# 	  print pwd
+#       end
+#     end
+#   end
+#
+# === Pipe /etc/printcap into a file
+#
+# In this example we will read the operating system file +/etc/printcap+,
+# generated by +cupsd+, and then output it to a new file relative to the +pwd+
+# of +sh+.
+#
+#   sh = Shell.new
+#   sh.cat("/etc/printcap") | sh.tee("tee1") > "tee2"
+#   (sh.cat < "/etc/printcap") | sh.tee("tee11") > "tee12"
+#   sh.cat("/etc/printcap") | sh.tee("tee1") >> "tee2"
+#   (sh.cat < "/etc/printcap") | sh.tee("tee11") >> "tee12"
+#
 class Shell
   @RCS_ID='-$Id: shell.rb,v 1.9 2002/03/04 12:01:10 keiju Exp keiju $-'
 
@@ -52,6 +118,10 @@ class Shell
       @verbose = val if val
     end
 
+
+    # call-seq:
+    #   Shell.cd(path)
+    #
     # Creates a new Shell instance with the current working directory
     # set to +path+.
     def cd(path)
@@ -107,6 +177,11 @@ class Shell
 
   end
 
+  # call-seq:
+  #   Shell.new(pwd, umask) -> obj
+  #
+  # Creates a Shell object which current directory is set to the process
+  # current directory, unless otherwise specified by the +pwd+ argument.
   def initialize(pwd = Dir.pwd, umask = nil)
     @cwd = File.expand_path(pwd)
     @dir_stack = []
@@ -122,6 +197,7 @@ class Shell
     @debug = Shell.debug
   end
 
+  # Returns the command search path in an array
   attr_reader :system_path
 
   # Sets the system path (the Shell instance's PATH environment variable).
@@ -132,7 +208,10 @@ class Shell
     rehash
   end
 
-  attr_accessor :umask, :record_separator
+
+  # Returns the umask
+  attr_accessor :umask
+  attr_accessor :record_separator
   attr_accessor :verbose, :debug
 
   def debug=(val)
@@ -171,6 +250,13 @@ class Shell
   attr_reader :dir_stack
   alias dirs dir_stack
 
+  # call-seq:
+  #   Shell.chdir(path)
+  #
+  # Creates a Shell object which current directory is set to +path+.
+  #
+  # If a block is given, it restores the current directory when the block ends.
+  #
   # If called as iterator, it restores the current directory when the
   # block ends.
   def chdir(path = nil, verbose = @verbose)
@@ -196,6 +282,17 @@ class Shell
   end
   alias cd chdir
 
+  # call-seq:
+  #   pushdir(path)
+  #   pushdir(path) { &block }
+  #
+  # Pushes the current directory to the directory stack, changing the current
+  # directory to +path+.
+  #
+  # If +path+ is omitted, it exchanges its current directory and the top of its
+  # directory stack.
+  #
+  # If a block is given, it restores the current directory when the block ends.
   def pushdir(path = nil, verbose = @verbose)
     check_point
 
@@ -228,6 +325,8 @@ class Shell
   end
   alias pushd pushdir
 
+  # Pops a directory from the directory stack, and sets the current directory
+  # to it.
   def popdir
     check_point
 
@@ -243,36 +342,40 @@ class Shell
   end
   alias popd popdir
 
-  #
-  # process management
-  #
+  # Returns a list of scheduled jobs.
   def jobs
     @process_controller.jobs
   end
 
+  # call-seq:
+  #   kill(signal, job)
+  #
+  # Sends the given +signal+ to the given +job+
   def kill(sig, command)
     @process_controller.kill_job(sig, command)
   end
 
-  #
-  # command definitions
-  #
+  # Convenience method for Shell::CommandProcessor.def_system_command
   def Shell.def_system_command(command, path = command)
     CommandProcessor.def_system_command(command, path)
   end
 
+  # Convenience method for Shell::CommandProcessor.undef_system_command
   def Shell.undef_system_command(command)
     CommandProcessor.undef_system_command(command)
   end
 
+  # Convenience method for Shell::CommandProcessor.alias_command
   def Shell.alias_command(ali, command, *opts, &block)
     CommandProcessor.alias_command(ali, command, *opts, &block)
   end
 
+  # Convenience method for Shell::CommandProcessor.unalias_command
   def Shell.unalias_command(ali)
     CommandProcessor.unalias_command(ali)
   end
 
+  # Convenience method for Shell::CommandProcessor.install_system_commands
   def Shell.install_system_commands(pre = "sys_")
     CommandProcessor.install_system_commands(pre)
   end