Adds #entries feature to the public API

mend

Author: nolantait

docsite/source/file-system-utilities.html.md

@@ -69,4 +69,7 @@ files.directory?(path)
 
 # check if path is an executable (files and directories)
 files.executable?(path)
+
+# read entries from a directory
+files.entries(path)
 ```

docsite/source/index.html.md

@@ -99,6 +99,9 @@ file.directory?(path)
 
 # check if path is an executable (files and directories)
 file.executable?(path)
+
+# read entries from a directory
+files.entries(path)
 ```
 
 ### Adapters

lib/dry/files.rb

@@ -836,6 +836,18 @@ def remove_block(path, target)
       remove_block(path, target) if match?(content, target)
     end
 
+    # Reads entries from a directory
+    #
+    # @param path [String,Pathname] the path to file
+    #
+    # @raise [Dry::Files::IOError] in case of I/O error
+    #
+    # @since 1.0.1
+    # @api public
+    def entries(path)
+      adapter.entries(path)
+    end
+
     private
 
     # @since 0.3.0

lib/dry/files/file_system.rb

@@ -17,6 +17,10 @@ class FileSystem
       # @api private
       attr_reader :file_utils
 
+      # @since 1.0.1
+      # @api private
+      attr_reader :dir
+
       # Creates a new instance
       #
       # @param file [Class]
@@ -25,9 +29,10 @@ class FileSystem
       # @return [Dry::Files::FileSystem]
       #
       # @since 0.1.0
-      def initialize(file: File, file_utils: FileUtils)
+      def initialize(file: File, file_utils: FileUtils, dir: Dir)
         @file = file
         @file_utils = file_utils
+        @dir = dir
       end
 
       # Opens (or creates) a new file for both read/write operations.
@@ -343,6 +348,22 @@ def executable?(path)
         file.executable?(path)
       end
 
+      # Get entries from a directory
+      #
+      # @see https://ruby-doc.org/3.2.2/Dir.html#method-c-entries
+      #
+      # @param [String,Pathname] the path to list entries for
+      #
+      # @raise [Dry::Files::IOError] in case of I/O error
+      #
+      # @since 1.0.1
+      # @api private
+      def entries(path)
+        with_error_handling do
+          dir.entries(path)
+        end
+      end
+
       private
 
       # Catch `SystemCallError` and re-raise a `Dry::Files::IOError`.

lib/dry/files/memory_file_system.rb

@@ -386,6 +386,24 @@ def executable?(path)
         node.executable?
       end
 
+      # Reads entries from a directory
+      #
+      # @param path [String,Pathname] the path to file
+      # @return [Array<String>] the entries
+      #
+      # @raise [Dry::Files::IOError] in case of I/O error
+      #
+      # @since 1.0.1
+      # @api private
+      def entries(path)
+        path = Path[path]
+        node = find(path)
+        raise IOError, Errno::ENOENT.new(path.to_s) if node.nil?
+        raise IOError, Errno::ENOTDIR.new(path.to_s) unless node.directory?
+
+        [".", ".."] + node.children.keys
+      end
+
       private
 
       # @since 0.1.0

lib/dry/files/memory_file_system/node.rb

@@ -97,6 +97,10 @@ def self.root
         # @api private
         attr_reader :segment, :mode
 
+        # @since 1.0.1
+        # @api private
+        attr_reader :children
+
         # Instantiate a new node.
         # It's a directory node by default.
         #

spec/integration/dry/files_spec.rb

@@ -1880,4 +1880,18 @@ class Result
       expect(subject.executable?(path)).to be(true)
     end
   end
+
+  describe "#entries" do
+    it "returns a list of entries for a directory" do
+      subject.touch(root.join("file-1.txt"))
+      subject.touch(root.join("file-2.txt"))
+
+      expect(subject.entries(root)).to eq [
+        ".",
+        "..",
+        "file-2.txt",
+        "file-1.txt"
+      ]
+    end
+  end
 end

spec/unit/dry/files/file_system_spec.rb

@@ -600,4 +600,23 @@
       expect(subject.executable?(path)).to be(true)
     end
   end
+
+  describe "#entries" do
+    it "returns entries for directory" do
+      subject.touch(root.join("file-1.txt"))
+      subject.touch(root.join("file-2.txt"))
+
+      expect(subject.entries(root)).to eq [".", "..", "file-2.txt", "file-1.txt"]
+    end
+
+    it "raises error if directory doesn't exist" do
+      path = root.join("non-existent")
+
+      expect { subject.entries(path) }.to raise_error do |exception|
+        expect(exception).to be_kind_of(Dry::Files::IOError)
+        expect(exception.cause).to be_kind_of(Errno::ENOENT)
+        expect(exception.message).to include(path.to_s)
+      end
+    end
+  end
 end

spec/unit/dry/files/memory_file_system_spec.rb

@@ -626,4 +626,39 @@ def call(*)
       expect(subject.executable?(path)).to be(true)
     end
   end
+
+  describe "#entries" do
+    it "raises an error when the path does not exist" do
+      path = subject.join("file-1.txt")
+
+      expect { subject.entries(path) }.to raise_error do |exception|
+        expect(exception).to be_kind_of(Dry::Files::IOError)
+        expect(exception.cause).to be_kind_of(Errno::ENOENT)
+        expect(exception.message).to include(path.to_s)
+      end
+    end
+
+    it "raises an error when the path is a file" do
+      path = subject.join("file-1.txt")
+      subject.touch(path)
+
+      expect { subject.entries(path) }.to raise_error do |exception|
+        expect(exception).to be_kind_of(Dry::Files::IOError)
+        expect(exception.cause).to be_kind_of(Errno::ENOTDIR)
+        expect(exception.message).to include(path.to_s)
+      end
+    end
+
+    it "returns entries when the path is a directory" do
+      subject.touch(subject.join("file-1.txt"))
+      subject.touch(subject.join("file-2.txt"))
+
+      expect(subject.entries(subject.join)).to eq [
+        ".",
+        "..",
+        "file-1.txt",
+        "file-2.txt"
+      ]
+    end
+  end
 end