cinnabar 0.0.0 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6647629512489671373fd91ffdd165fcdc08306caad030e7ad827adefb070bf5
-  data.tar.gz: 24e45eca6665b1a715dc9b7cd58547b6e6bb4ffbc1777a6250c8d55f537acaed
+  metadata.gz: 7ba73ee68ae237057d44f55990de599fae1290bdb0ad22ed9f4a3cc6688e8a9c
+  data.tar.gz: 0ca77910329aa2c50e2ee0f6562ae1873ab31db0926dedc856aafeb9e1b98c03
 SHA512:
-  metadata.gz: 9de983869bf035c25dcadaab1f4b803a46e2dabc48e1d5bfe42ca4314006f9b13f1aa7bebb37fbbfb226c266fd0689dec57b15c0957735137349e9b9b0bf2a79
-  data.tar.gz: 53d3feb704e7004cb4ba194854186a543fe0d42a9fca1abe5a689aba9464bac1ad7d6f30cdd83214710dd6543a1a2be260b3ea6568d459ea5b6bfa77358a6cc4
+  metadata.gz: 9123046f853c2533f6adbab221418066af5c351b283c346e31937ecd7a8010b897860cb3fb1365386d3d6abfdf7e822e405aa79ab63420fd1553cb5605f08b9f
+  data.tar.gz: 54b6ac22db5f6b5bb7287329d9b74876f03a8e76738968276cdd45b6d2ce22281b084c203ae93e66615bead81a2ce94cebbfdfd518c84956017a6f3a3e51949b

data/.rubocop.yml

@@ -36,7 +36,7 @@ Layout/CaseIndentation:
   EnforcedStyle: end
   IndentOneStep: true
 Layout/MultilineMethodCallIndentation:
-  EnforcedStyle: indented_relative_to_receiver
+  EnforcedStyle: indented
 
 
 Naming/AsciiIdentifiers:

data/.yardopts

@@ -0,0 +1,4 @@
+--markup markdown
+--title 'Cinnabar'
+--protected
+--no-private

data/docs/Readme-zh.md

@@ -24,41 +24,9 @@
 2.  朱砂有毒。这个项目是为了 **猛、糙、快** (a.k.a. *Dirty and Quick*) 的目的而开发的，可能会产生意料之外的副作用（它并非完全无害）。
 3.  朱砂是一种硫化汞 (HgS) 的矿物，呈深红色，而 Ruby 也是一种深红色的宝石。给一个 Ruby 项目取名为 “Cinnabar（朱砂）” 非常贴切。
 
-## 快速上手
+## API DOC
 
-Github Actions for cinnabar
+![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
 
-```yaml
-env:
-  # Speeds up script startup by disabling RubyGems
-  RUBYOPT: "--disable=gems"
-  default_ci_shell: ruby cinnabar/ci.rb {0}
+- Github Pages: <https://2moe.github.io/cinnabar>
 
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        shell: ${{env.default_ci_shell}}
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: clone cinnabar
-        uses: actions/checkout@v6
-        with:
-          repository: 2moe/cinnabar
-          path: cinnabar
-          ref: v0.0.0
-
-      - name: (example) run cargo command
-        run: |
-          {
-            cargo: (),
-            build: (),
-            profile: 'release',
-            verbose: true,
-            target: 'x86_64-unknown-linux-musl'
-          }
-            .to_argv
-            .run
-```

data/docs/Readme.md

@@ -24,6 +24,12 @@ A:
 2. Cinnabar is toxic. This project was developed for *Dirty and Quick* purposes and may produce unexpected side effects—in a sense, it is not entirely harmless.
 3. Cinnabar, a mineral form of mercury sulfide (HgS), is a deep red-colored stone. And ruby is also a deep red stone. Naming a Ruby project "Cinnabar" is particularly fitting.
 
+## API DOC
+
+![ClassDiagram](../misc/assets/svg/ClassDiagram.svg)
+
+- Github Pages: <https://2moe.github.io/cinnabar>
+
 ## Quick Start
 
 Github Actions for cinnabar
@@ -33,6 +39,8 @@ env:
   # Speeds up script startup by disabling RubyGems
   RUBYOPT: "--disable=gems"
   default_ci_shell: ruby cinnabar/ci.rb {0}
+  # optional values: debug, info, warn, error, fatal, unknown
+  RUBY_LOG: "debug"
 
 jobs:
   build:
@@ -48,7 +56,7 @@ jobs:
         with:
           repository: 2moe/cinnabar
           path: cinnabar
-          ref: v0.0.0
+          ref: v0.0.1
 
       - name: (example) run cargo command
         run: |
@@ -60,5 +68,87 @@ jobs:
             target: 'x86_64-unknown-linux-musl'
           }
             .to_argv
