doc/shell.rd

   1  -- shell.rb
   2                                 $Release Version: 0.6.0 $
   3                                 $Revision$
   4                                 by Keiju ISHITSUKA(keiju@ishitsuka.com)
   5
   6 =begin
   7
   8 = What's shell.rb?
   9
  10 It realizes a wish to do execution of commands with filters and pipes
  11 like sh/csh by using just native facilities of ruby.
  12
  13 = Main classes
  14
  15 == Shell
  16
  17 Every shell object has its own current working directory, and executes
  18 each command as if it stands in the directory.
  19
  20 --- Shell#cwd
  21 --- Shell#dir
  22 --- Shell#getwd
  23 --- Shell#pwd
  24
  25       Returns the current directory
  26
  27 --- Shell#system_path
  28
  29       Returns the command search path in an array
  30
  31 --- Shell#umask
  32
  33       Returns the umask
  34
  35 == Filter
  36
  37 Any result of command exection is a Filter.  Filter include
  38 Enumerable, therefore a Filter object can use all Enumerable
  39 facilities.
  40
  41 = Main methods
  42
  43 == Command definitions
  44
  45 In order to execute a command on your OS, you need to define it as a
  46 Shell method.
  47
  48 Alternatively, you can execute any command via Shell#system even if it
  49 is not defined.
  50
  51 --- Shell.def_system_command(command, path = command)
  52
  53       Defines a command.  Registers <path> as a Shell method
  54       <command>.
  55
  56       ex)
  57       Shell.def_system_command "ls"
  58         Defines ls.
  59
  60       Shell.def_system_command "sys_sort", "sort"
  61         Defines sys_sort as sort.
  62
  63 --- Shell.undef_system_command(command)
  64
  65       Undefines a commmand
  66
  67 --- Shell.alias_command(ali, command, *opts) {...}
  68
  69       Aliases a command.
  70
  71       ex)
  72         Shell.alias_command "lsC", "ls", "-CBF", "--show-control-chars"
  73         Shell.alias_command("lsC", "ls"){|*opts| ["-CBF", "--show-control-chars", *opts]}
  74
  75 --- Shell.unalias_command(ali)
  76
  77       Unaliases a command.
  78
  79 --- Shell.install_system_commands(pre = "sys_")
  80
  81       Defines all commands in the default_system_path as Shell method,
  82       all with <pre> prefixed to their names.
  83
  84 == Creation
  85
  86 --- Shell.new
  87
  88       Creates a Shell object which current directory is set to the
  89       process current directory.
  90
  91 --- Shell.cd(path)
  92
  93       Creates a Shell object which current directory is set to
  94       <path>.
  95
  96 == Process management
  97
  98 --- Shell#jobs
  99
 100       Returns a list of scheduled jobs.
 101
 102 --- Shell#kill sig, job
 103
 104       Sends a signal <sig> to <job>.
 105
 106 == Current directory operations
 107
 108 --- Shell#cd(path, &block)
 109 --- Shell#chdir
 110
 111       Changes the current directory to <path>.  If a block is given,
 112       it restores the current directory when the block ends.
 113
 114 --- Shell#pushd(path = nil, &block)
 115 --- Shell#pushdir
 116
 117       Pushes the current directory to the directory stack, changing
 118       the current directory to <path>.  If <path> is omitted, it
 119       exchanges its current directory and the top of its directory
 120       stack.  If a block is given, it restores the current directory
 121       when the block ends.
 122
 123 --- Shell#popd
 124 --- Shell#popdir
 125
 126       Pops a directory from the directory stack, and sets the current
 127       directory to it.
 128
 129 == File and directory operations
 130
 131 --- Shell#foreach(path = nil, &block)
 132
 133       Same as:
 134         File#foreach (when path is a file)
 135         Dir#foreach (when path is a directory)
 136
 137 --- Shell#open(path, mode)
 138
 139       Same as:
 140         File#open (when path is a file)
 141         Dir#open (when path is a directory)
 142
 143 --- Shell#unlink(path)
 144
 145       Same as:
 146         Dir#open (when path is a file)
 147         Dir#unlink (when path is a directory)
 148
 149 --- Shell#test(command, file1, file2)
 150 --- Shell#[command, file1, file2]
 151
 152       Same as test().
 153       ex)
 154           sh[?e, "foo"]
 155           sh[:e, "foo"]
 156           sh["e", "foo"]
 157           sh[:exists?, "foo"]
 158           sh["exists?", "foo"]
 159
 160 --- Shell#mkdir(*path)
 161
 162       Same as Dir.mkdir (with multiple directories allowed)
 163
 164 --- Shell#rmdir(*path)
 165
 166       Same as Dir.rmdir (with multiple directories allowed)
 167
 168 == Command execution
 169
 170 --- System#system(command, *opts)
 171
 172       Executes <command> with <opts>.
 173
 174       ex)
 175         print sh.system("ls", "-l")
 176         sh.system("ls", "-l") | sh.head > STDOUT
 177
 178 --- System#rehash
 179
 180       Does rehash.
 181
 182 --- Shell#transact &block
 183
 184       Executes a block as self.
 185       ex)
 186         sh.transact{system("ls", "-l") | head > STDOUT}
 187
 188 --- Shell#out(dev = STDOUT, &block)
 189
 190       Does transact, with redirecting the result output to <dev>.
 191
 192 == Internal commands
 193
 194 --- Shell#echo(*strings)
 195 --- Shell#cat(*files)
 196 --- Shell#glob(patten)
 197 --- Shell#tee(file)
 198
 199       Return Filter objects, which are results of their execution.
 200
 201 --- Filter#each &block
 202
 203       Iterates a block for each line of it.
 204
 205 --- Filter#<(src)
 206
 207       Inputs from <src>, which is either a string of a file name or an
 208       IO.
 209
 210 --- Filter#>(to)
 211
 212       Outputs to <to>, which is either a string of a file name or an
 213       IO.
 214
 215 --- Filter#>>(to)
 216
 217       Appends the ouput to <to>, which is either a string of a file
 218       name or an IO.
 219
 220 --- Filter#|(filter)
 221
 222       Processes a pipeline.
 223
 224 --- Filter#+(filter)
 225
 226       (filter1 + filter2) outputs filter1, and then outputs filter2.
 227
 228 --- Filter#to_a
 229 --- Filter#to_s
 230
 231 == Built-in commands
 232
 233 --- Shell#atime(file)
 234 --- Shell#basename(file, *opt)
 235 --- Shell#chmod(mode, *files)
 236 --- Shell#chown(owner, group, *file)
 237 --- Shell#ctime(file)
 238 --- Shell#delete(*file)
 239 --- Shell#dirname(file)
 240 --- Shell#ftype(file)
 241 --- Shell#join(*file)
 242 --- Shell#link(file_from, file_to)
 243 --- Shell#lstat(file)
 244 --- Shell#mtime(file)
 245 --- Shell#readlink(file)
 246 --- Shell#rename(file_from, file_to)
 247 --- Shell#split(file)
 248 --- Shell#stat(file)
 249 --- Shell#symlink(file_from, file_to)
 250 --- Shell#truncate(file, length)
 251 --- Shell#utime(atime, mtime, *file)
 252
 253       Equivalent to the class methods of File with the same names.
 254
 255 --- Shell#blockdev?(file)
 256 --- Shell#chardev?(file)
 257 --- Shell#directory?(file)
 258 --- Shell#executable?(file)
 259 --- Shell#executable_real?(file)
 260 --- Shell#exist?(file)/Shell#exists?(file)
 261 --- Shell#file?(file)
 262 --- Shell#grpowned?(file)
 263 --- Shell#owned?(file)
 264 --- Shell#pipe?(file)
 265 --- Shell#readable?(file)
 266 --- Shell#readable_real?(file)
 267 --- Shell#setgid?(file)
 268 --- Shell#setuid?(file)
 269 --- Shell#size(file)/Shell#size?(file)
 270 --- Shell#socket?(file)
 271 --- Shell#sticky?(file)
 272 --- Shell#symlink?(file)
 273 --- Shell#writable?(file)
 274 --- Shell#writable_real?(file)
 275 --- Shell#zero?(file)
 276
 277       Equivalent to the class methods of FileTest with the same names.
 278
 279 --- Shell#syscopy(filename_from, filename_to)
 280 --- Shell#copy(filename_from, filename_to)
 281 --- Shell#move(filename_from, filename_to)
 282 --- Shell#compare(filename_from, filename_to)
 283 --- Shell#safe_unlink(*filenames)
 284 --- Shell#makedirs(*filenames)
 285 --- Shell#install(filename_from, filename_to, mode)
 286
 287       Equivalent to the class methods of FileTools with the same
 288       names.
 289
 290       And also, there are some aliases for convenience:
 291
 292 --- Shell#cmp   <- Shell#compare
 293 --- Shell#mv    <- Shell#move
 294 --- Shell#cp    <- Shell#copy
 295 --- Shell#rm_f  <- Shell#safe_unlink
 296 --- Shell#mkpath        <- Shell#makedirs
 297
 298 = Samples
 299
 300 == ex1
 301
 302   sh = Shell.cd("/tmp")
 303   sh.mkdir "shell-test-1" unless sh.exists?("shell-test-1")
 304   sh.cd("shell-test-1")
 305   for dir in ["dir1", "dir3", "dir5"]
 306     if !sh.exists?(dir)
 307       sh.mkdir dir
 308       sh.cd(dir) do
 309         f = sh.open("tmpFile", "w")
 310         f.print "TEST\n"
 311         f.close
 312       end
 313       print sh.pwd
 314     end
 315   end
 316
 317 == ex2
 318
 319   sh = Shell.cd("/tmp")
 320   sh.transact do
 321     mkdir "shell-test-1" unless exists?("shell-test-1")
 322     cd("shell-test-1")
 323     for dir in ["dir1", "dir3", "dir5"]
 324       if !exists?(dir)
 325         mkdir dir
 326         cd(dir) do
 327           f = open("tmpFile", "w")
 328           f.print "TEST\n"
 329           f.close
 330         end
 331         print pwd
 332       end
 333     end
 334   end
 335
 336 == ex3
 337
 338   sh.cat("/etc/printcap") | sh.tee("tee1") > "tee2"
 339   (sh.cat < "/etc/printcap") | sh.tee("tee11") > "tee12"
 340   sh.cat("/etc/printcap") | sh.tee("tee1") >> "tee2"
 341   (sh.cat < "/etc/printcap") | sh.tee("tee11") >> "tee12"
 342
 343 == ex4
 344
 345   print sh.cat("/etc/passwd").head.collect{|l| l =~ /keiju/}
 346
 347 =end