This is an automated email from the ASF dual-hosted git repository. erickguan pushed a commit to branch ruby-binding-doc in repository https://gitbox.apache.org/repos/asf/opendal.git
commit 429ca57cac3eb0755fa4ccc4e631a203c24921d1 Author: Erick Guan <[email protected]> AuthorDate: Tue Sep 30 20:49:00 2025 +0200 Update README for Ruby binding --- bindings/ruby/README.md | 121 ++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 117 insertions(+), 4 deletions(-) diff --git a/bindings/ruby/README.md b/bindings/ruby/README.md index ea1606aaf..854c3bffa 100644 --- a/bindings/ruby/README.md +++ b/bindings/ruby/README.md @@ -1,14 +1,119 @@ -# Apache OpenDAL™ Ruby Binding (WIP) +# Apache OpenDAL™ Ruby Binding -[](https://opendal.apache.org/bindings/ruby/) + + -This crate intends to build a native ruby binding. +OpenDAL's Ruby gem.  +## Get started + +### Installation + +Install gem: + +```shell +bundle add opendal +``` + +or add it in Gemfile: + +```ruby +# Gemfile + +source "https://rubygems.org"; + +gem 'opendal' +``` + +### Examples + +#### File operations with an in-memory storage + +```ruby +require 'opendal' + +op = OpenDal::Operator.new("memory", {}) +op.write("file", "hello world") +puts op.read("file") # => "hello world" +puts "" + +puts "List:", op.list("").map { |e| e.path } +puts "" + +puts "Stat" +puts op.stat("file").inspect # => #<OpenDal::Metadata mode: File, content_type: , content_length: 11> +puts "" + +puts "Deleting 'file'" +op.delete("/file") +puts "" + +puts "Exist?", op.exist?("/file") # => false +puts "" + +puts "Info:", op.info.inspect # => #<OpenDal::OperatorInfo scheme: "memory", root: "/"> +``` + +#### A S3 operator + +```ruby +require 'opendal' + +op = OpenDal::Operator.new("s3", { + "endpoint" => "http://localhost:9000";, + "access_key_id" => "minioadmin" , + "secret_access_key" => "minioadmin", + "bucket" => "test", + "region" => "us-east-1", +}) +op.write("file", "hello world") +puts op.read("file") # => "hello world" +puts "" + +puts "List:", op.list("").map { |e| e.path } +puts "" + +puts "Stat" +puts op.stat("file").inspect # => #<OpenDal::Metadata mode: File, content_type: binary/octet-stream, content_length: 11> +puts "" + +puts "Deleting 'file'" +op.delete("file") +puts "" + +puts "Exist?", op.exist?("file") # => false +puts "" + +puts "Info:", op.info.inspect # => #<OpenDal::OperatorInfo scheme: "s3", root: "/"> +``` + +#### Use middleware + +```ruby +require 'opendal' + +op = OpenDal::Operator.new("s3", { + "endpoint" => "http://localhost:9000";, + "access_key_id" => "minioadmin" , + "secret_access_key" => "minioadmin", + "bucket" => "test", + "region" => "us-east-1", +}) + +op.middleware(OpenDal::Middleware::ConcurrentLimit.new(5)) +op.middleware(OpenDal::Middleware::Retry.new) +op.middleware(OpenDal::Middleware::Timeout.new(1, 2)) + +op.list("/").map do |e| + puts e.inspect +end +``` + ## Development -Install gems: +Install gem and its dependencies: ```shell bundle @@ -26,6 +131,14 @@ Run tests: bundle exec rake test ``` +Run linters: + +```shell +bundle exec rake standard:fix +rustfmt --config-path ../../rustfmt.toml src/*.rs # Run rustfmt for Rust files +cargo clippy --fix --all-targets # Run rust linter clippy +``` + ## License and Trademarks Licensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0