-            .run
+            .run_cmd
+```
+
+## Examples
+
+### Command Runner
+
+#### `.run` + pass stdin data
+
+```ruby,yaml
+- run: |
+    opts = { stdin_data: "Hello", allow_failure: true }
+    stdout = %w[wc -m].run(opts:)
+
+    stdout.to_i == 5 #=> true
+```
+
+#### `.async_run`
+
+```ruby,yaml
+- run: |
+    'building wasi file...'.log_dbg
+    task = {
+      cargo: (),
+      b: (),
+      r: true,
+      target: 'wasm32-wasip2'
+    } .to_argv
+      .async_run
+
+    stdout, status = task.wait_with_output
+    stdout.log_info
+    raise "wasi" unless status.success?
+```
+
+#### `.async_run` + pass stdin data
+
+```ruby,yaml
+- run: |
+    stdin_data = <<~'QMP_JSON'
+      { "execute":"qmp_capabilities" }
+      { "execute":"query-cpu-model-expansion",
+        "arguments":{"type":"full","model":{"name":"host"}} }
+      { "execute":"quit" }
+    QMP_JSON
+
+    # opts = { stdin_data:, stdin_binmode: false }
+    opts = { stdin_data: }
+
+    accel = %w[kvm hvf tcg].join ':'
+    task = {
+      'qemu-system-x86_64': (),
+      machine: "accel=#{accel}",
+      cpu: 'host',
+      display: 'none',
+      nodefaults: true,
+      no_user_config: true,
+      qmp: 'stdio',
+    } .to_argv_bsd
+      .async_run(opts:)
+
+    stdout, status = task.wait_with_output
+    stdout.log_info if status.success?
+```
+
+### Downloader
+
+```ruby,yaml
+- run: |
+    url = 'https://docs.ruby-lang.org/en/master'
+    url.download
+    # OR: url.download({out_dir: "/tmp", file_name: "index.html"})
+```
+
+### Function Pipe
+
+```ruby,yaml
+- run: |
+    upper = ->s { s.upcase }
+
+    'Foo'
+      .▷(upper)
+      .▷ :puts #=> "FOO"
 ```

data/lib/cinnabar/00_pre.rb

@@ -2,9 +2,9 @@
 
 # Define Cinnabar first to prevent errors when creating Cinnabar::SubMod
 # (compact ClassAndModuleChildren)
-#
 # ------------------
 
+# @see https://github.com/2moe/cinnabar
 module Cinnabar; end
 
 # To ensure compatibility with "--disable=gems" (allowing users to pre-require),

data/lib/cinnabar/cmd_runner.rb

@@ -1,162 +1,511 @@
+# typed: false
 # frozen_string_literal: true
 
 module Cinnabar::Command
   module_function
 
+  require 'open3'
   using Sinlog::Refin
 
-  # This lambda function is capable of running system command.
+  # Executes the command synchronously (blocking) and returns its standard output.
   #
-  # = Example
+  # @raise [RuntimeError] when `allow_failure: false` and the process exits with non-zero status
   #
-  #     using Cinnabar::FnPipe::Refin
+  # @example pass env
   #
   #     Cmd = Cinnabar::Command
-  #     %w[sleep 3].▷ Cmd.run
-  def run
-    ->(array) do
-      'Running system cmd'.log_dbg
-      array.log_info
-      success = system(*array)
-      Kernel.raise "Command failed: #{array.join(' ')}" unless success
+  #     cmd_arr = %w[sh -c] << 'printf $WW'
+  #     env_hash = {WW: 2}
+  #     opts = {allow_failure: true}
+  #     output = Cmd.run(cmd_arr, env_hash, opts:)
+  #     output.to_i == 2 #=> true
+  #
+  # @example pass stdin data
+  #
+  #     opts = {stdin_data: "Hello\nWorld\n"}
+  #     output = Cinnabar::Command.run(%w[wc -l], opts:)
+  #     output.to_i == 2 #=> true
+  #
+  # @param cmd_arr [Array<String>] The command and its arguments (e.g., `%w[printf hello]`).
+  # @param env_hash [#to_h] Environment variables to pass to the command.
+  # @param opts [Hash]
+  #
+  #   - Only the `:allow_failure` is extracted and handled explicitly;
+  #   - all other keys are passed through to **Open3.capture2** unchanged.
+  #
+  # @option opts [Boolean] :allow_failure
+  #   Indicates whether the command is allowed to fail.
+  #
+  # @return [String, nil] the standard output of the command.
+  #
+  # @see async_run
+  def run(cmd_arr, env_hash = nil, opts: {}) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/CyclomaticComplexity,Metrics/PerceivedComplexity
+    'Running and capturing the output of a system command.'.log_dbg
+    cmd_arr.log_info
+    "opts: #{opts}".log_dbg
+
+    allow_failure = opts.delete(:allow_failure) || false
+
+    final_env = normalize_env(env_hash)
+
+    begin
+      stdout, status =
+        if final_env.nil?
+          Open3.capture2(*cmd_arr, opts)
+        else
+          Open3.capture2(final_env, *cmd_arr, opts)
+        end
+    rescue StandardError => e
+      Kernel.raise e unless allow_failure
+      e.log_err
+      return stdout
     end
+
+    return stdout if status.success?
+
+    err_msg = "Command failed: #{cmd_arr.join(' ')}"
+    Kernel.raise err_msg unless allow_failure
+
+    err_msg.log_err
+    stdout
   end
 
-  # Lambda that runs system command in the background.
+  # Executes a system command using Ruby's `Kernel.system`.
   #
-  # @raise [RuntimeError] if the process exits with non-zero status
+  # It runs the command synchronously, blocks until completion, and does not capture stdout or stderr.
   #
-  # = Example
+  # @param cmd_arr [Array<String>] The command and its arguments as an array,
+  #   e.g., `%w[ls -lh]`.
+  #
+  # @param env_hash [#to_h] Environment variables to pass to the command.
+  # @param opts [Hash]
+  #
+  #   - Only the `:allow_failure` is extracted and handled explicitly;
+  #   - all other keys are passed through to `Kernel.system` unchanged.
+  #
+  # @option opts [Boolean] :allow_failure
+  #   Indicates whether the command is allowed to fail.
+  #   If true, the method will return false instead of raising an exception when the
+  #   command exits with a non-zero status.
+  #
+  # @see https://docs.ruby-lang.org/en/3.4/Process.html#module-Process-label-Execution+Options
+  #
+  # @example pwd
   #
   #     Cmd = Cinnabar::Command
-  #     pid = %w[sleep 5].then(&Cmd.run_in_bg)
-  def run_in_bg
-    ->(array) do
-      'Running system cmd in the background'.log_dbg
-      array.log_info
-      Process.spawn(*array)
+  #     opts = {chdir: '/tmp', allow_failure: true}
+  #     Cmd.run_cmd(%w[pwd], opts:)
+  #
+  # @example pass env
+  #
+  #     Cmd = Cinnabar::Command
+  #     cmd_arr = %w[sh -c] << 'printf $WW'
+  #     env_hash = {WW: 2}
+  #     Cmd.run_cmd(cmd_arr, env_hash)
+  #
+  # @return [Boolean] Returns true if the command succeeds (exit status 0),
+  #   or false if it fails and `allow_failure` is true.
+  # @raise [RuntimeError] Raises an error if the command fails and `allow_failure` is false.
+  def run_cmd(cmd_arr, env_hash = nil, opts: {})
+    'Running system command'.log_dbg
+    cmd_arr.log_info
+    "opts: #{opts}".log_dbg
+
+    allow_failure = opts.delete(:allow_failure) || false
+    exception = !allow_failure
+    "exception: #{exception}".log_dbg
+    options = opts.merge({ exception: })
+
+    final_env = normalize_env(env_hash)
+    if final_env.nil?
+      Kernel.system(*cmd_arr, options)
+    else
+      Kernel.system(final_env, *cmd_arr, options)
     end
   end
 
-  # ---------------
+  # @param hash [#to_h]
+  # @return [Hash{String => String}, nil] a hash where both keys and values are strings
+  def normalize_env(hash)
+    return nil if hash.nil?
+    return nil if hash.respond_to?(:empty?) && hash.empty?
+
+    hash.to_h { |k, v| [k.to_s, v.to_s] }
+      .tap { "normalized_env:#{_1}".log_dbg }
+  end
 
-  # Lambda that waits for a child process to complete and checks its status.
+  # Launch a command asynchronously (non-blocking) and return its stdout stream and process waiter.
   #
-  # This method requires the child process to exit with a successful status;
-  # otherwise, it will raise an error.
+  # This is a sugar over **Open3.popen2**, intended to start a subprocess
+  # and **immediately** hand back:
   #
-  # = Example
+  #    1. an `IO` for reading the command's stdout, and
+  #    2. a `Process::Waiter` (a thread-like object) that can be awaited later.
   #
-  #     using Cinnabar::FnPipe::Refin
+  # - If `:stdin_data` is provided, the data will be written to
+  #   the child's stdin and the stdin will be closed.
+  # - When `:stdin_data` is absent, stdin is simply closed and
+  #   the method returns immediately without blocking on output.
+  #
+  # @param cmd_arr [Array<String>] The command and its arguments (e.g., `%w[printf hello]`).
+  # @param env_hash [#to_h] Optional environment variables;
+  #   keys/values will be normalized by {#normalize_env} before being passed to the child.
+  #
+  # @param opts [Hash] Additional options.
+  #
+  #   - Only the following keys are extracted and handled explicitly;
+  #     - :stdin_data
+  #     - :binmode
+  #     - :stdin_binmode
+  #     - :stdout_binmode
+  #
+  #   all other keys are passed through to **Open3.popen2** unchanged.
+  #
+  # @option opts [String, #readpartial] :stdin_data
+  #   Data to write to the child's stdin. If it responds to `#readpartial`,
+  #   it will be streamed via **IO.copy_stream**;
+  #
+  # @option opts [Boolean] :binmode
+  #   When `true`, set both stdin and stdout to binary mode (useful for binary data).
+  #
+  # @option opts [Boolean] :stdin_binmode
+  #   Sets only stdin to binary mode.
+  #
+  # @option opts [Boolean] :stdout_binmode
+  #   Sets only stdout to binary mode.
+  #
+  # @return [Array(IO, Process::Waiter)] A pair `[stdout_io, waiter]`:
+  #
+  #   - `stdout_io` is an `IO` for reading **stdout**
+  #   - `waiter` is a `Process::Waiter`;
+  #     - call `waiter.value` to get `Process::Status`;
+  #     - or `waiter.join` to block until the process exits.
+  #
+  # @raise [StandardError] Reraises any non-`Errno::EPIPE` exception encountered while writing to stdin.
+  #   `Errno::EPIPE` is logged and swallowed.
+  #
+  # @example start a process and later wait for it
+  #
+  #     Cmd = Cinnabar::Command
+  #     stdout_fd, waiter = Cmd.async_run(['sh', '-c', 'echo hello; sleep 1; echo done'])
+  #
+  #     output, status = Cmd.wait_with_output(stdout_fd, waiter)
+  #
+  # @example pass stdin data
   #
   #     Cmd = Cinnabar::Command
