feat(bindings/ruby): add lister

bindings/ruby/lib/opendal.rb

@@ -19,3 +19,4 @@
 
 require_relative "opendal_ruby/opendal_ruby"
 require_relative "opendal_ruby/io"
+require_relative "opendal_ruby/entry"

bindings/ruby/lib/opendal_ruby/entry.rb

@@ -0,0 +1,29 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# frozen_string_literal: true
+
+module OpenDAL
+  class Entry
+    def to_h
+      {
+        path: path,
+        metadata: metadata
+      }
+    end
+  end
+end

bindings/ruby/src/lib.rs

@@ -26,6 +26,7 @@ pub use ::opendal as ocore;
 
 mod capability;
 mod io;
+mod lister;
 mod metadata;
 mod operator;
 
@@ -41,6 +42,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     let _ = metadata::include(&gem_module);
     let _ = capability::include(&gem_module);
     let _ = io::include(&gem_module);
+    let _ = lister::include(&ruby, &gem_module);
 
     Ok(())
 }

bindings/ruby/src/lister.rs

@@ -0,0 +1,93 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+use std::cell::RefCell;
+
+use magnus::class;
+use magnus::method;
+use magnus::prelude::*;
+use magnus::Error;
+use magnus::RModule;
+use magnus::Ruby;
+use magnus::Value;
+
+use crate::metadata::Metadata;
+use crate::*;
+
+/// Represents the result when list a directory
+#[magnus::wrap(class = "OpenDAL::Lister", free_immediately, size)]
+pub struct Lister(RefCell<ocore::BlockingLister>);
+
+/// Entry returned by Lister to represent a path and it's relative metadata.
+#[magnus::wrap(class = "OpenDAL::Entry", free_immediately, size)]
+pub struct Entry(ocore::Entry);
+
+impl Entry {
+    /// Gets the path of entry. Path is relative to operator's root.
+    ///
+    /// Only valid in current operator.
+    ///
+    /// If this entry is a dir, `path` MUST end with `/`
+    /// Otherwise, `path` MUST NOT end with `/`.
+    fn path(&self) -> Result<&str, Error> {
+        Ok(self.0.path())
+    }
+
+    /// Gets the name of entry. Name is the last segment of path.
+    ///
+    /// If this entry is a dir, `name` MUST end with `/`
+    /// Otherwise, `name` MUST NOT end with `/`.
+    fn name(&self) -> Result<&str, Error> {
+        Ok(self.0.name())
+    }
+
+    /// Fetches the metadata of this entry.
+    fn metadata(&self) -> Result<Metadata, Error> {
+        Ok(Metadata::new(self.0.metadata().clone()))
+    }
+}
+
+impl Lister {
+    /// Creates a new blocking Lister.
+    pub fn new(inner: ocore::BlockingLister) -> Self {
+        Self(RefCell::new(inner))
+    }
+
+    /// Returns the next element.
+    fn each(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        while let Some(Ok(entry)) = rb_self.0.borrow_mut().next() {
+            // we don't need the return value of the yield block
+            let _ = ruby.yield_value::<lister::Entry, Value>(Entry(entry));
+        }
+        Ok(())
+    }
+}
+
+pub fn include(ruby: &Ruby, gem_module: &RModule) -> Result<(), Error> {
+    let entry_class = gem_module.define_class("Entry", class::object())?;
+    entry_class.define_method("path", method!(Entry::path, 0))?;
+    entry_class.define_method("name", method!(Entry::name, 0))?;
+    entry_class.define_method("metadata", method!(Entry::metadata, 0))?;
+
+    let lister_class = gem_module.define_class("Lister", class::object())?;
+    let _ = lister_class
+        .include_module(ruby.module_enumerable())
+        .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+    lister_class.define_method("each", method!(Lister::each, 0))?;
+
+    Ok(())
+}

bindings/ruby/src/operator.rs

@@ -28,6 +28,7 @@ use magnus::Ruby;
 
 use crate::capability::Capability;
 use crate::io::Io;
+use crate::lister::Lister;
 use crate::metadata::Metadata;
 use crate::*;
 
@@ -141,6 +142,30 @@ impl Operator {
         let operator = rb_self.0.clone();
         Ok(Io::new(&ruby, operator, path, mode)?)
     }
+
+    /// Lists the directory.
+    pub fn list(ruby: &Ruby, rb_self: &Self, path: String) -> Result<Lister, Error> {
+        let lister = rb_self
+            .0
+            .clone()
+            .lister(&path)
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+
+        Ok(Lister::new(lister))
+    }
+
+    /// Lists the directory recursively.
+    pub fn scan(ruby: &Ruby, rb_self: &Self, path: String) -> Result<Lister, Error> {
+        let lister = rb_self
+            .0
+            .clone()
+            .lister_with(&path)
+            .recursive(true)
+            .call()
+            .map_err(|err| Error::new(ruby.exception_runtime_error(), err.to_string()))?;
+
+        Ok(Lister::new(lister))
+    }
 }
 
 pub fn include(gem_module: &RModule) -> Result<(), Error> {
@@ -157,6 +182,8 @@ pub fn include(gem_module: &RModule) -> Result<(), Error> {
     class.define_method("remove_all", method!(Operator::remove_all, 1))?;
     class.define_method("copy", method!(Operator::copy, 2))?;
     class.define_method("open", method!(Operator::open, 2))?;
+    class.define_method("list", method!(Operator::list, 1))?;
+    class.define_method("scan", method!(Operator::scan, 1))?;
 
     Ok(())
 }

bindings/ruby/test/lister_test.rb

@@ -0,0 +1,68 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+# frozen_string_literal: true
+
+require "test_helper"
+require "tmpdir"
+
+class ListerTest < ActiveSupport::TestCase
+  setup do
+    @root = Dir.mktmpdir
+    File.write("#{@root}/sample", "Sample data for testing")
+    Dir.mkdir("#{@root}/sub")
+    File.write("#{@root}/sub/sample", "Sample data for testing")
+    @op = OpenDAL::Operator.new("fs", {"root" => @root})
+  end
+
+  test "lists the directory" do
+    lister = @op.list("")
+
+    lists = lister.map(&:to_h).map { |e| e[:path] }.sort
+
+    assert_equal ["/", "sample", "sub/"], lists
+  end
+
+  test "list returns the entry" do
+    entry = @op.list("/").first
+
+    assert entry.is_a?(OpenDAL::Entry)
+    assert_equal "sample", entry.name
+  end
+
+  test "entry has the metadata" do
+    metadata = @op.list("sample").first.metadata
+
+    assert metadata.file?
+    assert !metadata.dir?
+  end
+
+  test "scans the directory" do
+    lister = @op.scan("")
+
+    lists = lister.map(&:to_h).map { |e| e[:path] }.sort
+
+    assert_equal ["/", "sample", "sub/", "sub/sample"], lists
+  end
+
+  test "scan returns the entry" do
+    entry = @op.scan("sample").first
+
+    assert entry.is_a?(OpenDAL::Entry)
+    assert_equal "sample", entry.name
+  end
+end