Module Boson::Pipe

This module passes an original command’s return value through methods/commands specified as pipe options. Pipe options are processed in this order:

• A :query option searches an array of objects or hashes using Pipes.query_pipe.
• A :sort option sorts an array of objects or hashes using Pipes.sort_pipe.
• A :reverse_sort pipe option reverses an array.
• A :pipes option takes an array of commands that modify the return value using Pipes.pipes_pipe.
• All user-defined pipe options (:pipe_options key in Repo.config) are processed in random order.

Some points:

• User-defined pipes call a command (the option’s name by default). It’s the user’s responsibility to have this command loaded when used. The easiest way to do this is by adding the pipe command’s library to :defaults in main config.
• By default, pipe commands do not modify the value their given. This means you can activate multiple pipes using a method’s original return value.
• A pipe command expects a command’s return value as its first argument. If the pipe option takes an argument, it’s passed on as a second argument.
• When piping occurs in relation to rendering depends on the Hirb view. With the default Hirb view, piping occurs occurs in the middle of the rendering, after Hirb has converted the return value into an array of hashes. If using a custom Hirb view, piping occurs before rendering.
• What the pipe command should expect as a return value depends on the type of command. If it’s a command rendered with hirb’s tables, the return value is a an array of hashes. For everything else, it’s the method’s original return value.

User Pipes

User pipes have the following attributes which alter their behavior:

:pipe

Pipe command the pipe executes when called. Default is the pipe’s name.

:env

Boolean which enables passing an additional hash to the pipe command. This hash contains information from the first command’s input with the following keys: :args (command’s arguments), :options (command’s options), :global_options (command’s global options) and :config (a command’s configuration hash). Default is false.

:filter

Boolean which has the pipe command modify the original command’s output with the value it returns. Default is false.

:no_render

Boolean to turn off auto-rendering of the original command’s final output. Only applicable to :filter enabled pipes. Default is false.

:solo

Boolean to indicate this pipe can’t run with other user pipes or pipes from :pipes option. If a user calls multiple solo pipes, only the first one detected is called.

User Pipes Example

Let’s say you want to have two commands, browser and copy, you want to make available as pipe options:

# Opens url in browser. This command already ships with Boson.
def browser(url)
  system('open', url)
end

# Copy to clipboard
def copy(str)
  IO.popen('pbcopy', 'w+') {|clipboard| clipboard.write(str)}
end

To configure them, drop the following config in ~/.boson/config/boson.yml:

:pipe_options:
  :browser:
    :type: :boolean
    :desc: Open in browser
  :copy:
    :type: :boolean
    :desc: Copy to clipboard

Now for any command that returns a url string, these pipe options can be turned on to execute the url.

Some examples of these options using commands from my libraries:

# Creates a gist and then opens url in browser and copies it.
$ cat some_file | boson gist -bC        # or cat some_file | boson gist --browser --copy

# Generates rdoc in current directory and then opens it in browser
irb>> rdoc '-b'    # or rdoc '--browser'

Methods

public instance

1. add_pipes
2. process_pipes
3. scientist_process