-  #     %w[sleep 3]
-  #       .▷(Cmd.run_in_bg) #=> pid
-  #       .▷(Cmd.wait_task)
-  #
-  def wait_task
-    ->(pid) do
-      "wait pid: #{pid}".log_dbg
-      Process.wait(pid)
-      status = $? # rubocop:disable Style/SpecialGlobalVars
-      "child_status: #{status}".log_dbg
-      Kernel.raise %(Command failed with "#{status}") unless status.success?
+  #     opts = {stdin_data: "Run in the background" }
+  #     io_and_waiter = Cmd.async_run(%w[wc -m], opts:)
+  #
+  #     output, status = Cmd.wait_with_output(*io_and_waiter)
+  #     status.success?   #=> true
+  #     output.to_i == 21 #=> true
+  #
+  # @see wait_with_output
+  # @see run
+  def async_run(cmd_arr, env_hash = nil, opts: {}) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize,Metrics/PerceivedComplexity,Metrics/CyclomaticComplexity
+    "Asynchronously executing system command: #{cmd_arr}".log_dbg
+    "opts: #{opts}".log_dbg
+
+    stdin_data = opts.delete(:stdin_data)
+    binmode = opts.delete(:binmode)
+    stdin_binmode = opts.delete(:stdin_binmode)
+    stdout_binmode = opts.delete(:stdout_binmode)
+
+    'async_run() does not support the :allow_failure option.'.log_warn if opts.delete(:allow_failure)
+
+    final_env = normalize_env(env_hash)
+
+    stdin, stdout, waiter =
+      if final_env.nil?
+        Open3.popen2(*cmd_arr, opts)
+      else
+        Open3.popen2(final_env, *cmd_arr, opts)
+      end
+
+    if binmode
+      stdin.binmode
+      stdout.binmode
+    else
+      stdin.binmode if stdin_binmode
+      stdout.binmode if stdout_binmode
+    end
+
+    # Non-blocking: no stdin to write; return immediately
+    unless stdin_data
+      stdin.close
+      return [stdout, waiter]
+    end
+
+    begin
+      if stdin_data.respond_to? :readpartial
+        IO.copy_stream(stdin_data, stdin)
+      else
+        stdin.write stdin_data
+      end
+    rescue Errno::EPIPE => e
+      e.log_err
+    rescue StandardError => e
+      "Failed to write stdin data: #{e}".log_err
+      Kernel.raise e
+    ensure
+      stdin.close
     end
