dir.rb

   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.
   4 #
   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
   8 # (<code>.</code>).
   9 #
  10 # == What's Here
  11 #
  12 # First, what's elsewhere. \Class \Dir:
  13 #
  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.
  17 #
  18 # Here, class \Dir provides methods that are useful for:
  19 #
  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]
  25 #
  26 # === Reading
  27 #
  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.
  34 #
  35 # === Setting
  36 #
  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.
  41 #
  42 # === Querying
  43 #
  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+.
  63 #
  64 # === Iterating
  65 #
  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>.
  74 #
  75 # === Other
  76 #
  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+.
  83 class Dir
  84   # call-seq:
  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
  89   #
  90   # The optional <i>encoding</i> keyword argument specifies the encoding of the directory.
  91   # If not specified, the filesystem encoding is used.
  92   #
  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)
  99     if block
 100       begin
 101         yield dir
 102       ensure
 103         Primitive.dir_s_close(dir)
 104       end
 105     else
 106       dir
 107     end
 108   end
 109
 110   # call-seq:
 111   #    Dir.new( string ) -> aDir
 112   #    Dir.new( string, encoding: enc ) -> aDir
 113   #
 114   # Returns a new directory object for the named directory.
 115   #
 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)
 120   end
 121
 122   # call-seq:
 123   #    Dir[ string [, string ...] [, base: path] [, sort: true] ] -> array
 124   #
 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)
 129   end
 130
 131   # call-seq:
 132   #    Dir.glob( pattern, [flags], [base: path] [, sort: true] )                       -> array
 133   #    Dir.glob( pattern, [flags], [base: path] [, sort: true] ) { |filename| block }  -> nil
 134   #
 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.
 139   #
 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
 144   # paths.
 145   #
 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
 149   # are preserved.
 150   #
 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).
 154   #
 155   # <code>*</code>::
 156   #   Matches any file. Can be restricted by other values in the glob.
 157   #   Equivalent to <code>/.*/mx</code> in regexp.
 158   #
 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).
 164   #
 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>.
 168   #
 169   # <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>.
 173   #
 174   # <code>?</code>::
 175   #   Matches any one character. Equivalent to <code>/.{1}/</code> in regexp.
 176   #
 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>).
 180   #
 181   # <code>{p,q}</code>::
 182   #   Matches either literal <code>p</code> or literal <code>q</code>.
 183   #   Equivalent to pattern alternation in regexp.
 184   #
 185   #   Matching literals may be more than one character in length.  More than
 186   #   two literals may be specified.
 187   #
 188   # <code>\\</code>::
 189   #   Escapes the next metacharacter.
 190   #
 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.
 194   #
 195   # Examples:
 196   #
 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"]
 205   #
 206   #    Dir.glob("**/*.rb")                 #=> ["main.rb",
 207   #                                        #    "lib/song.rb",
 208   #                                        #    "lib/song/karaoke.rb"]
 209   #
 210   #    Dir.glob("**/*.rb", base: "lib")    #=> ["song.rb",
 211   #                                        #    "song/karaoke.rb"]
 212   #
 213   #    Dir.glob("**/lib")                  #=> ["lib"]
 214   #
 215   #    Dir.glob("**/lib/**/*.rb")          #=> ["lib/song.rb",
 216   #                                        #    "lib/song/karaoke.rb"]
 217   #
 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)
 221   end
 222 end
 223
 224 class << File
 225   # call-seq:
 226   #    File.fnmatch( pattern, path, [flags] ) -> (true or false)
 227   #    File.fnmatch?( pattern, path, [flags] ) -> (true or false)
 228   #
 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:
 232   #
 233   # <code>*</code>::
 234   #   Matches any file. Can be restricted by other values in the glob.
 235   #   Equivalent to <code>/.*/x</code> in regexp.
 236   #
 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).
 242   #
 243   #   To match hidden files (that start with a <code>.</code>) set the
 244   #   File::FNM_DOTMATCH flag.
 245   #
 246   # <code>**</code>::
 247   #   Matches directories recursively or files expansively.
 248   #
 249   # <code>?</code>::
 250   #   Matches any one character. Equivalent to <code>/.{1}/</code> in regexp.
 251   #
 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>).
 255   #
 256   # <code>\\</code>::
 257   #   Escapes the next metacharacter.
 258   #
 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>).
 262   #
 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.
 265   #
 266   # Examples:
 267   #
 268   #    File.fnmatch('cat',       'cat')        #=> true  # match entire string
 269   #    File.fnmatch('cat',       'category')   #=> false # only match partial string
 270   #
 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
 273   #
 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 '!')
 280   #
 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
 284   #
 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
 288   #
 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
 293   #
 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
 297   #
 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
 305   #
 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)
 312   end
 313   alias fnmatch? fnmatch
 314 end if false