[前][次][番号順一覧][スレッド一覧]

ruby-changes:26144

From: zzak <ko1@a...>
Date: Wed, 5 Dec 2012 11:55:23 +0900 (JST)
Subject: [ruby-changes:26144] zzak:r38201 (trunk): * doc/shell.rd, doc/shell.rd.ja: Removed stale doc files

zzak	2012-12-05 11:55:07 +0900 (Wed, 05 Dec 2012)

  New Revision: 38201

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38201

  Log:
    * doc/shell.rd, doc/shell.rd.ja: Removed stale doc files
    * lib/shell.rb, lib/shell/*: Merge and updates docs from doc/shell.rd*

  Modified files:
    trunk/ChangeLog
    trunk/lib/shell/command-processor.rb
    trunk/lib/shell/filter.rb
    trunk/lib/shell/version.rb
    trunk/lib/shell.rb

Index: ChangeLog
===================================================================
--- ChangeLog	(revision 38200)
+++ ChangeLog	(revision 38201)
@@ -1,3 +1,8 @@
+Wed Dec  5 11:55:00 2012  Zachary Scott  <zachary@z...>
+
+	* doc/shell.rd, doc/shell.rd.ja: Removed stale doc files
+	* lib/shell.rb, lib/shell/*: Merge and updates docs from doc/shell.rd*
+
 Wed Dec  5 11:42:38 2012  Koichi Sasada  <ko1@a...>
 
 	* test/ruby/test_settracefunc.rb: disable trace.
Index: lib/shell.rb
===================================================================
--- lib/shell.rb	(revision 38200)
+++ lib/shell.rb	(revision 38201)
@@ -20,6 +20,72 @@
 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 @@
       @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 @@
 
   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 @@
     @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 @@
     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 @@
   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 @@
   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 @@
   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 @@
   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
Index: lib/shell/filter.rb
===================================================================
--- lib/shell/filter.rb	(revision 38200)
+++ lib/shell/filter.rb	(revision 38201)
@@ -9,11 +9,12 @@
 #
 #
 
-class Shell
+class Shell #:nodoc:
+  # Any result of command exection is a Filter.
   #
-  # Filter
-  # A method to require
-  #    each()
+  # This class includes Enumerable, therefore a Filter object can use all
+  # Enumerable
+  # facilities.
   #
   class Filter
     include Enumerable
@@ -29,6 +30,10 @@
       @input = filter
     end
 
+    # call-seq:
+    #   each(record_separator=nil) { block }
+    #
+    # Iterates a block for each line.
     def each(rs = nil)
       rs = @shell.record_separator unless rs
       if @input
@@ -36,6 +41,11 @@
       end
     end
 
+    # call-seq:
+    #   < source
+    #
+    # Inputs from +source+, which is either a string of a file name or an IO
+    # object.
     def < (src)
       case src
       when String
@@ -49,6 +59,11 @@
       end
     end
 
+    # call-seq:
+    #   > source
+    #
+    # Outputs from +source+, which is either a string of a file name or an IO
+    # object.
     def > (to)
       case to
       when String
@@ -66,6 +81,11 @@
       self
     end
 
+    # call-seq:
+    #   >> source
+    #
+    # Appends the output to +source+, which is either a string of a file name
+    # or an IO object.
     def >> (to)
       begin
         Shell.cd(@shell.pwd).append(to, self)
@@ -74,6 +94,10 @@
       end
     end
 
+    # call-seq:
+    #   | filter
+    #
+    # Processes a pipeline.
     def | (filter)
       filter.input = self
       if active?
@@ -82,6 +106,10 @@
       filter
     end
 
+    # call-seq:
+    #   filter1 + filter2
+    #
+    # Outputs +filter1+, and then +filter2+ using Join.new
     def + (filter)
       Join.new(@shell, self, filter)
     end
Index: lib/shell/version.rb
===================================================================
--- lib/shell/version.rb	(revision 38200)
+++ lib/shell/version.rb	(revision 38201)
@@ -9,7 +9,7 @@
 #
 #
 
-class Shell
+class Shell # :nodoc:
   @RELEASE_VERSION = "0.7"
   @LAST_UPDATE_DATE = "07/03/20"
 end
Index: lib/shell/command-processor.rb
===================================================================
--- lib/shell/command-processor.rb	(revision 38200)
+++ lib/shell/command-processor.rb	(revision 38201)
@@ -18,6 +18,11 @@
 require "shell/builtin-command"
 
 class Shell
+  # In order to execute a command on your OS, you need to define it as a
+  # Shell method.
+  #
+  # Alternatively, you can execute any command via
+  # Shell::CommandProcessor#system even if it is not defined.
   class CommandProcessor
 #    include Error
 
@@ -76,24 +81,14 @@
       @shell.expand_path(path)
     end
 
+    # call-seq:
+    #   foreach(path, record_separator) -> Enumerator
+    #   foreach(path, record_separator) { block }
     #
-    # File related commands
-    # Shell#foreach
-    # Shell#open
-    # Shell#unlink
-    # Shell#test
+    # See IO.foreach when +path+ is a file.
     #
-    # -
+    # See Dir.foreach when +path+ is a directory.
     #
-    # 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
-    #
     def foreach(path = nil, *rs)
       path = "." unless path
       path = expand_path(path)
@@ -105,16 +100,14 @@
       end
     end
 
+    # call-seq:
+    #   open(path, mode, permissions) -> Enumerator
+    #   open(path, mode, permissions) { block }
     #
-    # 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
+    # See IO.open when +path+ is a file.
     #
+    # See Dir.open when +path+ is a directory.
+    #
     def open(path, mode = nil, perm = 0666, &b)
       path = expand_path(path)
       if File.directory?(path)
@@ -134,12 +127,13 @@
     end
     #  public :open
 
+    # call-seq:
+    #   unlink(path)
     #
-    # CommandProcessor#unlink(path)
-    #   same as:
-    #     Dir#unlink  (when path is directory)
-    #     File#unlink (when path is file)
+    # See IO.unlink when +path+ is a file.
     #
+    # See Dir.unlink when +path+ is a directory.
+    #
     def unlink(path)
       @shell.check_point
 
@@ -152,24 +146,21 @@
       Void.new(@shell)
     end
 
+    # See Shell::CommandProcessor#test
+    alias top_level_test test
+    # call-seq:
+    #   test(command, file1, file2) ->  true or false
+    #   [command, file1, file2] ->  true or false
     #
-    # 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:
+    # Tests if the given +command+ exists in +file1+, or optionally +file2+.
+    #
+    # Example:
     #     sh[?e, "foo"]
     #     sh[:e, "foo"]
     #     sh["e", "foo"]
     #     sh[:exists?, "foo"]
     #     sh["exists?", "foo"]
     #
-    alias top_level_test test
     def test(command, file1, file2=nil)
       file1 = expand_path(file1)
       file2 = expand_path(file2) if file2
@@ -198,20 +189,13 @@
         end
       end
     end
+    # See Shell::CommandProcessor#test
     alias [] test
 
+    # call-seq:
+    #   mkdir(path)
     #
-    # Dir related methods
-    #
-    # Shell#mkdir
-    # Shell#rmdir
-    #
-    #--
-    #
-    # CommandProcessor#mkdir(*path)
-    #     path: String
-    #   same as Dir.mkdir()
-    #
+    # Same as Dir.mkdir, except multiple directories are allowed.
     def mkdir(*path)
       @shell.check_point
       notify("mkdir #{path.join(' ')}")
@@ -232,11 +216,10 @@
       Void.new(@shell)
     end
 
+    # call-seq:
+    #   rmdir(path)
     #
-    # CommandProcessor#rmdir(*path)
-    #     path: String
-    #   same as Dir.rmdir()
-    #
+    # Same as Dir.rmdir, except multiple directories are allowed.
     def rmdir(*path)
       @shell.check_point
       notify("rmdir #{path.join(' ')}")
@@ -247,13 +230,12 @@
       Void.new(@shell)
     end
 
+    # call-seq:
+    #   system(command, *options) -> SystemCommand
     #
-    # CommandProcessor#system(command, *opts)
-    #     command: String
-    #     opts:    String
-    #     return:  SystemCommand
-    #   Same as system() function
-    #   example:
+    # Executes the given +command+ with the +options+ parameter.
+    #
+    # Example:
     #     print sh.system("ls", "-l")
     #     sh.system("ls", "-l") | sh.head > STDOUT
     #
@@ -268,22 +250,26 @@
       SystemCommand.new(@shell, find_system_command(command), *opts)
     end
 
+    # call-seq:
+    #   rehash
     #
-    # ProcessCommand#rehash
-    #   clear command hash table.
-    #
+    # Clears the command hash table.
     def rehash
       @system_commands = {}
     end
 
-    #
-    # ProcessCommand#transact
-    #
-    def check_point
+    def check_point # :nodoc:
       @shell.process_controller.wait_all_jobs_execution
     end
-    alias finish_all_jobs check_point
+    alias finish_all_jobs check_point # :nodoc:
 
+    # call-seq:
+    #   transact { block }
+    #
+    # Executes a block as self
+    #
+    # Example:
+    #   sh.transact { system("ls", "-l") | head > STDOUT }
     def transact(&block)
       begin
         @shell.instance_eval(&block)
@@ -292,17 +278,27 @@
       end
     end
 
+    # call-seq:
+    #   out(device) { block }
     #
-    # internal commands
-    #
+    # Calls <code>device.print</code> on the result passing the _block_ to
+    # #transact
     def out(dev = STDOUT, &block)
       dev.print transact(&block)
     end
 
+    # call-seq:
+    #   echo(*strings) ->  Echo
+    #
+    # Returns a Echo object, for the given +strings+
     def echo(*strings)
       Echo.new(@shell, *strings)
     end
 
+    # call-seq:
+    #   cat(*filename) ->  Cat
+    #
+    # Returns a Cat object, for the given +filenames+
     def cat(*filenames)
       Cat.new(@shell, *filenames)
     end
@@ -310,7 +306,10 @@
     #   def sort(*filenames)
     #     Sort.new(self, *filenames)
     #   end
-
+    # call-seq:
+    #   glob(pattern) ->  Glob
+    #
+    # Returns a Glob filter object, with the given +pattern+ object
     def glob(pattern)
       Glob.new(@shell, pattern)
     end
@@ -326,10 +325,18 @@
       end
     end
 
+    # call-seq:
+    #   tee(file) ->  Tee
+    #
+    # Returns a Tee filter object, with the given +file+ command
     def tee(file)
       Tee.new(@shell, file)
     end
 
+    # call-seq:
+    #   concat(*jobs) ->  Concat
+    #
+    # Returns a Concat object, for the given +jobs+
     def concat(*jobs)
       Concat.new(@shell, *jobs)
     end
@@ -371,12 +378,18 @@
       Shell.Fail Error::CommandNotFound, command
     end
 
+    # call-seq:
+    #   def_system_command(command, path)  ->  Shell::SystemCommand
     #
-    # CommandProcessor.def_system_command(command, path)
-    #     command:  String
-    #     path:     String
-    #   define 'command()' method as method.
+    # Defines a command, registering +path+ as a Shell method for the given
+    # +command+.
     #
+    #     Shell::CommandProcessor.def_system_command "ls"
+    #       #=> Defines ls.
+    #
+    #     Shell::CommandProcessor.def_system_command "sys_sort", "sort"
+    #       #=> Defines sys_sort as sort
+    #
     def self.def_system_command(command, path = command)
       begin
         eval((d = %Q[def #{command}(*opts)
@@ -390,6 +403,10 @@
              Shell.debug.kind_of?(Integer) && Shell.debug > 1)
     end
 
+    # call-seq:
+    #   undef_system_command(command) ->  self
+    #
+    # Undefines a command
     def self.undef_system_command(command)
       command = command.id2name if command.kind_of?(Symbol)
       remove_method(command)
@@ -398,15 +415,20 @@
       self
     end
 
-    # define command alias
-    # ex)
-    # def_alias_command("ls_c", "ls", "-C", "-F")
-    # def_alias_command("ls_c", "ls"){|*opts| ["-C", "-F", *opts]}
-    #
     @alias_map = {}
+    # Returns a list of aliased commands
     def self.alias_map
       @alias_map
     end
+    # call-seq:
+    #   alias_command(alias, command, *options) ->  self
+    #
+    # Creates a command alias at the given +alias+ for the given +command+,
+    # passing any +options+ along with it.
+    #
+    #     Shell::CommandProcessor.alias_command "lsC", "ls", "-CBF", "--show-control-chars"
+    #     Shell::CommandProcessor.alias_command("lsC", "ls"){|*opts| ["-CBF", "--show-control-chars", *opts]}
+    #
     def self.alias_command(ali, command, *opts)
       ali = ali.id2name if ali.kind_of?(Symbol)
       command = command.id2name if command.kind_of?(Symbol)
@@ -436,23 +458,58 @@
       self
     end
 
+    # call-seq:
+    #   unalias_command(alias)  ->  self
+    #
+    # Unaliases the given +alias+ command.
     def self.unalias_command(ali)
       ali = ali.id2name if ali.kind_of?(Symbol)
       @alias_map.delete ali.intern
       undef_system_command(ali)
     end
 
+    # :nodoc:
     #
-    # 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,...)
+    # Delegates File and FileTest methods into Shell, including the following
+    # commands:
     #
+    # * Shell#blockdev?(file)
+    # * Shell#chardev?(file)
+    # * Shell#directory?(file)
+    # * Shell#executable?(file)
+    # * Shell#executable_real?(file)
+    # * Shell#exist?(file)/Shell#exists?(file)
+    # * Shell#file?(file)
+    # * Shell#grpowned?(file)
+    # * Shell#owned?(file)
+    # * Shell#pipe?(file)
+    # * Shell#readable?(file)
+    # * Shell#readable_real?(file)
+    # * Shell#setgid?(file)
+    # * Shell#setuid?(file)
+    # * Shell#size(file)/Shell#size?(file)
+    # * Shell#socket?(file)
+    # * Shell#sticky?(file)
+    # * Shell#symlink?(file)
+    # * Shell#writable?(file)
+    # * Shell#writable_real?(file)
+    # * Shell#zero?(file)
+    # * Shell#syscopy(filename_from, filename_to)
+    # * Shell#copy(filename_from, filename_to)
+    # * Shell#move(filename_from, filename_to)
+    # * Shell#compare(filename_from, filename_to)
+    # * Shell#safe_unlink(*filenames)
+    # * Shell#makedirs(*filenames)
+    # * Shell#install(filename_from, filename_to, mode)
+    #
+    # And also, there are some aliases for convenience:
+    #
+    # * Shell#cmp	<- Shell#compare
+    # * Shell#mv	<- Shell#move
+    # * Shell#cp	<- Shell#copy
+    # * Shell#rm_f	<- Shell#safe_unlink
+    # * Shell#mkpath	<- Shell#makedirs
+    #
     def self.def_builtin_commands(delegation_class, command_specs)
       for meth, args in command_specs
         arg_str = args.collect{|arg| arg.downcase}.join(", ")
@@ -478,15 +53 (... truncated)

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/

[前][次][番号順一覧][スレッド一覧]