+    [stdout, waiter]
+  end
+
+  # Waits for a process to finish and reads all remaining output from its stdout.
+  #
+  # @param io_fd [IO] The IO object connected to the process's stdout (or combined stdout & stderr).
+  # @param waiter [Process::Waiter] The waiter thread returned by **Open3.popen2** or **Open3.popen2e**.
+  #
+  # @return [Array(String, Process::Status)] A two-element array:
+  #
+  #   - The full output read from `io_fd`.
+  #   - The **Process::Status** object representing the process's exit status.
+  #
+  # @example Wait for process and capture output
+  #
+  #   require 'sinlog'
+  #   using Sinlog::Refin
+  #
+  #   Cmd = Cinnabar::Command
+  #
+  #   fd, waiter = %w[ruby -e].push('sleep 2; puts "OK"')
+  #                 .then { Cmd.async_run(_1) }
+  #
+  #   "You can now do other things without waiting for the process to complete.".log_dbg
+  #
+  #   "blocking wait".log_info
+  #   output, status = Cmd.wait_with_output(fd, waiter)
+  #
+  #   "Exit code: #{status.exitstatus}".log_warn unless status.success?
+  #   "Output:\n#{output}".log_info
+  #
+  # @note This method blocks until the process exits and all output is read.
+  # @see async_run
+  def wait_with_output(io_fd, waiter)
+    status = waiter.value
+    output = io_fd.read
+    io_fd.close
+    [output, status]
   end
