From d9350f56002fde6b5640b93ae7b8885cb7811d1a Mon Sep 17 00:00:00 2001 From: knu Date: Thu, 17 May 2001 10:02:47 +0000 Subject: Initial revision git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@1418 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- doc/shell.rd | 283 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/shell.rd.jp | 283 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 566 insertions(+) create mode 100644 doc/shell.rd create mode 100644 doc/shell.rd.jp (limited to 'doc') diff --git a/doc/shell.rd b/doc/shell.rd new file mode 100644 index 0000000000..437f035dec --- /dev/null +++ b/doc/shell.rd @@ -0,0 +1,283 @@ +shell.rbユーザガイド + $Release Version: 0.6.0 $ + $Revision$ + $Date$ + by Keiju ISHITSUKA(keiju@ishitsuka.com) + +* What's shell.rb? + +It realizes a wish to do execution of command and filtering like +sh/csh. However, Control statement which include sh/csh just uses +facility of ruby. + +* Main classes +** Shell + +All shell objects have a each unique current directory. Any shell object +execute a command on relative path from current directory. + ++ Shell#cwd/dir/getwd/pwd current directory ++ Shell#system_path command path ++ Shell#umask umask + +** Filter + +Any result of command exection is a Filter. Filter include Enumerable, +therefore a Filter object can use all Enumerable facility. + +* Main methods +** Command definition + +For executing a command on OS, you need to define it as a Shell +method. + +notice) Also, there are a Shell#system alternatively to execute the +command even if it is not defined. + ++ Shell.def_system_command(command, path = command) +Register command as a Shell method + +++ Shell.def_system_command "ls" + define ls +++ Shell.def_system_command "sys_sort", "sort" + define sys_sort as sort + ++ Shell.install_system_commands(pre = "sys_") + +Define all command of default_system_path. Default action prefix +"sys_" to the method name. + +** 生成 + ++ Shell.new +Shell creates a Shell object of which current directory is the process +current directory. + ++ Shell.cd(path) +Shell creates a Shell object of which current directory is . + +** Process management + ++ jobs +The shell returns jobs list of scheduling. + ++ kill sig, job +The shell kill . + +** Current directory operation + ++ Shell#cd(path, &block)/chdir +The current directory of the shell change to . If it is called +with an block, it changes current directory to the while its +block executes. + ++ Shell#pushd(path = nil, &block)/pushdir + +The shell push current directory to directory stack. it changes +current directory to . If the path is omitted, it exchange its +current directory and the top of its directory stack. If it is called +with an block, it do `pushd' the while its block executes. + ++ Shell#popd/popdir +The shell pop a directory from directory stack, and its directory is +changed to current directory. + +** ファイル/ディレクトリ操作 + ++ 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, file] +Same as file testing function test(). +ex) + sh[?e, "foo"] + sh[:e, "foo"] + sh["e", "foo"] + sh[:exists?, "foo"] + sh["exists?", "foo"] + ++ Shell#mkdir(*path) +Same as Dir.mkdir(its parameters is one or more) + ++ Shell#rmdir(*path) +Same as Dir.rmdir(its parameters is one or more) + +** Command execution ++ System#system(command, *opts) +The shell execure . +ex) + print sh.system("ls", "-l") + sh.system("ls", "-l") | sh.head > STDOUT + ++ System#rehash +The shell do rehash. + ++ Shell#transact &block +The shell execute block as self. +ex) + sh.transact{system("ls", "-l") | head > STDOUT} + ++ Shell#out(dev = STDOUT, &block) +The shell do transact, and its result output to dev. + +** Internal Command ++ Shell#echo(*strings) ++ Shell#cat(*files) ++ Shell#glob(patten) ++ Shell#tee(file) + +When these are executed, they return a filter object, which is a +result of their execution. + ++ Filter#each &block +The shell iterate with each line of it. + ++ Filter#<(src) +The shell inputs from src. If src is a string, it inputs from a file +of which name is the string. If src is a IO, it inputs its IO. + ++ Filter#>(to) +The shell outputs to . If is a string, it outputs to a file +of which name is the string. If c is a IO, it outoputs to its IO. + ++ Filter#>>(to) +The shell appends to . If is a string, it is append to a file +of which name is the string. If c is a IO, it is append to its IO. + ++ Filter#|(filter) +pipe combination + ++ Filter#+(filter) +filter1 + filter2 output filter1, and next output filter2. + ++ Filter#to_a ++ Filter#to_s + +** Built-in command + ++ 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) + +These have a same function as a class method which is in File with same name. + ++ 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) + +These have a same function as a class method which is in FileTest with +same name. + ++ 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) + +These have a same function as a class method which is in FileTools +with same name. + +And also, alias: + ++ 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" + +** ex5 + + print sh.cat("/etc/passwd").head.collect{|l| l =~ /keiju/} + diff --git a/doc/shell.rd.jp b/doc/shell.rd.jp new file mode 100644 index 0000000000..0e8c2ee69b --- /dev/null +++ b/doc/shell.rd.jp @@ -0,0 +1,283 @@ +shell.rbユーザガイド + $Release Version: 0.6.0 $ + $Revision$ + $Date$ + by Keiju ISHITSUKA(keiju@ishitsuka.com) + +ruby上でshellっぽいコマンドを使えるようにする. + +* 目的 + +sh/cshのようにコマンドの実行及びフィルタリングを気軽に行いたい. ただし, +sh/cshには制御文があるがそれはrubyの機能をそのまま用いる. + +* 主なクラス一覧 +** Shell + +Shellオブジェクトはカレントディレクトリを持ち, コマンド実行はそこからの +相対パスになります. + ++ Shell#cwd/dir/getwd/pwd カレントディレクトリ ++ Shell#system_path コマンドのパス ++ Shell#umask umask + +** Filter +コマンドの実行結果はFilterとしてかえります. Enumerableをincludeしていま +す. + +* 主なメソッド一覧 +** コマンド定義 + +OS上のコマンドを実行するにはまず, Shellのメソッドとして定義します. +注) コマンドを定義しなくともすむShell#systemコマンドもあります. + ++ Shell.def_system_command(command, path = command) +Shellのメソッドとしてcommandを登録します. + +++ Shell.def_system_command "ls" + ls を定義 +++ Shell.def_system_command "sys_sort", "sort" + sortコマンドをsys_sortとして定義 + ++ Shell.undef_system_command(command) +commandを削除します. + ++ Shell.alias_command(ali, command, *opts) {...} +commandのaliasをします. +例) + Shell.alias_command "lsC", "ls", "-CBF", "--show-control-chars" + Shell.alias_command("lsC", "ls"){|*opts| ["-CBF", "--show-control-chars", *opts]} + ++ Shell.unalias_command(ali) +commandのaliasを削除します. + ++ Shell.install_system_commands(pre = "sys_") +system_path上にある全ての実行可能ファイルをShellに定義する. メソッド名は +元のファイル名の頭にpreをつけたものとなる. + +** 生成 + ++ Shell.new +プロセスのカレントディレクトリをカレントディレクトリとするShellオブジェ +クトを生成します. + ++ Shell.cd(path) +pathをカレントディレクトリとするShellオブジェクトを生成します. + +** プロセス管理 + ++ jobs +スケジューリングされているjobの一覧を返す. + ++ kill sig, job +jobをkillする + +** カレントディレクトリ操作 + ++ Shell#cd(path, &block)/chdir +カレントディレクトリをpathにする. イテレータとして呼ばれたときには, ブロッ +ク実行中のみカレントディレクトリを変更する. + ++ Shell#pushd(path = nil, &block)/pushdir + +カレントディレクトリをディレクトリスタックにつみ, カレントディレクトリを +pathにする. pathが省略されたときには, カレントディレクトリとディレクトリ +スタックのトップを交換する. イテレータとして呼ばれたときには, ブロック実 +行中のみpushdする. + ++ Shell#popd/popdir +ディレクトリスタックからポップし, それをカレントディレクトリにする. + +** ファイル/ディレクトリ操作 + ++ Shell#foreach(path = nil, &block) +pathがファイルなら, File#foreach +pathがディレクトリなら, Dir#foreach + ++ Shell#open(path, mode) +pathがファイルなら, File#open +pathがディレクトリなら, Dir#open + ++ Shell#unlink(path) +pathがファイルなら, File#unlink +pathがディレクトリなら, Dir#unlink + ++ Shell#test(command, file1, file2)/Shell#[command, file1, file] +ファイルテスト関数testと同じ. +例) + sh[?e, "foo"] + sh[:e, "foo"] + sh["e", "foo"] + sh[:exists?, "foo"] + sh["exists?", "foo"] + ++ Shell#mkdir(*path) +Dir.mkdirと同じ(複数可) + ++ Shell#rmdir(*path) +Dir.rmdirと同じ(複数可) + +** コマンド実行 ++ System#system(command, *opts) +commandを実行する. +例) + print sh.system("ls", "-l") + sh.system("ls", "-l") | sh.head > STDOUT + ++ System#rehash +リハッシュする + ++ Shell#transact &block +ブロック中ではshellをselfとして実行する. +例) + sh.transact{system("ls", "-l") | head > STDOUT} + ++ Shell#out(dev = STDOUT, &block) +transactを呼び出しその結果をdevに出力する. + +** 内部コマンド ++ Shell#echo(*strings) ++ Shell#cat(*files) ++ Shell#glob(patten) ++ Shell#tee(file) + +これらは実行すると, それらを内容とするFilterオブジェクトを返します. + ++ Filter#each &block +フィルタの一行ずつをblockに渡す. + ++ Filter#<(src) +srcをフィルタの入力とする. srcが, 文字列ならばファイルを, IOであればそれ +をそのまま入力とする. + ++ Filter#>(to) +srcをフィルタの出力とする. toが, 文字列ならばファイルに, IOであればそれ +をそのまま出力とする. + ++ Filter#>>(to) +srcをフィルタに追加する. toが, 文字列ならばファイルに, IOであればそれを +そのまま出力とする. + ++ Filter#|(filter) +パイプ結合 + ++ Filter#+(filter) +filter1 + filter2 は filter1の出力の後, filter2の出力を行う. + ++ Filter#to_a ++ Filter#to_s + +** 組込みコマンド + ++ 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) + +これらはFileクラスにある同名のクラスメソッドと同じです. + ++ 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) + +これらはFileTestクラスにある同名のクラスメソッドと同じです. + ++ 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) + +これらはFileToolsクラスにある同名のクラスメソッドと同じです. + +その他, 以下のものがエイリアスされています. + ++ Shell#cmp <- Shell#compare ++ Shell#mv <- Shell#move ++ Shell#cp <- Shell#copy ++ Shell#rm_f <- Shell#safe_unlink ++ Shell#mkpath <- Shell#makedirs + +* サンプル +** 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" + +** ex5 + + print sh.cat("/etc/passwd").head.collect{|l| l =~ /keiju/} + -- cgit v1.2.3