summaryrefslogtreecommitdiff
path: root/doc/shell.rd
blob: 8a1f7c5a808998f85da3dec3bba99382f545ec2f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
 -- shell.rb
				$Release Version: 0.6.0 $
			   	$Revision$
			   	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