-  # ---------------
 end
 
 module Cinnabar::Command
-  module ArrayExt
-    def run
-      Cinnabar::Command.run.call(self)
+  # The foundation of {ArrRefin} and {ArrMixin}
+  # @see Cinnabar::Command.run
+  # @see Cinnabar::Command.async_run
+  # @see Cinnabar::Command.run_cmd
+  module ArrExt
+    # Executes the command synchronously (blocking) and returns its standard output.
+    #
+    # @note self [`Array<String>`]: The command and its arguments (e.g., `%w[printf hello]`).
+    #
+    # @param env_hash [#to_h] Environment variables to pass to the command.
+    # @param opts [Hash]
+    #
+    #   - Only the `:allow_failure` is extracted and handled explicitly;
+    #   - all other keys are passed through to **Open3.capture2** unchanged.
+    #
+    # @raise [StandardError] when `allow_failure: false` and the process exits with non-zero status
+    #
+    # @return [String, nil] the standard output of the command.
+    # @see Cinnabar::Command.run
+    #
+    # @example pass stdin data
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #     # OR: include Cinnabar::Command::ArrMixin
+    #
+    #     opts = {allow_failure: true, stdin_data: "Hello\nWorld\n"}
+    #     output = %w[wc -l].run(opts:)
+    #     output.to_i == 2 unless output.nil? #=> true
+    #
+    # @note This method blocks until the process completes.
+    def run(env_hash = nil, opts: {})
+      Cinnabar::Command.run(self, env_hash, opts:)
+    end
+
+    # Starts a command asynchronously using this `Array<String>`.
+    #
+    # @note self [`Array<String>`]: The command and its arguments (e.g., `%w[printf hello]`).
+    #
+    # @param env_hash [#to_h] Optional environment variables.
+    # @param opts [Hash]
+    #
+    # @see Cinnabar::Command.async_run
+    #
+    # @return [Array(IO, Process::Waiter)] a pair `[stdout_io, waiter]`
+    #
+    # @example pass stdin data
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #     # OR: include Cinnabar::Command::ArrMixin
+    #
+    #     opts = {stdin_data: "Hello\nWorld\n"}
+    #     io_and_waiter = %w[wc -l].async_run(opts:)
+    #     output, status = Cinnabar::Command.wait_with_output *io_and_waiter
+    #     output.to_i == 2 #=> true
+    def async_run(env_hash = nil, opts: {})
+      Cinnabar::Command.async_run(self, env_hash, opts:)
     end
 
