Preview Ruby 4.1 is a preview. It can change before the final release. Switch to Ruby 4.0 →

class method

Dir.scan

Dir.scan(dirpath) → entries

Dir.scan(dirpath, encoding: 'UTF-8') → entries

Dir.scan(dirpath) {|entry_name, entry_type| ... } → nil

Dir.scan(dirpath, encoding: 'UTF-8') {|entry_name, entry_type| ... } → nil

static VALUE
dir_s_scan(int argc, VALUE *argv, VALUE klass)
{
    VALUE dir = dir_open_dir(argc, argv);
    return rb_ensure(dir_scan_children, dir, dir_close, dir);
}

Scans the entries in the directory at dirpath, except for '.' and '..'.

With no block given, returns entries, an array of 2-element arrays. Each nested array contains an entry name and its type:

Example

Dir.scan('/example') # => [["config.h", :file], ["lib", :directory], ["main.rb", :file]]

With a block given, calls the block with each entry name and its type; returns nil:

Example

entries = []
Dir.scan('/example') do |entry_name, entry_type|
  entries << [entry_name, entry_type]
end # => nil
entries # => [["config.h", :file], ["lib", :directory], ["main.rb", :file]]

The type symbol is one of :file, :directory, :characterSpecial, :blockSpecial, :fifo, :link, :socket, or :unknown.

The given encoding is used as the external encoding for each entry name:

Example

Dir.scan('/example').first.first.encoding
# => #<Encoding:UTF-8>
Dir.scan('/example', encoding: 'US-ASCII').first.first.encoding
# => #<Encoding:US-ASCII>

See String Encoding.

Raises an exception if the directory does not exist.