diff options
Diffstat (limited to 'dir.rb')
| -rw-r--r-- | dir.rb | 123 |
1 files changed, 93 insertions, 30 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,7 +206,7 @@ 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) @@ -224,13 +224,20 @@ class Dir end # call-seq: - # Dir.glob(*patterns, _flags = 0, flags: _flags, base: nil, sort: true) -> array - # Dir.glob(*patterns, _flags = 0, flags: _flags, base: nil, sort: true) {|entry_name| ... } -> nil + # 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 pattern string or an array of pattern strings; - # note that these are not regexps. + # 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]): @@ -248,10 +255,30 @@ class Dir # 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 project file tree}[https://github.com/ruby/ruby]: + # 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>; @@ -292,16 +319,16 @@ class Dir # # 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.rdoc@Character+Classes], + # - <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>: + # - <tt>'{abc,xyz}'</tt>: # Matches either string _abc_ or string _xyz_; - # behaves like {Regexp alternation}[rdoc-ref:regexp.rdoc@Alternation]: + # behaves like {Regexp alternation}[rdoc-ref:Regexp@Alternation]: # # Dir.glob('{LEGAL,BSDL}') # => ["LEGAL", "BSDL"] # @@ -313,15 +340,6 @@ class Dir # in a string pattern: # <tt>Dir['c:\\foo*']</tt> will not work, use <tt>Dir['c:/foo*']</tt> instead. # - # If optional keyword argument +base+ is given, - # each pattern string specifies entries relative to the specified directory; - # the default is <tt>'.'</tt>. - # The base directory is not prepended to the entry names in the result. - # - # If optional keyword +sort+ is given, its value specifies whether - # the array is to be sorted; - # the default is +true+. - # # More examples (using the {simple file tree}[rdoc-ref:Dir@About+the+Examples]): # # # We're in the example directory. @@ -345,7 +363,52 @@ class Dir # # 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. + # 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 |