-    # Spawns system command (runs in the background)
-    def run_in_bg
-      Cinnabar::Command.run_in_bg.call(self)
+    # @note self [`Array<String>`]: The command and its arguments (e.g., `%w[printf hello]`).
+    #
+    # @example pwd
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #     # OR: include Cinnabar::Command::ArrMixin
+    #
+    #     opts = {chdir: '/tmp', allow_failure: true}
+    #     status = %w[pwd].run_cmd(opts:)
+    #
+    # @example pass env
+    #
+    #     using Cinnabar::Command::ArrRefin
+    #
+    #     env_hash = {WW: 2}
+    #     status =
+    #        %w[sh -c]
+    #          .push('printf $WW')
+    #          .run_cmd(env_hash)
+    #
+    #     status == true
+    #
+    # @return [Boolean]
+    # @see Cinnabar::Command.run_cmd
+    def run_cmd(env_hash = nil, opts: {}) # rubocop:disable Style/OptionalBooleanParameter
+      Cinnabar::Command.run_cmd(self, env_hash, opts:)
     end
   end
 
   # ---------------------
 
-  # monkey patching: Array#run, Array#run_in_bg
+  # Monkey patching: Array#run, Array#async_run, Array#run_cmd
+  #
+  # @example run
+  #
+  #     include Cinnabar::Command::ArrMixin
+  #
+  #     stdout = %w[printf World].run
+  #     stdout == "World" #=> true
+  #
+  # @example async_run
+  #
+  #     include Cinnabar::Command::ArrMixin
+  #
+  #     fd, waiter = %w[ruby -e].push('sleep 2; puts "OK"').async_run
+  #
+  #     status = waiter.value
+  #     status.success?  #=> true
+  #
+  #     output = fd.read.chomp
+  #     fd.close
+  #     output == 'OK' #=> true
   #
-  # == Example
+  # @example async_run + wait_with_output
   #
   #     include Cinnabar::Command::ArrMixin
+  #     include Cinnabar::Command::TaskArrMixin
   #
-  #     %w[ls -l].run
+  #     task = %w[ruby -e].push('sleep 2; puts "OK"').async_run
   #
-  #     pid = %w[sleep 3].run_in_bg
+  #     output, status = task.wait_with_output
+  #
+  #     status.success?  #=> true
+  #     output.chomp == 'OK' #=> true
+  #
+  # @see ArrExt
   module ArrMixin
-    def self.included(_host) = ::Array.include ArrayExt
+    def self.included(_host) = ::Array.include ArrExt
   end
 
-  # Refinements: Array#run, Array#run_in_bg
+  # Refinements: Array#run, Array#async_run, Array#run_cmd
   #
-  # = Examples
-  #
-  # == Simple
+  # @example run
   #
   #     using Cinnabar::Command::ArrRefin
   #
-  #     %w[ls -l].run
-  #     #=> execute system('ls', '-l')
+  #     stdout =
+  #       %w[ruby -e]
+  #         .push('print 2')
+  #        .run
+  #
+  #     stdout.to_i == 2   #=> true
   #
-  # == Argvise + run_in_bg
+  # @example run(opts:)
   #
   #     using Cinnabar::Command::ArrRefin
+  #
+  #     opts = { allow_failure: true, stdin_data: "Hello" }
+  #
+  #     stdout = %w[wc -m].run(opts:)
+  #
+  #     stdout.to_i == 5   #=> true
+  #
+  # @example Argvise + run_async
+  #
+  #     require 'argvise'
+  #     require 'cinnabar'
+  #
   #     using Argvise::HashRefin
+  #     using Cinnabar::Command::ArrRefin
+  #     using Cinnabar::Command::TaskArrRefin
   #
-  #     pid = {
+  #     task = {
   #       cargo: (),
-  #       run: (),
+  #       b: (),
+  #       r: true,
   #       target: "wasm32-wasip2"
