diff options
Diffstat (limited to 'dir.rb')
| -rw-r--r-- | dir.rb | 306 |
1 files changed, 24 insertions, 282 deletions
@@ -31,7 +31,7 @@ # A \Dir object is in some ways array-like: # # - It has instance methods #children, #each, and #each_child. -# - It includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here]. +# - It includes {module Enumerable}[rdoc-ref:Enumerable@Whats+Here]. # # == \Dir As Stream-Like # @@ -46,14 +46,14 @@ # The stream has a _position_, which is the index of an entry in the directory: # # - The initial position is zero (before the first entry). -# - \Method #tell (aliased as #pos) returns the position. -# - \Method #pos= sets the position (but ignores a value outside the stream), +# - Method #tell (aliased as #pos) returns the position. +# - Method #pos= sets the position (but ignores a value outside the stream), # and returns the position. -# - \Method #seek is like #pos=, but returns +self+ (convenient for chaining). -# - \Method #read, if not at end-of-stream, reads the next entry and increments +# - Method #seek is like #pos=, but returns +self+ (convenient for chaining). +# - Method #read, if not at end-of-stream, reads the next entry and increments # the position; # if at end-of-stream, does not increment the position. -# - \Method #rewind sets the position to zero. +# - Method #rewind sets the position to zero. # # Examples (using the {simple file tree}[rdoc-ref:Dir@About+the+Examples]): # @@ -83,10 +83,10 @@ # # == What's Here # -# First, what's elsewhere. \Class \Dir: +# First, what's elsewhere. Class \Dir: # -# - Inherits from {class Object}[rdoc-ref:Object@What-27s+Here]. -# - Includes {module Enumerable}[rdoc-ref:Enumerable@What-27s+Here], +# - Inherits from {class Object}[rdoc-ref:Object@Whats+Here]. +# - Includes {module Enumerable}[rdoc-ref:Enumerable@Whats+Here], # which provides dozens of additional methods. # # Here, class \Dir provides methods that are useful for: @@ -178,7 +178,7 @@ class Dir # if +nil+ (the default), the file system's encoding is used: # # Dir.open('.').read.encoding # => #<Encoding:UTF-8> - # Dir.open('.', encoding: 'US-ASCII').read.encoding # => #<Encoding:US-ASCII> + # Dir.open('.', encoding: Encoding::US_ASCII).read.encoding # => #<Encoding:US-ASCII> # def self.open(name, encoding: nil, &block) dir = Primitive.dir_s_open(name, encoding) @@ -206,299 +206,41 @@ class Dir # if +nil+ (the default), the file system's encoding is used: # # Dir.new('.').read.encoding # => #<Encoding:UTF-8> - # Dir.new('.', encoding: 'US-ASCII').read.encoding # => #<Encoding:US-ASCII> + # Dir.new('.', encoding: Encoding::US_ASCI).read.encoding # => #<Encoding:US-ASCII> # def initialize(name, encoding: nil) Primitive.dir_initialize(name, encoding) end # call-seq: - # Dir[*patterns, base: nil, sort: true] -> array - # - # Calls Dir.glob with argument +patterns+ - # and the values of keyword arguments +base+ and +sort+; - # returns the array of selected entry names. + # Dir[patterns, base: nil, sort: true] -> array # + # Like Dir.glob, but does not accept keyword argument +flags+. def self.[](*args, base: nil, sort: true) Primitive.dir_s_aref(args, base, sort) end # call-seq: - # Dir.glob(*patterns, flags: 0, base: nil, sort: true) -> array - # Dir.glob(*patterns, flags: 0, base: nil, sort: true) {|entry_name| ... } -> nil - # - # Forms an array _entry_names_ of the entry names selected by the arguments. - # - # Argument +patterns+ is a string pattern or an array of string patterns; - # note that these are not regexps; see below. - # - # Notes for the following examples: - # - # - <tt>'*'</tt> is the pattern that matches any entry name - # except those that begin with <tt>'.'</tt>. - # - We use method Array#take to shorten returned arrays - # that otherwise would be very large. - # - # With no block, returns array _entry_names_; - # example (using the {simple file tree}[rdoc-ref:Dir@About+the+Examples]): - # - # Dir.glob('*') # => ["config.h", "lib", "main.rb"] - # - # With a block, calls the block with each of the _entry_names_ - # and returns +nil+: - # - # Dir.glob('*') {|entry_name| puts entry_name } # => nil - # - # Output: - # - # config.h - # lib - # main.rb - # - # If optional keyword argument +flags+ is given, - # the value modifies the matching; see below. - # - # If optional keyword argument +base+ is given, - # its value specifies the base directory. - # Each pattern string specifies entries relative to the base directory; - # the default is <tt>'.'</tt>. - # The base directory is not prepended to the entry names in the result: - # - # Dir.glob(pattern, base: 'lib').take(5) - # # => ["abbrev.gemspec", "abbrev.rb", "base64.gemspec", "base64.rb", "benchmark.gemspec"] - # Dir.glob(pattern, base: 'lib/irb').take(5) - # # => ["cmd", "color.rb", "color_printer.rb", "completion.rb", "context.rb"] - # - # If optional keyword +sort+ is given, its value specifies whether - # the array is to be sorted; the default is +true+. - # Passing value +false+ with that keyword disables sorting - # (though the underlying file system may already have sorted the array). - # - # <b>Patterns</b> - # - # Each pattern string is expanded - # according to certain metacharacters; - # examples below use the {Ruby file tree}[rdoc-ref:Dir@About+the+Examples]: - # - # - <tt>'*'</tt>: Matches any substring in an entry name, - # similar in meaning to regexp <tt>/.*/mx</tt>; - # may be restricted by other values in the pattern strings: - # - # - <tt>'*'</tt> matches all entry names: - # - # Dir.glob('*').take(3) # => ["BSDL", "CONTRIBUTING.md", "COPYING"] - # - # - <tt>'c*'</tt> matches entry names beginning with <tt>'c'</tt>: - # - # Dir.glob('c*').take(3) # => ["CONTRIBUTING.md", "COPYING", "COPYING.ja"] - # - # - <tt>'*c'</tt> matches entry names ending with <tt>'c'</tt>: - # - # Dir.glob('*c').take(3) # => ["addr2line.c", "array.c", "ast.c"] - # - # - <tt>'\*c\*'</tt> matches entry names that contain <tt>'c'</tt>, - # even at the beginning or end: - # - # Dir.glob('*c*').take(3) # => ["CONTRIBUTING.md", "COPYING", "COPYING.ja"] - # - # Does not match Unix-like hidden entry names ("dot files"). - # To include those in the matched entry names, - # use flag IO::FNM_DOTMATCH or something like <tt>'{*,.*}'</tt>. - # - # - <tt>'**'</tt>: Matches entry names recursively - # if followed by the slash character <tt>'/'</tt>: - # - # Dir.glob('**/').take(3) # => ["basictest/", "benchmark/", "benchmark/gc/"] - # - # If the string pattern contains other characters - # or is not followed by a slash character, - # it is equivalent to <tt>'*'</tt>. - # - # - <tt>'?'</tt> Matches any single character; - # similar in meaning to regexp <tt>/./</tt>: - # - # Dir.glob('io.?') # => ["io.c"] - # - # - <tt>'[_set_]'</tt>: Matches any one character in the string _set_; - # behaves like a {Regexp character class}[rdoc-ref:Regexp@Character+Classes], - # including set negation (<tt>'[^a-z]'</tt>): - # - # Dir.glob('*.[a-z][a-z]').take(3) - # # => ["CONTRIBUTING.md", "COPYING.ja", "KNOWNBUGS.rb"] - # - # - <tt>'{_abc_,_xyz_}'</tt>: - # Matches either string _abc_ or string _xyz_; - # behaves like {Regexp alternation}[rdoc-ref:Regexp@Alternation]: - # - # Dir.glob('{LEGAL,BSDL}') # => ["LEGAL", "BSDL"] - # - # More than two alternatives may be given. - # - # - <tt>\\</tt>: Escapes the following metacharacter. - # - # Note that on Windows, the backslash character may not be used - # in a string pattern: - # <tt>Dir['c:\\foo*']</tt> will not work, use <tt>Dir['c:/foo*']</tt> instead. - # - # More examples (using the {simple file tree}[rdoc-ref:Dir@About+the+Examples]): - # - # # We're in the example directory. - # File.basename(Dir.pwd) # => "example" - # Dir.glob('config.?') # => ["config.h"] - # Dir.glob('*.[a-z][a-z]') # => ["main.rb"] - # Dir.glob('*.[^r]*') # => ["config.h"] - # Dir.glob('*.{rb,h}') # => ["main.rb", "config.h"] - # Dir.glob('*') # => ["config.h", "lib", "main.rb"] - # Dir.glob('*', File::FNM_DOTMATCH) # => [".", "config.h", "lib", "main.rb"] - # Dir.glob(["*.rb", "*.h"]) # => ["main.rb", "config.h"] - # - # Dir.glob('**/*.rb') - # => ["lib/song/karaoke.rb", "lib/song.rb", "main.rb"] - # - # Dir.glob('**/*.rb', base: 'lib') # => ["song/karaoke.rb", "song.rb"] - # - # Dir.glob('**/lib') # => ["lib"] - # - # Dir.glob('**/lib/**/*.rb') # => ["lib/song/karaoke.rb", "lib/song.rb"] - # - # Dir.glob('**/lib/*.rb') # => ["lib/song.rb"] - # - # <b>Flags</b> - # - # If optional keyword argument +flags+ is given (the default is zero -- no flags), - # its value should be the bitwise OR of one or more of the constants - # defined in module File::Constants. - # - # Example: - # - # flags = File::FNM_EXTGLOB | File::FNM_DOTMATCH - # - # Specifying flags can extend, restrict, or otherwise modify the matching. - # - # The flags for this method (other constants in File::Constants do not apply): - # - # - File::FNM_DOTMATCH: - # specifies that entry names beginning with <tt>'.'</tt> - # should be considered for matching: - # - # Dir.glob('*').take(5) - # # => ["BSDL", "CONTRIBUTING.md", "COPYING", "COPYING.ja", "GPL"] - # Dir.glob('*', flags: File::FNM_DOTMATCH).take(5) - # # => [".", ".appveyor.yml", ".cirrus.yml", ".dir-locals.el", ".document"] - # - # - File::FNM_EXTGLOB: - # enables the pattern extension - # <tt>'{_a_,_b_}'</tt>, which matches pattern _a_ and pattern _b_; - # behaves like a - # {regexp union}[rdoc-ref:Regexp.union] - # (e.g., <tt>'(?:_a_|_b_)'</tt>): - # - # pattern = '{LEGAL,BSDL}' - # Dir.glob(pattern) # => ["LEGAL", "BSDL"] - # - # - File::FNM_NOESCAPE: - # specifies that escaping with the backslash character <tt>'\'</tt> - # is disabled; the character is not an escape character. - # - # - File::FNM_PATHNAME: - # specifies that metacharacters <tt>'*'</tt> and <tt>'?'</tt> - # do not match directory separators. - # - # - File::FNM_SHORTNAME: - # specifies that patterns may match short names if they exist; Windows only. + # Dir.glob(patterns, flags: 0, base: '.', sort: true) -> array_of_entries # + # Returns an array of filesystem entries; + # see {Filename Globbing}[rdoc-ref:file/filename_globbing.md]. def self.glob(pattern, _flags = 0, flags: _flags, base: nil, sort: true) + Primitive.attr! :use_block Primitive.dir_s_glob(pattern, flags, base, sort) end end class << File - # call-seq: - # File.fnmatch( pattern, path, [flags] ) -> (true or false) - # File.fnmatch?( pattern, path, [flags] ) -> (true or false) - # - # Returns true if +path+ matches against +pattern+. The pattern is not a - # regular expression; instead it follows rules similar to shell filename - # globbing. It may contain the following metacharacters: - # - # <code>*</code>:: - # Matches any file. Can be restricted by other values in the glob. - # Equivalent to <code>/.*/x</code> in regexp. - # - # <code>*</code>:: Matches all regular files - # <code>c*</code>:: Matches all files beginning with <code>c</code> - # <code>*c</code>:: Matches all files ending with <code>c</code> - # <code>\*c*</code>:: Matches all files that have <code>c</code> in them - # (including at the beginning or end). - # - # To match hidden files (that start with a <code>.</code>) set the - # File::FNM_DOTMATCH flag. - # - # <code>**</code>:: - # Matches directories recursively or files expansively. - # - # <code>?</code>:: - # Matches any one character. Equivalent to <code>/.{1}/</code> in regexp. - # - # <code>[set]</code>:: - # Matches any one character in +set+. Behaves exactly like character sets - # in Regexp, including set negation (<code>[^a-z]</code>). - # - # <code>\\</code>:: - # Escapes the next metacharacter. - # - # <code>{a,b}</code>:: - # Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled. - # Behaves like a Regexp union (<code>(?:a|b)</code>). - # - # +flags+ is a bitwise OR of the <code>FNM_XXX</code> constants. The same - # glob pattern and flags are used by Dir::glob. - # - # Examples: - # - # File.fnmatch('cat', 'cat') #=> true # match entire string - # File.fnmatch('cat', 'category') #=> false # only match partial string - # - # File.fnmatch('c{at,ub}s', 'cats') #=> false # { } isn't supported by default - # File.fnmatch('c{at,ub}s', 'cats', File::FNM_EXTGLOB) #=> true # { } is supported on FNM_EXTGLOB - # - # File.fnmatch('c?t', 'cat') #=> true # '?' match only 1 character - # File.fnmatch('c??t', 'cat') #=> false # ditto - # File.fnmatch('c*', 'cats') #=> true # '*' match 0 or more characters - # File.fnmatch('c*t', 'c/a/b/t') #=> true # ditto - # File.fnmatch('ca[a-z]', 'cat') #=> true # inclusive bracket expression - # File.fnmatch('ca[^t]', 'cat') #=> false # exclusive bracket expression ('^' or '!') - # - # File.fnmatch('cat', 'CAT') #=> false # case sensitive - # File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true # case insensitive - # File.fnmatch('cat', 'CAT', File::FNM_SYSCASE) #=> true or false # depends on the system default - # - # File.fnmatch('?', '/', File::FNM_PATHNAME) #=> false # wildcard doesn't match '/' on FNM_PATHNAME - # File.fnmatch('*', '/', File::FNM_PATHNAME) #=> false # ditto - # File.fnmatch('[/]', '/', File::FNM_PATHNAME) #=> false # ditto - # - # File.fnmatch('\?', '?') #=> true # escaped wildcard becomes ordinary - # File.fnmatch('\a', 'a') #=> true # escaped ordinary remains ordinary - # File.fnmatch('\a', '\a', File::FNM_NOESCAPE) #=> true # FNM_NOESCAPE makes '\' ordinary - # File.fnmatch('[\?]', '?') #=> true # can escape inside bracket expression - # - # File.fnmatch('*', '.profile') #=> false # wildcard doesn't match leading - # File.fnmatch('*', '.profile', File::FNM_DOTMATCH) #=> true # period by default. - # File.fnmatch('.*', '.profile') #=> true + + # :markup: markdown # - # File.fnmatch('**/*.rb', 'main.rb') #=> false - # File.fnmatch('**/*.rb', './main.rb') #=> false - # File.fnmatch('**/*.rb', 'lib/song.rb') #=> true - # File.fnmatch('**.rb', 'main.rb') #=> true - # File.fnmatch('**.rb', './main.rb') #=> false - # File.fnmatch('**.rb', 'lib/song.rb') #=> true - # File.fnmatch('*', 'dave/.profile') #=> true + # call-seq: + # File.fnmatch(pattern, path, flags = 0) -> true or false # - # File.fnmatch('**/foo', 'a/b/c/foo', File::FNM_PATHNAME) #=> true - # File.fnmatch('**/foo', '/a/b/c/foo', File::FNM_PATHNAME) #=> true - # File.fnmatch('**/foo', 'c:/a/b/c/foo', File::FNM_PATHNAME) #=> true - # File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME) #=> false - # File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true + # Returns whether string `pattern` matches against string `path`, + # under the control of the given `flags`; + # see [Filename Matching](rdoc-ref:file/filename_matching.md). def fnmatch(pattern, path, flags = 0) end alias fnmatch? fnmatch |