1 # Objects of class Dir are directory streams representing
2 # directories in the underlying file system. They provide a variety
3 # of ways to list directories and their contents. See also File.
5 # The directory used in these examples contains the two regular files
6 # (<code>config.h</code> and <code>main.rb</code>), the parent
7 # directory (<code>..</code>), and the directory itself
12 # First, what's elsewhere. \Class \Dir:
14 # - Inherits from {class Object}[Object.html#class-Object-label-What-27s+Here].
15 # - Includes {module Enumerable}[Enumerable.html#module-Enumerable-label-What-27s+Here],
16 # which provides dozens of additional methods.
18 # Here, class \Dir provides methods that are useful for:
20 # - {Reading}[#class-Dir-label-Reading]
21 # - {Setting}[#class-Dir-label-Setting]
22 # - {Querying}[#class-Dir-label-Querying]
23 # - {Iterating}[#class-Dir-label-Iterating]
24 # - {Other}[#class-Dir-label-Other]
28 # - #close:: Closes the directory stream for +self+.
29 # - #pos=:: Sets the position in the directory stream for +self+.
30 # - #read:: Reads and returns the next entry in the directory stream for +self+.
31 # - #rewind:: Sets the position in the directory stream for +self+ to the first entry.
32 # - #seek:: Sets the position in the directory stream for +self+
33 # the entry at the given offset.
37 # - ::chdir:: Changes the working directory of the current process
38 # to the given directory.
39 # - ::chroot:: Changes the file-system root for the current process
40 # to the given directory.
44 # - ::[]:: Same as ::glob without the ability to pass flags.
45 # - ::children:: Returns an array of names of the children
46 # (both files and directories) of the given directory,
47 # but not including <tt>.</tt> or <tt>..</tt>.
48 # - ::empty?:: Returns whether the given path is an empty directory.
49 # - ::entries:: Returns an array of names of the children
50 # (both files and directories) of the given directory,
51 # including <tt>.</tt> and <tt>..</tt>.
52 # - ::exist?:: Returns whether the given path is a directory.
53 # - ::getwd (aliased as #pwd):: Returns the path to the current working directory.
54 # - ::glob:: Returns an array of file paths matching the given pattern and flags.
55 # - ::home:: Returns the home directory path for a given user or the current user.
56 # - #children:: Returns an array of names of the children
57 # (both files and directories) of +self+,
58 # but not including <tt>.</tt> or <tt>..</tt>.
59 # - #fileno:: Returns the integer file descriptor for +self+.
60 # - #path (aliased as #to_path):: Returns the path used to create +self+.
61 # - #tell (aliased as #pos):: Returns the integer position
62 # in the directory stream for +self+.
66 # - ::each_child:: Calls the given block with each entry in the given directory,
67 # but not including <tt>.</tt> or <tt>..</tt>.
68 # - ::foreach:: Calls the given block with each entryin the given directory,
69 # including <tt>.</tt> and <tt>..</tt>.
70 # - #each:: Calls the given block with each entry in +self+,
71 # including <tt>.</tt> and <tt>..</tt>.
72 # - #each_child:: Calls the given block with each entry in +self+,
73 # but not including <tt>.</tt> or <tt>..</tt>.
77 # - ::mkdir:: Creates a directory at the given path, with optional permissions.
78 # - ::new:: Returns a new \Dir for the given path, with optional encoding.
79 # - ::open:: Same as ::new, but if a block is given, yields the \Dir to the block,
80 # closing it upon block exit.
81 # - ::unlink (aliased as ::delete and ::rmdir):: Removes the given directory.
82 # - #inspect:: Returns a string description of +self+.
85 # Dir.open( string ) -> aDir
86 # Dir.open( string, encoding: enc ) -> aDir
87 # Dir.open( string ) {| aDir | block } -> anObject
88 # Dir.open( string, encoding: enc ) {| aDir | block } -> anObject
90 # The optional <i>encoding</i> keyword argument specifies the encoding of the directory.
91 # If not specified, the filesystem encoding is used.
93 # With no block, <code>open</code> is a synonym for Dir::new. If a
94 # block is present, it is passed <i>aDir</i> as a parameter. The
95 # directory is closed at the end of the block, and Dir::open returns
96 # the value of the block.
97 def self.open(name, encoding: nil, &block)
98 dir = Primitive.dir_s_open(name, encoding)
103 Primitive.dir_s_close(dir)
111 # Dir.new( string ) -> aDir
112 # Dir.new( string, encoding: enc ) -> aDir
114 # Returns a new directory object for the named directory.
116 # The optional <i>encoding</i> keyword argument specifies the encoding of the directory.
117 # If not specified, the filesystem encoding is used.
118 def initialize(name, encoding: nil)
119 Primitive.dir_initialize(name, encoding)
123 # Dir[ string [, string ...] [, base: path] [, sort: true] ] -> array
125 # Equivalent to calling
126 # <code>Dir.glob([</code><i>string,...</i><code>], 0)</code>.
127 def self.[](*args, base: nil, sort: true)
128 Primitive.dir_s_aref(args, base, sort)
132 # Dir.glob( pattern, [flags], [base: path] [, sort: true] ) -> array
133 # Dir.glob( pattern, [flags], [base: path] [, sort: true] ) { |filename| block } -> nil
135 # Expands +pattern+, which is a pattern string or an Array of pattern
136 # strings, and returns an array containing the matching filenames.
137 # If a block is given, calls the block once for each matching filename,
138 # passing the filename as a parameter to the block.
140 # The optional +base+ keyword argument specifies the base directory for
141 # interpreting relative pathnames instead of the current working directory.
142 # As the results are not prefixed with the base directory name in this
143 # case, you will need to prepend the base directory name if you want real
146 # The results which matched single wildcard or character set are sorted in
147 # binary ascending order, unless +false+ is given as the optional +sort+
148 # keyword argument. The order of an Array of pattern strings and braces
151 # Note that the pattern is not a regexp, it's closer to a shell glob.
152 # See File::fnmatch for the meaning of the +flags+ parameter.
153 # Case sensitivity depends on your system (+File::FNM_CASEFOLD+ is ignored).
156 # Matches any file. Can be restricted by other values in the glob.
157 # Equivalent to <code>/.*/mx</code> in regexp.
159 # <code>*</code>:: Matches all files
160 # <code>c*</code>:: Matches all files beginning with <code>c</code>
161 # <code>*c</code>:: Matches all files ending with <code>c</code>
162 # <code>\*c\*</code>:: Match all files that have <code>c</code> in them
163 # (including at the beginning or end).
165 # Note, this will not match Unix-like hidden files (dotfiles). In order
166 # to include those in the match results, you must use the
167 # File::FNM_DOTMATCH flag or something like <code>"{*,.*}"</code>.
170 # Matches directories recursively if followed by <code>/</code>. If
171 # this path segment contains any other characters, it is the same as the
172 # usual <code>*</code>.
175 # Matches any one character. Equivalent to <code>/.{1}/</code> in regexp.
177 # <code>[set]</code>::
178 # Matches any one character in +set+. Behaves exactly like character sets
179 # in Regexp, including set negation (<code>[^a-z]</code>).
181 # <code>{p,q}</code>::
182 # Matches either literal <code>p</code> or literal <code>q</code>.
183 # Equivalent to pattern alternation in regexp.
185 # Matching literals may be more than one character in length. More than
186 # two literals may be specified.
189 # Escapes the next metacharacter.
191 # Note that this means you cannot use backslash on windows as part of a
192 # glob, i.e. <code>Dir["c:\\foo*"]</code> will not work, use
193 # <code>Dir["c:/foo*"]</code> instead.
197 # Dir["config.?"] #=> ["config.h"]
198 # Dir.glob("config.?") #=> ["config.h"]
199 # Dir.glob("*.[a-z][a-z]") #=> ["main.rb"]
200 # Dir.glob("*.[^r]*") #=> ["config.h"]
201 # Dir.glob("*.{rb,h}") #=> ["main.rb", "config.h"]
202 # Dir.glob("*") #=> ["config.h", "main.rb"]
203 # Dir.glob("*", File::FNM_DOTMATCH) #=> [".", "..", "config.h", "main.rb"]
204 # Dir.glob(["*.rb", "*.h"]) #=> ["main.rb", "config.h"]
206 # Dir.glob("**/*.rb") #=> ["main.rb",
208 # # "lib/song/karaoke.rb"]
210 # Dir.glob("**/*.rb", base: "lib") #=> ["song.rb",
211 # # "song/karaoke.rb"]
213 # Dir.glob("**/lib") #=> ["lib"]
215 # Dir.glob("**/lib/**/*.rb") #=> ["lib/song.rb",
216 # # "lib/song/karaoke.rb"]
218 # Dir.glob("**/lib/*.rb") #=> ["lib/song.rb"]
219 def self.glob(pattern, _flags = 0, flags: _flags, base: nil, sort: true)
220 Primitive.dir_s_glob(pattern, flags, base, sort)
226 # File.fnmatch( pattern, path, [flags] ) -> (true or false)
227 # File.fnmatch?( pattern, path, [flags] ) -> (true or false)
229 # Returns true if +path+ matches against +pattern+. The pattern is not a
230 # regular expression; instead it follows rules similar to shell filename
231 # globbing. It may contain the following metacharacters:
234 # Matches any file. Can be restricted by other values in the glob.
235 # Equivalent to <code>/.*/x</code> in regexp.
237 # <code>*</code>:: Matches all regular files
238 # <code>c*</code>:: Matches all files beginning with <code>c</code>
239 # <code>*c</code>:: Matches all files ending with <code>c</code>
240 # <code>\*c*</code>:: Matches all files that have <code>c</code> in them
241 # (including at the beginning or end).
243 # To match hidden files (that start with a <code>.</code>) set the
244 # File::FNM_DOTMATCH flag.
247 # Matches directories recursively or files expansively.
250 # Matches any one character. Equivalent to <code>/.{1}/</code> in regexp.
252 # <code>[set]</code>::
253 # Matches any one character in +set+. Behaves exactly like character sets
254 # in Regexp, including set negation (<code>[^a-z]</code>).
257 # Escapes the next metacharacter.
259 # <code>{a,b}</code>::
260 # Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled.
261 # Behaves like a Regexp union (<code>(?:a|b)</code>).
263 # +flags+ is a bitwise OR of the <code>FNM_XXX</code> constants. The same
264 # glob pattern and flags are used by Dir::glob.
268 # File.fnmatch('cat', 'cat') #=> true # match entire string
269 # File.fnmatch('cat', 'category') #=> false # only match partial string
271 # File.fnmatch('c{at,ub}s', 'cats') #=> false # { } isn't supported by default
272 # File.fnmatch('c{at,ub}s', 'cats', File::FNM_EXTGLOB) #=> true # { } is supported on FNM_EXTGLOB
274 # File.fnmatch('c?t', 'cat') #=> true # '?' match only 1 character
275 # File.fnmatch('c??t', 'cat') #=> false # ditto
276 # File.fnmatch('c*', 'cats') #=> true # '*' match 0 or more characters
277 # File.fnmatch('c*t', 'c/a/b/t') #=> true # ditto
278 # File.fnmatch('ca[a-z]', 'cat') #=> true # inclusive bracket expression
279 # File.fnmatch('ca[^t]', 'cat') #=> false # exclusive bracket expression ('^' or '!')
281 # File.fnmatch('cat', 'CAT') #=> false # case sensitive
282 # File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true # case insensitive
283 # File.fnmatch('cat', 'CAT', File::FNM_SYSCASE) #=> true or false # depends on the system default
285 # File.fnmatch('?', '/', File::FNM_PATHNAME) #=> false # wildcard doesn't match '/' on FNM_PATHNAME
286 # File.fnmatch('*', '/', File::FNM_PATHNAME) #=> false # ditto
287 # File.fnmatch('[/]', '/', File::FNM_PATHNAME) #=> false # ditto
289 # File.fnmatch('\?', '?') #=> true # escaped wildcard becomes ordinary
290 # File.fnmatch('\a', 'a') #=> true # escaped ordinary remains ordinary
291 # File.fnmatch('\a', '\a', File::FNM_NOESCAPE) #=> true # FNM_NOESCAPE makes '\' ordinary
292 # File.fnmatch('[\?]', '?') #=> true # can escape inside bracket expression
294 # File.fnmatch('*', '.profile') #=> false # wildcard doesn't match leading
295 # File.fnmatch('*', '.profile', File::FNM_DOTMATCH) #=> true # period by default.
296 # File.fnmatch('.*', '.profile') #=> true
298 # File.fnmatch('**/*.rb', 'main.rb') #=> false
299 # File.fnmatch('**/*.rb', './main.rb') #=> false
300 # File.fnmatch('**/*.rb', 'lib/song.rb') #=> true
301 # File.fnmatch('**.rb', 'main.rb') #=> true
302 # File.fnmatch('**.rb', './main.rb') #=> false
303 # File.fnmatch('**.rb', 'lib/song.rb') #=> true
304 # File.fnmatch('*', 'dave/.profile') #=> true
306 # File.fnmatch('**/foo', 'a/b/c/foo', File::FNM_PATHNAME) #=> true
307 # File.fnmatch('**/foo', '/a/b/c/foo', File::FNM_PATHNAME) #=> true
308 # File.fnmatch('**/foo', 'c:/a/b/c/foo', File::FNM_PATHNAME) #=> true
309 # File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME) #=> false
310 # File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true
311 def fnmatch(pattern, path, flags = 0)
313 alias fnmatch? fnmatch