* lib/un.rb: add descriptions.

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@4234 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 103 insertions, 21 deletions

diff --git a/lib/un.rb b/lib/un.rb
index 3834784f2d..8f630801d8 100644
--- a/lib/un.rb
+++ b/lib/un.rb
@@ -1,3 +1,25 @@
+# 
+# = un.rb
+# 
+# Copyright (c) 2003 WATANABE Hirofumi <eban@ruby-lang.org>
+# 
+# This program is free software.
+# You can distribute/modify this program under the same terms of Ruby.
+# 
+# == Utilities to replace common UNIX commands in Makefiles etc
+#
+# == SYNOPSIS
+#
+#   ruby -run -e cp -- [OPTION] SOURCE DEST
+#   ruby -run -e ln -- [OPTION] TARGET LINK_NAME
+#   ruby -run -e mv -- [OPTION] SOURCE DEST
+#   ruby -run -e rm -- [OPTION] FILE
+#   ruby -run -e mkdir -- [OPTION] DIRS
+#   ruby -run -e rmdir -- [OPTION] DIRS
+#   ruby -run -e install -- [OPTION] SOURCE DEST
+#   ruby -run -e chmod -- [OPTION] OCTAL-MODE FILE
+#   ruby -run -e touch -- [OPTION] FILE
+
 require 'fileutils'
 require 'getopts'
 
@@ -28,20 +50,32 @@ def setup(options = "")
   yield ARGV, options, $OPT
 end
 
-def mkdir
-  setup("p") do |argv, options, opt|
-    cmd = "mkdir"
-    cmd += "_p" if options.delete :preserve
-    FileUtils.send cmd, argv, options
-  end
-end
-
-def rmdir
-  setup do |argv, options|
-    FileUtils.rmdir argv, options
+#
+# Copy SOURCE to DEST, or multiple SOURCE(s) to DIRECTORY
+#
+#   ruby -run -e cp -- [OPTION] SOURCE DEST
+#
+#   -p		preserve file attributes if possible
+#   -r		copy recursively
+#
+def cp
+  setup("pr") do |argv, options, opt|
+    cmd = "cp"
+    cmd += "_r" if opt["r"]
+    dest = argv.pop
+    argv = argv[0] if argv.size == 1
+    FileUtils.send cmd, argv, dest, options
   end
 end
 
+#
+# Create a link to the specified TARGET with LINK_NAME.
+#
+#   ruby -run -e ln -- [OPTION] TARGET LINK_NAME
+#
+#   -s		make symbolic links instead of hard links
+#   -f		remove existing destination files
+#
 def ln
   setup("sf") do |argv, options, opt|
     cmd = "ln"
@@ -52,16 +86,11 @@ def ln
   end
 end
 
-def cp
-  setup("pr") do |argv, options, opt|
-    cmd = "cp"
-    cmd += "_r" if opt["r"]
-    dest = argv.pop
-    argv = argv[0] if argv.size == 1
-    FileUtils.send cmd, argv, dest, options
-  end
-end
-
+#
+# Rename SOURCE to DEST, or move SOURCE(s) to DIRECTORY.
+#
+#   ruby -run -e mv SOURCE DEST
+#
 def mv
   setup do |argv, options|
     dest = argv.pop
@@ -70,6 +99,14 @@ def mv
   end
 end
 
+#
+# Remove the FILE
+#
+#   ruby -run -e rm -- [OPTION] FILE
+#
+#   -f		ignore nonexistent files
+#   -r		remove the contents of directories recursively
+#
 def rm
   setup("fr") do |argv, options, opt|
     cmd = "rm"
@@ -78,6 +115,41 @@ def rm
   end
 end
 
+#
+# Create the DIR, if they do not already exist.
+#
+#   ruby -run -e mkdir -- [OPTION] DIR
+#
+#   -p		no error if existing, make parent directories as needed
+#
+def mkdir
+  setup("p") do |argv, options, opt|
+    cmd = "mkdir"
+    cmd += "_p" if options.delete :preserve
+    FileUtils.send cmd, argv, options
+  end
+end
+
+#
+# Remove the DIR.
+#
+#   ruby -run -e rmdir DIR
+#
+def rmdir
+  setup do |argv, options|
+    FileUtils.rmdir argv, options
+  end
+end
+
+#
+# Copy SOURCE to DEST.
+#
+#   ruby -run -e install -- [OPTION] SOURCE DEST
+#
+#   -p		apply access/modification times of SOURCE files to
+#  		corresponding destination files
+#   -m		set permission mode (as in chmod), instead of 0755
+#
 def install
   setup("pm:") do |argv, options, opt|
     options[:mode] = opt["m"] ? opt["m"].oct : 0755
@@ -87,6 +159,11 @@ def install
   end
 end
 
+#
+# Change the mode of each FILE to OCTAL-MODE.
+#
+#   ruby -run -e chmod OCTAL-MODE FILE
+#
 def chmod
   setup do |argv, options|
     mode = argv.shift.oct
@@ -94,6 +171,11 @@ def chmod
   end
 end
 
+#
+# Update the access and modification times of each FILE to the current time.
+#
+#   ruby -run -e touch FILE
+#
 def touch
   setup do |argv, options|
     FileUtils.touch argv, options