ruby-changes:16794
From: akr <ko1@a...>
Date: Fri, 30 Jul 2010 06:23:58 +0900 (JST)
Subject: [ruby-changes:16794] Ruby:r28789 (trunk): class description document moved.
akr 2010-07-30 06:13:34 +0900 (Fri, 30 Jul 2010) New Revision: 28789 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=28789 Log: class description document moved. Modified files: trunk/ext/pathname/lib/pathname.rb trunk/ext/pathname/pathname.c Index: ext/pathname/lib/pathname.rb =================================================================== --- ext/pathname/lib/pathname.rb (revision 28788) +++ ext/pathname/lib/pathname.rb (revision 28789) @@ -13,183 +13,6 @@ require 'pathname.so' -# -# == Pathname -# -# Pathname represents a pathname which locates a file in a filesystem. -# The pathname depends on OS: Unix, Windows, etc. -# Pathname library works with pathnames of local OS. -# However non-Unix pathnames are supported experimentally. -# -# It does not represent the file itself. -# A Pathname can be relative or absolute. It's not until you try to -# reference the file that it even matters whether the file exists or not. -# -# Pathname is immutable. It has no method for destructive update. -# -# The value of this class is to manipulate file path information in a neater -# way than standard Ruby provides. The examples below demonstrate the -# difference. *All* functionality from File, FileTest, and some from Dir and -# FileUtils is included, in an unsurprising way. It is essentially a facade for -# all of these, and more. -# -# == Examples -# -# === Example 1: Using Pathname -# -# require 'pathname' -# pn = Pathname.new("/usr/bin/ruby") -# size = pn.size # 27662 -# isdir = pn.directory? # false -# dir = pn.dirname # Pathname:/usr/bin -# base = pn.basename # Pathname:ruby -# dir, base = pn.split # [Pathname:/usr/bin, Pathname:ruby] -# data = pn.read -# pn.open { |f| _ } -# pn.each_line { |line| _ } -# -# === Example 2: Using standard Ruby -# -# pn = "/usr/bin/ruby" -# size = File.size(pn) # 27662 -# isdir = File.directory?(pn) # false -# dir = File.dirname(pn) # "/usr/bin" -# base = File.basename(pn) # "ruby" -# dir, base = File.split(pn) # ["/usr/bin", "ruby"] -# data = File.read(pn) -# File.open(pn) { |f| _ } -# File.foreach(pn) { |line| _ } -# -# === Example 3: Special features -# -# p1 = Pathname.new("/usr/lib") # Pathname:/usr/lib -# p2 = p1 + "ruby/1.8" # Pathname:/usr/lib/ruby/1.8 -# p3 = p1.parent # Pathname:/usr -# p4 = p2.relative_path_from(p3) # Pathname:lib/ruby/1.8 -# pwd = Pathname.pwd # Pathname:/home/gavin -# pwd.absolute? # true -# p5 = Pathname.new "." # Pathname:. -# p5 = p5 + "music/../articles" # Pathname:music/../articles -# p5.cleanpath # Pathname:articles -# p5.realpath # Pathname:/home/gavin/articles -# p5.children # [Pathname:/home/gavin/articles/linux, ...] -# -# == Breakdown of functionality -# -# === Core methods -# -# These methods are effectively manipulating a String, because that's -# all a path is. Except for #mountpoint?, #children, #each_child, -# #realdirpath and #realpath, they don't access the filesystem. -# -# - + -# - #join -# - #parent -# - #root? -# - #absolute? -# - #relative? -# - #relative_path_from -# - #each_filename -# - #cleanpath -# - #realpath -# - #realdirpath -# - #children -# - #each_child -# - #mountpoint? -# -# === File status predicate methods -# -# These methods are a facade for FileTest: -# - #blockdev? -# - #chardev? -# - #directory? -# - #executable? -# - #executable_real? -# - #exist? -# - #file? -# - #grpowned? -# - #owned? -# - #pipe? -# - #readable? -# - #world_readable? -# - #readable_real? -# - #setgid? -# - #setuid? -# - #size -# - #size? -# - #socket? -# - #sticky? -# - #symlink? -# - #writable? -# - #world_writable? -# - #writable_real? -# - #zero? -# -# === File property and manipulation methods -# -# These methods are a facade for File: -# - #atime -# - #ctime -# - #mtime -# - #chmod(mode) -# - #lchmod(mode) -# - #chown(owner, group) -# - #lchown(owner, group) -# - #fnmatch(pattern, *args) -# - #fnmatch?(pattern, *args) -# - #ftype -# - #make_link(old) -# - #open(*args, &block) -# - #readlink -# - #rename(to) -# - #stat -# - #lstat -# - #make_symlink(old) -# - #truncate(length) -# - #utime(atime, mtime) -# - #basename(*args) -# - #dirname -# - #extname -# - #expand_path(*args) -# - #split -# -# === Directory methods -# -# These methods are a facade for Dir: -# - Pathname.glob(*args) -# - Pathname.getwd / Pathname.pwd -# - #rmdir -# - #entries -# - #each_entry(&block) -# - #mkdir(*args) -# - #opendir(*args) -# -# === IO -# -# These methods are a facade for IO: -# - #each_line(*args, &block) -# - #read(*args) -# - #binread(*args) -# - #readlines(*args) -# - #sysopen(*args) -# -# === Utilities -# -# These methods are a mixture of Find, FileUtils, and others: -# - #find(&block) -# - #mkpath -# - #rmtree -# - #unlink / #delete -# -# -# == Method documentation -# -# As the above section shows, most of the methods in Pathname are facades. The -# documentation for these methods generally just says, for instance, "See -# FileTest.writable?", as you should be familiar with the original method -# anyway, and its documentation (e.g. through +ri+) will contain more -# information. In some cases, a brief description will follow. -# class Pathname # :stopdoc: Index: ext/pathname/pathname.c =================================================================== --- ext/pathname/pathname.c (revision 28788) +++ ext/pathname/pathname.c (revision 28789) @@ -119,6 +119,183 @@ return INT2FIX(0); } +/* + * == Pathname + * + * Pathname represents a pathname which locates a file in a filesystem. + * The pathname depends on OS: Unix, Windows, etc. + * Pathname library works with pathnames of local OS. + * However non-Unix pathnames are supported experimentally. + * + * It does not represent the file itself. + * A Pathname can be relative or absolute. It's not until you try to + * reference the file that it even matters whether the file exists or not. + * + * Pathname is immutable. It has no method for destructive update. + * + * The value of this class is to manipulate file path information in a neater + * way than standard Ruby provides. The examples below demonstrate the + * difference. *All* functionality from File, FileTest, and some from Dir and + * FileUtils is included, in an unsurprising way. It is essentially a facade for + * all of these, and more. + * + * == Examples + * + * === Example 1: Using Pathname + * + * require 'pathname' + * pn = Pathname.new("/usr/bin/ruby") + * size = pn.size # 27662 + * isdir = pn.directory? # false + * dir = pn.dirname # Pathname:/usr/bin + * base = pn.basename # Pathname:ruby + * dir, base = pn.split # [Pathname:/usr/bin, Pathname:ruby] + * data = pn.read + * pn.open { |f| _ } + * pn.each_line { |line| _ } + * + * === Example 2: Using standard Ruby + * + * pn = "/usr/bin/ruby" + * size = File.size(pn) # 27662 + * isdir = File.directory?(pn) # false + * dir = File.dirname(pn) # "/usr/bin" + * base = File.basename(pn) # "ruby" + * dir, base = File.split(pn) # ["/usr/bin", "ruby"] + * data = File.read(pn) + * File.open(pn) { |f| _ } + * File.foreach(pn) { |line| _ } + * + * === Example 3: Special features + * + * p1 = Pathname.new("/usr/lib") # Pathname:/usr/lib + * p2 = p1 + "ruby/1.8" # Pathname:/usr/lib/ruby/1.8 + * p3 = p1.parent # Pathname:/usr + * p4 = p2.relative_path_from(p3) # Pathname:lib/ruby/1.8 + * pwd = Pathname.pwd # Pathname:/home/gavin + * pwd.absolute? # true + * p5 = Pathname.new "." # Pathname:. + * p5 = p5 + "music/../articles" # Pathname:music/../articles + * p5.cleanpath # Pathname:articles + * p5.realpath # Pathname:/home/gavin/articles + * p5.children # [Pathname:/home/gavin/articles/linux, ...] + * + * == Breakdown of functionality + * + * === Core methods + * + * These methods are effectively manipulating a String, because that's + * all a path is. Except for #mountpoint?, #children, #each_child, + * #realdirpath and #realpath, they don't access the filesystem. + * + * - + + * - #join + * - #parent + * - #root? + * - #absolute? + * - #relative? + * - #relative_path_from + * - #each_filename + * - #cleanpath + * - #realpath + * - #realdirpath + * - #children + * - #each_child + * - #mountpoint? + * + * === File status predicate methods + * + * These methods are a facade for FileTest: + * - #blockdev? + * - #chardev? + * - #directory? + * - #executable? + * - #executable_real? + * - #exist? + * - #file? + * - #grpowned? + * - #owned? + * - #pipe? + * - #readable? + * - #world_readable? + * - #readable_real? + * - #setgid? + * - #setuid? + * - #size + * - #size? + * - #socket? + * - #sticky? + * - #symlink? + * - #writable? + * - #world_writable? + * - #writable_real? + * - #zero? + * + * === File property and manipulation methods + * + * These methods are a facade for File: + * - #atime + * - #ctime + * - #mtime + * - #chmod(mode) + * - #lchmod(mode) + * - #chown(owner, group) + * - #lchown(owner, group) + * - #fnmatch(pattern, *args) + * - #fnmatch?(pattern, *args) + * - #ftype + * - #make_link(old) + * - #open(*args, &block) + * - #readlink + * - #rename(to) + * - #stat + * - #lstat + * - #make_symlink(old) + * - #truncate(length) + * - #utime(atime, mtime) + * - #basename(*args) + * - #dirname + * - #extname + * - #expand_path(*args) + * - #split + * + * === Directory methods + * + * These methods are a facade for Dir: + * - Pathname.glob(*args) + * - Pathname.getwd / Pathname.pwd + * - #rmdir + * - #entries + * - #each_entry(&block) + * - #mkdir(*args) + * - #opendir(*args) + * + * === IO + * + * These methods are a facade for IO: + * - #each_line(*args, &block) + * - #read(*args) + * - #binread(*args) + * - #readlines(*args) + * - #sysopen(*args) + * + * === Utilities + * + * These methods are a mixture of Find, FileUtils, and others: + * - #find(&block) + * - #mkpath + * - #rmtree + * - #unlink / #delete + * + * + * == Method documentation + * + * As the above section shows, most of the methods in Pathname are facades. The + * documentation for these methods generally just says, for instance, "See + * FileTest.writable?", as you should be familiar with the original method + * anyway, and its documentation (e.g. through +ri+) will contain more + * information. In some cases, a brief description will follow. + */ void Init_pathname() { -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/