-  #     }.to_argv.run_in_bg
-  #     #=> execute Process.spawn('cargo', 'run', '--target', 'wasm32-wasip2')
+  #     }
+  #       .to_argv
+  #       .run_async
+  #
+  #     stdout, status = task.wait_with_output
+  #     status.success? #=> true
   #
+  # @see ArrExt
   module ArrRefin
     refine ::Array do
-      import_methods ArrayExt
+      import_methods ArrExt
     end
   end
 end
 
 module Cinnabar::Command
-  module IntegerExt
-    def wait_task
-      Cinnabar::Command.wait_task.call(self)
-    end
-  end
-
-  # ---------------------
-
-  # Monkey Patching: Integer#wait_task
+  # The foundation of {TaskArrRefin} and {TaskArrMixin}
+  # @see Cinnabar::Command.wait_with_output
   #
-  # == Example
+  # @example simple
   #
-  #     include Cinnabar::Command::IntMixin
+  #     using Cinnabar::Command::ArrRefin
+  #     using Cinnabar::Command::TaskArrRefin
+  #     # OR: include Cinnabar::Command::TaskArrMixin
+  #
+  #     task = %w[ruby -e]
+  #             .push('sleep 2; puts "OK"')
+  #             .async_run
   #
-  #     pid = %w[sleep 3].run_in_bg
-  #     p "wait 3s"
-  #     pid.wait_task
-  module IntMixin
-    def self.included(_host) = ::Integer.include IntegerExt
+  #     stdout, status = task.wait_with_output
+  #     status.success? #=> true
+  module TaskArrExt
+    def wait_with_output
+      Cinnabar::Command.wait_with_output(*self)
+    end
   end
 
-  # Refinement: Integer#wait_task
-  #
-  # == Example
-  #
-  #     using Cinnabar::Command::IntRefin
-  #
-  #     pid = %w[sleep 3].run_in_bg
-  #     p "wait 3s"
-  #     pid.wait_task
-  module IntRefin
-    refine ::Integer do
-      import_methods IntegerExt
+  # Refinement: Array#wait_with_output
+  # @see TaskArrExt
+  module TaskArrRefin
+    refine ::Array do
+      import_methods TaskArrExt
     end
   end
+
+  # Monkey Patching: Array#wait_with_output
+  # @see TaskArrExt
+  module TaskArrMixin
+    def self.included(_host) = ::Array.include TaskArrExt
+  end
 end

data/lib/cinnabar/net.rb

@@ -5,19 +5,33 @@ module Cinnabar::Downloader
 
   require 'open-uri'
 
-  # == Example
+  DEFAULT_DL_OPTS = {
+    out_dir: 'tmp', file_name: nil,
+  }.freeze
+
+  # @example
   #
   #     url = 'https://docs.ruby-lang.org/en/3.4/OpenURI.html'
   #     opts = { out_dir: "tmp", file_name: "doc.html" }
   #     DL = Cinnabar::Downloader
   #     DL.download(url, opts)
   #
-  # == Params
+  # @param url [String] e.g., **https://url.local**
+  #
+  # @param opts [Hash] Options for customizing the download behavior.
+  #   e.g., `{out_dir: 'download', file_name: nil, headers: {'User-Agent' => "aria2/1.37.0"}}`
   #
-  # - url: [String] e.g., https://url.local
-  # - opts: [Hash] e.g., `{out_dir: 'download', file_name: nil, headers: {'User-Agent' => "aria2/1.37.0"}}`
-  def download(url, opts)
+  # @option opts [String] :out_dir
+  #   Directory where the downloaded file will be saved.
+  # @option opts [String, nil] :file_name
+  #   Name of the output file. If nil, it will be inferred from the URL.
+  # @option opts [Hash{String => String}] :headers
+  #   Optional HTTP headers to include in the request.
+  # @return [Integer]
+  def download(url, opts = {})
+    opts = DEFAULT_DL_OPTS.merge(opts)
     out_dir, file_name, headers = opts.values_at(:out_dir, :file_name, :headers)
+    out_dir = '.' if out_dir.nil?
 
     headers = build_headers(headers)
     parsed_url = Kernel.URI(url)
@@ -30,7 +44,7 @@ module Cinnabar::Downloader
       .then { IO.copy_stream(_1, file_path.to_s) }
   end
 
