Command language and results

Rubian commands can be called as Ruby methods. Arguments, blocks, variables and ordinary Ruby expressions let you compose a repeatable operation without reconstructing its data from terminal formatting.

Calling a command#

Parentheses make argument boundaries explicit and are recommended in scripts:

ls('/path/to/workspace')
cat('/path/to/example.txt', quiet: true)

Strings contain paths or text. Keyword arguments such as quiet: true select documented behavior. A keyword supported by one command is not necessarily supported by another. Conventional shell flags, pipes, wildcard expansion and redirection are not interchangeable with this syntax.

Returned values and terminal output#

The display is intended for a person reading the terminal; the return value is intended for the next expression. ls returns entry names, cat returns text, and a background-job command returns a job identifier. Do not assume every command returns the text it prints.

names = ls
ruby_files = names ? names.select { |name| name.end_with?('.rb') } : []
puts ruby_files.join("\n")

This example selects names by their suffix. It does not open or execute the files. The empty-array fallback also makes the result usable if the directory lookup fails.

For text processing, first confirm that a read succeeded:

body = cat('/path/to/example.log', quiet: true)
if body
  matching_lines = body.lines.select { |line| line.include?('example') }
  puts matching_lines.join
end

Reusing an operation#

A small method can express a routine in terms of supported commands. Give its inputs explicit names and decide how it should respond to a failed read.

def matching_lines(path, phrase)
  body = cat(path, quiet: true)
  return [] unless body
  body.lines.select { |line| line.include?(phrase) }
end

This method returns an array and leaves display to the caller. It is an example of user-authored shell code, not an extension that changes the installed product.

Errors and side effects#

A syntax error means the expression could not be parsed. An unknown method can indicate a misspelling or a command absent from the supplied build. An operation that returns no result may also have printed a more useful diagnostic; retain both when investigating it.

Before composing commands that change state, run the smallest read-only part and inspect its result. Use the documented cancellation or recovery procedure for the specific operation. Closing a terminal is not a reliable way to undo work that has already changed files or services.

The files reference and job reference describe the return values and failure cases used in the examples above.