ara [options] query

In batch mode, ara takes one or more queries as arguments, read the database files according to its configuration, and outputs the results to stdout.

ara [options] -i

With the -i or -interactive options, ara reads the database files and then prompts the user for queries or commands. The results are displayed (with the help of a pager such as more or less if necessary), and ara prompts the user again. Interactive mode is strongly recommended, since loading the package databases can be long, but once loaded, queries run quite fast. This is a major advantage of ara over tools such as dpkg-iasearch or dpkg-dctrl.

For key bindings see KEY BINDINGS.

A graphical interface, xara(1), is provided by the Debian package xara-gtk.

See the EXAMPLES section for a quick introduction ; xara has some built-in help. The syntax is described in detail below.

A query is a boolean combination of atomic expressions. An atomic expression selects a subset of the set D of descriptions. I call this set the meaning of the expression; if e denotes an atomic expression, its meaning is denoted by [e]. The meaning of a boolean combination of atomic expressions is just the boolean combination of the meaning of its constituents. In other words, if e1 and e2 are atomic expressions, then e1 & e2 is a query, whose meaning is the intersection of the meanings of e1 and e2; and the meaning of e1 | e2 is the union of the meanings of e1 and e2.

Atomic expressions can be of the forms pattern, /regexp/, quoted_string, fieldspec operator1 string, or fieldspec operator2 regexp.

e1 & e2 (also e1 AND e2, e1 and e2)

This is logical conjunction (set intersection). Returns the intersection of [e1] and [e2], i.e. packages satisfying both e1 and e2.

e1 | e2 (also e1 OR e2, e1 or e2)

This is logical disjunction (set union). Union of [e1] and [e2], i.e. packages satisfying e1, e2 or both.

!e1 (also NOT e1, not e1)

This is logical negation (set complementation). Complement of [e1], i.e. packages not satisfying e1.

Please note that ~ stands for the current default field specifier and is not an alias for the complementation operator.

true (also all)

The set of all descriptions, i.e. all packages.

false (also none) The empty set, i.e. no packages.

A field specifier fieldspec is a comma-separated list of field patterns.

Field patterns are like simple shell patterns and they may contain star characters (which stand for anything) or question marks (which stand for any single character). They are case-insensitive. They specify a set of fields.

For example description and Description specify the set of fields { Description }, whereas de* specifies { Description, Depends }.

The special specifier ~ denotes the current default specifier (see below).

The need to repeat the field specifier can make the above syntax cumbersome. That is why there is a current field specifier. The current field specified is, by default, Description,Package. Simplified atomic expressions are simply words or simplified shell expressions (which do not need to be enclosed in double quotes) and they are searched in fields in the current field specifier. They can be made of letters, digits, underscores, dashes and periods. They may contain stars of question marks which are interpreted as for field patterns (i.e., as simplified shell expressions). If double quotes are used, other characters and spaces can be used.

The default field specifier in a query query can be changed to fieldspec by simply prefixing the query with fieldspec:. This gives fieldspec:query. However if query is complex (i.e., contains binary boolean operators) you need to enclose query in parentheses, as in fieldspec:(query1 or query2).

String literals can be given with or without double quotes; without double quotes, the syntax is as for C identifiers, except that you can use dashes, you must start with a latin letter ([a-zA-Z]) and you can continue with Latin letters, decimal digits or underscore ([a-zA-Z0-9_]). Inside double quotes, all characters are allowed, except double quotes, which must be preceded by a backslash.

Results of queries can be stored in variables, which may be recalled later. This isn't very useful in batch mode but is useful in interactive and graphical modes.

Variable names start with a dollar and follow usual conventions for variables, i.e., they can be any mix of alphanumeric characters and symbols such as underscore, dash, etc.

Variable names are case-sensitive so that $Installed and $installed are different.

To assign the result of a query (which is a set of packages) a variable named $variable just execute the query $variable := query. You may then recall this particular set by simply writing $variable.

Example: $installed := status:(installed & !not-installed)

Hierarchical comparison operators can be negated by changing the direction of the angle brackets and adding or removing an equality sign at end (<= becomes >). Other operators are negated as follows: = becomes != and =~ becomes !~.

fieldspec=string Atomic expression selecting packages having a field in fieldspec having a value a value exactly equal to string.

