From 11dbedfaad4a9a9521ece2198a8dc491678b1902 Mon Sep 17 00:00:00 2001
From: shyouhei <shyouhei@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>
Date: Wed, 29 Aug 2007 04:06:12 +0000
Subject: add tag v1_8_6_5001

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/tags/v1_8_6_5001@13304 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
---
 ruby_1_8_6/doc/shell.rd | 348 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 348 insertions(+)
 create mode 100644 ruby_1_8_6/doc/shell.rd

(limited to 'ruby_1_8_6/doc/shell.rd')

diff --git a/ruby_1_8_6/doc/shell.rd b/ruby_1_8_6/doc/shell.rd
new file mode 100644
index 0000000000..02ee1b020a
--- /dev/null
+++ b/ruby_1_8_6/doc/shell.rd
@@ -0,0 +1,348 @@
+ -- shell.rb
+				$Release Version: 0.6.0 $
+			   	$Revision$
+			   	$Date$
+			   	by Keiju ISHITSUKA(keiju@ishitsuka.com)
+
+=begin
+
+= What's shell.rb?
+
+It realizes a wish to do execution of commands with filters and pipes
+like sh/csh by using just native facilities of ruby.
+
+= Main classes
+
+== Shell
+
+Every shell object has its own current working directory, and executes
+each command as if it stands in the directory.
+
+--- Shell#cwd
+--- Shell#dir
+--- Shell#getwd
+--- Shell#pwd
+
+      Returns the current directory
+
+--- Shell#system_path
+
+      Returns the command search path in an array
+
+--- Shell#umask
+
+      Returns the umask
+
+== Filter
+
+Any result of command exection is a Filter.  Filter include
+Enumerable, therefore a Filter object can use all Enumerable
+facilities.
+
+= Main methods
+
+== Command definitions
+
+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#system even if it
+is not defined.
+
+--- Shell.def_system_command(command, path = command)
+
+      Defines a command.  Registers <path> as a Shell method
+      <command>.
+
+      ex)
+      Shell.def_system_command "ls"
+        Defines ls.
+
+      Shell.def_system_command "sys_sort", "sort"
+        Defines sys_sort as sort.
+
+--- Shell.undef_system_command(command)
+
+      Undefines a commmand
+
+--- Shell.alias_command(ali, command, *opts) {...}
+
+      Aliases a command.
+
+      ex)
+        Shell.alias_command "lsC", "ls", "-CBF", "--show-control-chars"
+        Shell.alias_command("lsC", "ls"){|*opts| ["-CBF", "--show-control-chars", *opts]}
+
+--- Shell.unalias_command(ali)
+
+      Unaliases a command.
+
+--- Shell.install_system_commands(pre = "sys_")
+
+      Defines all commands in the default_system_path as Shell method,
+      all with <pre> prefixed to their names.
+
+== Creation
+
+--- Shell.new
+
+      Creates a Shell object which current directory is set to the
+      process current directory.
+
+--- Shell.cd(path)
+
+      Creates a Shell object which current directory is set to
+      <path>.
+
+== Process management
+
+--- Shell#jobs
+
+      Returns a list of scheduled jobs.
+
+--- Shell#kill sig, job
+
+      Sends a signal <sig> to <job>.
+
+== Current directory operations
+
+--- Shell#cd(path, &block)
+--- Shell#chdir
+
+      Changes the current directory to <path>.  If a block is given,
+      it restores the current directory when the block ends.
+
+--- Shell#pushd(path = nil, &block)
+--- Shell#pushdir
+
+      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.
+
+--- Shell#popd
+--- Shell#popdir
+
+      Pops a directory from the directory stack, and sets the current
+      directory to it.
+
+== File and directory operations
+
+--- Shell#foreach(path = nil, &block)
+
+      Same as:
+        File#foreach (when path is a file)
+        Dir#foreach (when path is a directory)
+
+--- Shell#open(path, mode)
+
+      Same as:
+        File#open (when path is a file)
+        Dir#open (when path is a directory)
+
+--- Shell#unlink(path)
+
+      Same as:
+        Dir#open (when path is a file)
+        Dir#unlink (when path is a directory)
+
+--- Shell#test(command, file1, file2)
+--- Shell#[command, file1, file2]
+
+      Same as test().
+      ex)
+          sh[?e, "foo"]
+          sh[:e, "foo"]
+          sh["e", "foo"]
+          sh[:exists?, "foo"]
+          sh["exists?", "foo"]
+
+--- Shell#mkdir(*path)
+
+      Same as Dir.mkdir (with multiple directories allowed)
+
+--- Shell#rmdir(*path)
+
+      Same as Dir.rmdir (with multiple directories allowed)
+
+== Command execution
+
+--- System#system(command, *opts)
+
+      Executes <command> with <opts>.
+
+      ex)
+        print sh.system("ls", "-l")
+        sh.system("ls", "-l") | sh.head > STDOUT
+
+--- System#rehash
+
+      Does rehash.
+
+--- Shell#transact &block
+
+      Executes a block as self.
+      ex)
+        sh.transact{system("ls", "-l") | head > STDOUT}
+
+--- Shell#out(dev = STDOUT, &block)
+
+      Does transact, with redirecting the result output to <dev>.
+
+== Internal commands
+
+--- Shell#echo(*strings)
+--- Shell#cat(*files)
+--- Shell#glob(patten)
+--- Shell#tee(file)
+
+      Return Filter objects, which are results of their execution.
+
+--- Filter#each &block
+
+      Iterates a block for each line of it.
+
+--- Filter#<(src)
+
+      Inputs from <src>, which is either a string of a file name or an
+      IO.
+
+--- Filter#>(to)
+
+      Outputs to <to>, which is either a string of a file name or an
+      IO.
+
+--- Filter#>>(to)
+
+      Appends the ouput to <to>, which is either a string of a file
+      name or an IO.
+
+--- Filter#|(filter)
+
+      Processes a pipeline.
+
+--- Filter#+(filter)
+
+      (filter1 + filter2) outputs filter1, and then outputs filter2.
+
+--- Filter#to_a
+--- Filter#to_s
+
+== Built-in commands
+
+--- Shell#atime(file)
+--- Shell#basename(file, *opt)
+--- Shell#chmod(mode, *files)
+--- Shell#chown(owner, group, *file)
+--- Shell#ctime(file)
+--- Shell#delete(*file)
+--- Shell#dirname(file)
+--- Shell#ftype(file)
+--- Shell#join(*file)
+--- Shell#link(file_from, file_to)
+--- Shell#lstat(file)
+--- Shell#mtime(file)
+--- Shell#readlink(file)
+--- Shell#rename(file_from, file_to)
+--- Shell#split(file)
+--- Shell#stat(file)
+--- Shell#symlink(file_from, file_to)
+--- Shell#truncate(file, length)
+--- Shell#utime(atime, mtime, *file)
+
+      Equivalent to the class methods of File with the same names.
+
+--- 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)
+
+      Equivalent to the class methods of FileTest with the same names.
+
+--- 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)
+
+      Equivalent to the class methods of FileTools with the same
+      names.
+
+      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
+
+= Samples
+
+== ex1
+
+  sh = Shell.cd("/tmp")
+  sh.mkdir "shell-test-1" unless sh.exists?("shell-test-1")
+  sh.cd("shell-test-1")
+  for dir in ["dir1", "dir3", "dir5"]
+    if !sh.exists?(dir)
+      sh.mkdir dir
+      sh.cd(dir) do
+	f = sh.open("tmpFile", "w")
+	f.print "TEST\n"
+	f.close
+      end
+      print sh.pwd
+    end
+  end
+
+== ex2
+
+  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
+
+== ex3
+
+  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"
+
+== ex4
+
+  print sh.cat("/etc/passwd").head.collect{|l| l =~ /keiju/}
+
+=end
-- 
cgit v1.2.3