-  # => ::Hash
+  # @return [Hash]
   def build_headers(headers)
     base_headers = {
       'User-Agent' => 'Mozilla/5.0 (Linux; aarch64 Wayland; rv:138.0) Gecko/20100101 Firefox/138.0',
@@ -38,7 +52,7 @@ module Cinnabar::Downloader
     base_headers.merge(headers || {}).transform_keys(&:to_s)
   end
 
-  # => ::String
+  # @return [String]
   def determine_filename(file_name, parsed_url)
     filename = file_name || File.basename(parsed_url.path || '')
     case filename.strip
@@ -47,7 +61,7 @@ module Cinnabar::Downloader
     end
   end
 
-  # => Kernel.Pathname
+  # @return [Pathname]
   def setup_file_path(out_dir, file_name)
     Kernel.Pathname(out_dir)
       .tap(&:mkpath)
@@ -56,37 +70,53 @@ module Cinnabar::Downloader
 end
 
 module Cinnabar::Downloader
-  module StringExt
-    def download(out_dir: 'tmp', file_name: nil, headers: {})
-      Cinnabar::Downloader.download(self, { out_dir:, file_name:, headers: })
+  # The foundation of {StrRefin} and {StrMixin}
+  module StrExt
+    # @see Cinnabar::Downloader.download
+    #
+    # @param opts [Hash] Options for customizing the download behavior.
+    #   e.g., `{out_dir: 'download', file_name: nil, headers: {'User-Agent' => "aria2/1.37.0"}}`
+    #
+    # @option opts [String] :out_dir
+    # @option opts [String, nil] :file_name
+    # @option opts [Hash{String => String}] :headers
+    # @return [Integer]
+    def download(opts = {})
+      Cinnabar::Downloader.download(self, opts)
     end
   end
 
   # -------------
 
-  # = Example
+  # @example
   #
   #     include Cinnabar::Downloader::StrMixin
   #
-  #     url = 'https://docs.ruby-lang.org'
+  #     url = 'https://docs.ruby-lang.org/en/master'
   #
   #     url.download
-  #     # OR: url.download(out_dir: "tmp", file_name: "custom.html")
+  #     # OR: url.download({out_dir: "tmp", file_name: "custom.html"})
+  #
+  # @see Cinnabar::Downloader.download
+  # @see StrExt
   module StrMixin
-    def self.included(_host) = ::String.include StringExt
+    def self.included(_host) = ::String.include StrExt
   end
 
-  # = Example
+  # @example
   #
   #     using Cinnabar::Downloader::StrRefin
   #
-  #     url = 'https://docs.ruby-lang.org/en/master/OpenURI.html'
+  #     url = 'https://docs.ruby-lang.org/en/master'
   #
   #     url.download
-  #     # OR: url.download(out_dir: "/tmp", file_name: "index.html")
+  #     # OR: url.download({out_dir: "/tmp", file_name: "index.html"})
+  #
+  # @see Cinnabar::Downloader.download
+  # @see StrExt
   module StrRefin
     refine ::String do
-      import_methods StringExt
+      import_methods StrExt
     end
   end
 end

data/lib/cinnabar/pipe.rb

@@ -17,7 +17,7 @@ module Cinnabar::FnPipe
 end
 
 module Cinnabar::FnPipe
-  module ObjectExt
+  module Ext
     def ▷(other) # rubocop:disable Naming/MethodName
       Cinnabar::FnPipe.▷(self, other)
     end
@@ -29,7 +29,7 @@ module Cinnabar::FnPipe
   #
   # Monkey Patching: Object#▷
   #
-  # = Example
+  # @example
   #
   #     include Cinnabar::FnPipe::Mixin
   #
@@ -40,14 +40,14 @@ module Cinnabar::FnPipe
   #     2.▷ :puts
   #         #=> 2
   module Mixin
-    def self.included(_host) = ::Object.include ObjectExt
+    def self.included(_host) = ::Object.include Ext
   end
 
   # Function Pipe
   #
   # Refinement: Object#▷
   #
-  # = Example
+  # @example
   #
   #     using Cinnabar::FnPipe::Refin
   #
@@ -63,7 +63,7 @@ module Cinnabar::FnPipe
   #
   module Refin
     refine ::Object do
-      import_methods ObjectExt
+      import_methods Ext
     end
   end
 end

data/lib/cinnabar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Cinnabar
-  VERSION = '0.0.0'
+  VERSION = '0.0.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cinnabar
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.0.1
 platform: ruby
 authors:
 - 2moe
@@ -29,6 +29,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".rubocop.yml"
+- ".yardopts"
 - License
 - docs/Readme-zh.md
 - docs/Readme.md