docs/ruby/file.README.html - opendal - Git at Google

 <!DOCTYPE html><html><head>
     <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>
   File: README

     — Documentation by YARD 0.9.38

 </title>

   <link rel="stylesheet" href="css/style.css" type="text/css">

   <link rel="stylesheet" href="css/common.css" type="text/css">

 <script type="text/javascript">
   pathId = "README";
   relpath = '';
 </script>


   <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>

   <script type="text/javascript" charset="utf-8" src="js/app.js"></script>


   </head>
   <body>
     <div class="nav_wrap">
       <iframe id="nav" src="file_list.html?1"></iframe>
       <div id="resizer"></div>
     </div>

     <div id="main" tabindex="-1">
       <div id="header">
         <div id="menu">

     <a href="_index.html">Index</a> »
     <span class="title">File: README</span>

 </div>

         <div id="search">

     <a class="full_list_link" id="class_list_link" href="class_list.html">

         <svg width="24" height="24">
           <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
           <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
           <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
         </svg>
     </a>

 </div>
         <div class="clear"></div>
       </div>

       <div id="content"><div id="filecontents"><h1 id="apache-opendal-ruby-binding">Apache OpenDAL™ Ruby Binding</h1>

 <p><a href="https://rubygems.org/gems/opendal"><img src="/img/external/543c994a056a0d48f83ab1ea91f6ee77.svg" alt="Gem Version"></a>
 <a href="https://rubygems.org/gems/opendal"><img src="/img/external/c4d62baef0803d759df7a2ff252188c0.svg" alt="Gem Downloads (for latest version)"></a></p>

 <p>OpenDAL's Ruby <a href="https://rubygems.org/gems/opendal">gem</a>.</p>

 <p><img src="/img/external/9a183ec0ae8ab600b6baceb2c70a2367.jpg" alt=""></p>

 <blockquote>
 <p><strong>Note</strong>: This binding has its own independent version number, which may differ from the Rust core version. When checking for updates or compatibility, always refer to this binding's version rather than the core version.</p>
 </blockquote>

 <p>Read OpenDAL's <a href="https://opendal.apache.org/docs/ruby/">ruby</a> documentation.</p>

 <p>You can find Rust documentation <a href="https://docs.rs/opendal/latest/opendal/index.html">here</a>.</p>

 <h2 id="get-started">Get started</h2>

 <h3 id="installation">Installation</h3>

 <p>Install gem:</p>

 <pre class="code shell"><code class="shell">bundle add opendal
 </code></pre>

 <p>or add it in Gemfile:</p>

 <pre class="code ruby"><code class="ruby"><span class="comment"># Gemfile
 </span>
 <span class="id identifier rubyid_source">source</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">https://rubygems.org</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_gem">gem</span> <span class="tstring"><span class="tstring_beg">'</span><span class="tstring_content">opendal</span><span class="tstring_end">'</span></span>
 </code></pre>

 <h3 id="examples">Examples</h3>

 <h4 id="file-operations-with-an-in-memory-storage">File operations with an in-memory storage</h4>

 <pre class="code ruby"><code class="ruby"><span class="id identifier rubyid_require">require</span> <span class="tstring"><span class="tstring_beg">'</span><span class="tstring_content">opendal</span><span class="tstring_end">'</span></span>

 <span class="id identifier rubyid_op">op</span> <span class="op">=</span> <span class="const"><span class="object_link"><a href="OpenDal.html" title="OpenDal (module)">OpenDal</a></span></span><span class="op">::</span><span class="const"><span class="object_link"><a href="OpenDal/Operator.html" title="OpenDal::Operator (class)">Operator</a></span></span><span class="period">.</span><span class="id identifier rubyid_new">new</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">memory</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="lbrace">{</span><span class="rbrace">}</span><span class="rparen">)</span>
 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_write">write</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">hello world</span><span class="tstring_end">"</span></span><span class="rparen">)</span>
 <span class="id identifier rubyid_puts">puts</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_read">read</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="rparen">)</span> <span class="comment"># =&gt; "hello world"
 </span><span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">List:</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_list">list</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span><span class="rparen">)</span><span class="period">.</span><span class="id identifier rubyid_map">map</span> <span class="lbrace">{</span> <span class="op">|</span><span class="id identifier rubyid_e">e</span><span class="op">|</span> <span class="id identifier rubyid_e">e</span><span class="period">.</span><span class="id identifier rubyid_path">path</span> <span class="rbrace">}</span>
 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Stat</span><span class="tstring_end">"</span></span>
 <span class="id identifier rubyid_puts">puts</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_stat">stat</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="rparen">)</span><span class="period">.</span><span class="id identifier rubyid_inspect">inspect</span> <span class="comment"># =&gt; #&lt;OpenDal::Metadata mode: File,         content_type: ,         content_length: 11&gt;
 </span><span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Deleting 'file'</span><span class="tstring_end">"</span></span>
 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_delete">delete</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">/file</span><span class="tstring_end">"</span></span><span class="rparen">)</span>
 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Exist?</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_exist?">exist?</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">/file</span><span class="tstring_end">"</span></span><span class="rparen">)</span> <span class="comment"># =&gt; false
 </span><span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Info:</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_info">info</span><span class="period">.</span><span class="id identifier rubyid_inspect">inspect</span> <span class="comment"># =&gt; #&lt;OpenDal::OperatorInfo scheme: "memory", root: "/"&gt;
 </span></code></pre>

 <h4 id="a-s3-operator">A S3 operator</h4>

 <pre class="code ruby"><code class="ruby"><span class="id identifier rubyid_require">require</span> <span class="tstring"><span class="tstring_beg">'</span><span class="tstring_content">opendal</span><span class="tstring_end">'</span></span>

 <span class="id identifier rubyid_op">op</span> <span class="op">=</span> <span class="const"><span class="object_link"><a href="OpenDal.html" title="OpenDal (module)">OpenDal</a></span></span><span class="op">::</span><span class="const"><span class="object_link"><a href="OpenDal/Operator.html" title="OpenDal::Operator (class)">Operator</a></span></span><span class="period">.</span><span class="id identifier rubyid_new">new</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">s3</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="lbrace">{</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">endpoint</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">http://localhost:9000</span><span class="tstring_end">"</span></span><span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">access_key_id</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">minioadmin</span><span class="tstring_end">"</span></span> <span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">secret_access_key</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">minioadmin</span><span class="tstring_end">"</span></span><span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">bucket</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">test</span><span class="tstring_end">"</span></span><span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">region</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">us-east-1</span><span class="tstring_end">"</span></span><span class="comma">,</span>
 <span class="rbrace">}</span><span class="rparen">)</span>
 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_write">write</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">hello world</span><span class="tstring_end">"</span></span><span class="rparen">)</span>
 <span class="id identifier rubyid_puts">puts</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_read">read</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="rparen">)</span> <span class="comment"># =&gt; "hello world"
 </span><span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">List:</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_list">list</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span><span class="rparen">)</span><span class="period">.</span><span class="id identifier rubyid_map">map</span> <span class="lbrace">{</span> <span class="op">|</span><span class="id identifier rubyid_e">e</span><span class="op">|</span> <span class="id identifier rubyid_e">e</span><span class="period">.</span><span class="id identifier rubyid_path">path</span> <span class="rbrace">}</span>
 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Stat</span><span class="tstring_end">"</span></span>
 <span class="id identifier rubyid_puts">puts</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_stat">stat</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="rparen">)</span><span class="period">.</span><span class="id identifier rubyid_inspect">inspect</span> <span class="comment"># =&gt; #&lt;OpenDal::Metadata mode: File,         content_type: binary/octet-stream,         content_length: 11&gt;
 </span><span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Deleting 'file'</span><span class="tstring_end">"</span></span>
 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_delete">delete</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="rparen">)</span>
 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Exist?</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_exist?">exist?</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">file</span><span class="tstring_end">"</span></span><span class="rparen">)</span> <span class="comment"># =&gt; false
 </span><span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_end">"</span></span>

 <span class="id identifier rubyid_puts">puts</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">Info:</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_info">info</span><span class="period">.</span><span class="id identifier rubyid_inspect">inspect</span> <span class="comment"># =&gt; #&lt;OpenDal::OperatorInfo scheme: "s3", root: "/"&gt;
 </span></code></pre>

 <h4 id="use-middleware">Use middleware</h4>

 <pre class="code ruby"><code class="ruby"><span class="id identifier rubyid_require">require</span> <span class="tstring"><span class="tstring_beg">'</span><span class="tstring_content">opendal</span><span class="tstring_end">'</span></span>

 <span class="id identifier rubyid_op">op</span> <span class="op">=</span> <span class="const"><span class="object_link"><a href="OpenDal.html" title="OpenDal (module)">OpenDal</a></span></span><span class="op">::</span><span class="const"><span class="object_link"><a href="OpenDal/Operator.html" title="OpenDal::Operator (class)">Operator</a></span></span><span class="period">.</span><span class="id identifier rubyid_new">new</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">s3</span><span class="tstring_end">"</span></span><span class="comma">,</span> <span class="lbrace">{</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">endpoint</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">http://localhost:9000</span><span class="tstring_end">"</span></span><span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">access_key_id</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">minioadmin</span><span class="tstring_end">"</span></span> <span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">secret_access_key</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">minioadmin</span><span class="tstring_end">"</span></span><span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">bucket</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">test</span><span class="tstring_end">"</span></span><span class="comma">,</span>
   <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">region</span><span class="tstring_end">"</span></span> <span class="op">=&gt;</span> <span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">us-east-1</span><span class="tstring_end">"</span></span><span class="comma">,</span>
 <span class="rbrace">}</span><span class="rparen">)</span>

 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_middleware">middleware</span><span class="lparen">(</span><span class="const"><span class="object_link"><a href="OpenDal.html" title="OpenDal (module)">OpenDal</a></span></span><span class="op">::</span><span class="const">Middleware</span><span class="op">::</span><span class="const">ConcurrentLimit</span><span class="period">.</span><span class="id identifier rubyid_new">new</span><span class="lparen">(</span><span class="int">5</span><span class="rparen">)</span><span class="rparen">)</span>
 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_middleware">middleware</span><span class="lparen">(</span><span class="const"><span class="object_link"><a href="OpenDal.html" title="OpenDal (module)">OpenDal</a></span></span><span class="op">::</span><span class="const">Middleware</span><span class="op">::</span><span class="const">Retry</span><span class="period">.</span><span class="id identifier rubyid_new">new</span><span class="rparen">)</span>
 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_middleware">middleware</span><span class="lparen">(</span><span class="const"><span class="object_link"><a href="OpenDal.html" title="OpenDal (module)">OpenDal</a></span></span><span class="op">::</span><span class="const">Middleware</span><span class="op">::</span><span class="const">Timeout</span><span class="period">.</span><span class="id identifier rubyid_new">new</span><span class="lparen">(</span><span class="int">1</span><span class="comma">,</span> <span class="int">2</span><span class="rparen">)</span><span class="rparen">)</span>

 <span class="id identifier rubyid_op">op</span><span class="period">.</span><span class="id identifier rubyid_list">list</span><span class="lparen">(</span><span class="tstring"><span class="tstring_beg">"</span><span class="tstring_content">/</span><span class="tstring_end">"</span></span><span class="rparen">)</span><span class="period">.</span><span class="id identifier rubyid_map">map</span> <span class="kw">do</span> <span class="op">|</span><span class="id identifier rubyid_e">e</span><span class="op">|</span>
   <span class="id identifier rubyid_puts">puts</span> <span class="id identifier rubyid_e">e</span><span class="period">.</span><span class="id identifier rubyid_inspect">inspect</span>
 <span class="kw">end</span>
 </code></pre>

 <h2 id="documentation">Documentation</h2>

 <p>More detailed documentation is a work in progress.</p>

 <ul>
 <li>OpenDAL's <a href="https://opendal.apache.org/docs/ruby/">ruby</a> documentation</li>
 <li>Rust <a href="https://docs.rs/opendal/latest/opendal/index.html">documentation</a></li>
 <li>Rust documentation for <a href="https://docs.rs/opendal/latest/opendal/services/index.html">services</a></li>
 <li>Rust documentation for <a href="https://docs.rs/opendal/latest/opendal/layers/index.html">layers</a> (middlewares in Ruby)</li>
 </ul>

 <h2 id="development">Development</h2>

 <p>Install gem and its dependencies:</p>

 <pre class="code shell"><code class="shell">bundle
 </code></pre>

 <p>Build bindings:</p>

 <pre class="code shell"><code class="shell">bundle exec rake compile
 </code></pre>

 <p>Run tests:</p>

 <pre class="code shell"><code class="shell">bundle exec rake test
 </code></pre>

 <p>Run linters:</p>

 <pre class="code shell"><code class="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
 </code></pre>

 <h2 id="license-and-trademarks">License and Trademarks</h2>

 <p>Licensed under the Apache License, Version 2.0: <a href="http://www.apache.org/licenses/LICENSE-2.0">http://www.apache.org/licenses/LICENSE-2.0</a></p>

 <p>Apache OpenDAL, OpenDAL, and Apache are either registered trademarks or trademarks of the Apache Software Foundation.</p>
 </div></div>

       <div id="footer">
   Generated on Mon Dec 29 05:11:28 2025 by
   <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.38 (ruby-3.3.10).
 </div>

     </div>

 </body></html>