fieldspec<string (fieldspec<=string, fieldspec>string, fieldspec>=string) Atomic expression selecting packages having a field in fieldspec whose value is strictly less than string. The order used is the Debian versioning order. This order is compatible with the natural order on integers and with Debian version numbers. When comparing strings not containing special characters, letters sort before numbers, as opposed to lexicographic ASCII order we are used to. This means that hexadecimal numbers (such as MD5 sums) will not have their usual order.

Note that string must be on the right side of the operator (i.e., you cannot write 1000 < Size).

fieldspec=~/expression/ (also fieldspec:/expression/)

Selects descriptions whose field named fieldspec exists and whose value matches, case-sensitively, the regular expression expression.

fieldspec=~/expression/i (also fieldspec:/expression/i) Same as above, but the regular expression is case-insensitive.

fieldspec=~/expression/w (also fieldspec:/expression/w) Same as above, but the regular expression is case-sensitive and matches only at word boundaries. Note that letters-to-digit or digit-to-letter transitions are considered to be word boundaries.

fieldspec=~/expression/iw (also fieldspec:/expression/iw) The regular expression here is case-insensitive and matched at word boundaries.

Regular expressions are given between a pair of slashes; the last slash can be followed by a commutative sequence of letters denoting flags. Regular expression syntax is sed-like: grouping parentheses and alternation must be backslashed. For more details, see the Objective Caml manual chapter on the Str module. In short (x,x1,x2 are meta-symbols denoting regular expressions):

/./ Any character.

/toto/ Literal string toto.

/x1x2/ Concatenation.

/x1\|x2/ Alternation.

\(x1\)* Star closure.

[c-d] Character range.

\b Word boundaries.

/x/i Case insensitive.

/x/w At word boundaries.

Most queries will contain an appreciable amount of shell metacharacters. For example, logical disjunction is denoted by the pipe character, which is used by all known shells. The problem is aggravated by the fact that names of real commands are likely to appear in the used expressions; successfully setting up a UNIX pipeline by error is therefore plausible.

When calling ara from the command line in batch mode, You are strongly urged to protect your queries by surrounding them with simple quotes; never write something like ara Pack*=~/halt|reboot|shutdown/ as this will very likely reboot your system (and is incorrect regular expression syntax, if halt or reboot or shutdown is meant: pipes must be backslashed). Instead, one should write ara 'Pack*=~/halt\|reboot\|shutdown /'

-interactive, -i

Interactive mode ; prompt for a query, display it.

-config <path> (also for xara)

Set configuration file name (default $HOME/.ara/ara.config).

-noconfig

Dont attempt to create a configuration file.

-nohistory

Dont save command history

-help (also for xara)

Display some help

-about Display copyright, thanks and dedication.

-version, -about (also for xara)

Print author, license, version and dedication (and exit if called from CLI).

-examples

Display some documentation including examples exit.

-q <query>

Query (e.g., depends:xlibs & !package:xcalc).

-query <query>

Ditto.

-progress (-noprogress)

Show or dont show progress indicator when loading database.

-lines <height>

Set height of terminal for interactive display. By default this is taken from the environment variable LINES or as 25 if it is undefined.

-columns <width>

Set width of terminal for interactive display. By default this is taken from the environment variable COLUMNS or as 25 if it is undefined.

-pager (-nopager)

Use (or dont use) a pager displaying long output in interactive mode. The pager command is defined in the configuration file $HOME/.ara/ara.config. By default this is /etc/alternatives/pager. The pager is only used when the output size exceeds the terminal height.

-debug (also for xara)

Enable debugging information

-debug-level (also for xara)

Set debugging level (higher is more verbose, max is 100, default is 10)

-new Show only newest version of each package.

-old

List all versions of packages.

-short <query>

Display names of packages satisfying query (and their version if -old is set), with multiple packages per line.

-list <query>

Same, but display one package name per line, and no curly braces (default).

-raw <query>

For each package satisfying the query, display all selected fields.

-table <query>

Display results as a table.

-noborders

Dont draw ASCII borders for tabular output.

-borders

Draw ASCII borders for tabular output.

-count <query>

Display number of matching packages.

-fields <field_1[:width_1],...>

Limit output to specified fields. The optional width specifiers are used with the -table option and ignored otherwise. Use * to display all fields (but remember to escape the star character from your shell).

-ast

Dump the abstract syntax tree of parsed queries to stderr.