Search and process text

Applies to: Rubian 4.0.2

Updated September 16, 2026

Rubian's text commands return strings, arrays or match records that can be used in another Ruby expression. This guide covers the Rubian interfaces; they do not accept every flag or expression from their similarly named Unix utilities.

Find a name or search contents#

find(pattern, path: '/', quiet: false) looks for a substring in available names and paths. It can use the session's discovered inventory. It is not a complete, fresh recursive search of a filesystem, and path is not a strict boundary for every fallback lookup. Use discovery and refresh when an expected file is absent.

grep searches the contents of host files:

matches = grep('timeout', '/path/to/application.log', fixed: true, quiet: true)
matches.each do |match|
  puts "#{match[:line_num]}: #{match[:content]}"
end

The result is an array of records containing :file, :line_num and :content. No matches produces an empty array. A missing file or invalid pattern also needs its diagnostic inspected; an empty result alone does not establish that every input was searched.

Parameter	Behavior
`pattern`	String or regular expression. A string is interpreted as a regular expression unless `fixed: true`.
`*files`	One or more host files. Without them, searches the session's indexed user files; specify files to bound the work.
`fixed: false`	Use `true` for literal text.
`ignore_case: true`	String patterns ignore case by default. A supplied Ruby regular expression uses its own options.
`quiet: false`	Suppresses normal display when `true`; returned match records remain available.

Select and transform lines#

rows = ["alpha,ready", "beta,waiting", "alpha,ready"]
names = cut(1, ',', rows, quiet: true)
unique_names = uniq(names, quiet: true)
ordered_names = sort(unique_names, false, quiet: true)
puts ordered_names.join("\n")

The expected output is alpha followed by beta, each on its own line. The example uses an array, so it needs no files or connected services.

Command	Input and return	Important behavior
`head(input, lines = 10, quiet: false)`	Host file, multiline string or array; returns selected lines as an array.	Selects the beginning.
`tail(input, lines = 10, quiet: false)`	The same input forms; returns selected lines.	Selects the end; does not follow later writes.
`cut(field, delimiter = "\t", *files, quiet: false)`	Host files, multiline text or arrays; returns an array.	Fields start at 1; selections can include lists or ranges. A line without the delimiter passes through.
`sort(input, reverse = false, quiet: false)`	Host file, multiline text or array; returns an array.	Lexical ordering. Pass `true` as the second argument for descending order.
`uniq(input, quiet: false)`	Host file, multiline text or array; returns an array.	Removes repeated lines throughout the input and retains the first occurrence.
`tr(set1, set2, input, quiet: false)`	Text or supported file input; returns a string.	Character translation, including basic ranges such as `a-z`.
`wc(*files, quiet: false)`	Host files or inline text; returns count records.	Records contain `:file`, `:lines`, `:words`, `:chars`. Characters are not byte counts.

For Rubian-managed text, read it first with cat, check the result, and pass its lines to the appropriate array-based command. A string without a newline can be interpreted as a filename by several commands. Use an array for an unambiguous single line.

Limited awk and sed expressions#

awk(pattern, *files, quiet: false) supports a small set of expressions: a regular-expression filter, NF > 0, {print $1}, {print $NF}, {print NR, $0} and {print}. It returns an array of output lines. Do not supply a general awk program: an unsupported expression can pass input through without performing the intended transformation.

sed('s/pattern/replacement/g', '/path/to/file.txt') returns and displays transformed host-file content. Add '-i' as the first argument to replace that host file. The supported flags are g and i; without g, substitution changes the first match in the entire file. It does not mean the first match on each line.

Inspect the returned text before choosing an in-place edit. For a transformation beyond these supported forms, use ordinary Ruby string and array operations in the command language.

Passing results to a host program#

xargs(inputs, command) invokes one host program with the inputs as arguments. It does not call a Rubian method or implement the full Unix xargs option set. For another Rubian command, pass the returned value directly in Ruby. See Shell tools when you intentionally need host-program behavior.