Man Linux: Main Page and Category List

NAME

       ara  -  a  utility  for  doing boolean regexp queries on the the Debian
       package database

SYNOPSIS

   Batch mode:
       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.

   Interactive mode:
       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.

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

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

DESCRIPTION

       ara and xara allow the user  to  search  the  Debian  software  package
       database  (which  includes  installed  and  uninstalled packages) using
       powerful queries made of boolean combinations  of  regular  expressions
       acting on fields given by patterns.

       For  example, the query section=utils & depends:(gtk or tk8 or xlibs or
       kde or gnome or qt) & debian & package will  display  packages  in  the
       section  utils  that  have graphical interfaces (because they depend on
       graphical toolkits or X11 libraries), and  whose  description  contains
       the words debian and package.

RATIONALE

       Debian  users  can easily install software with the commands dselect or
       apt-get install.  They can choose (on Debian 3.1  unstable)  from  over
       30,000  packages.   Finding  the  right package can be quite difficult.
       Although packages are categorized in crude sections,  there  are  still
       too  many packages and reading all descriptions is out of the question.

       The database files are huge and their mail-like syntax makes them  hard
       to  search  with  line-oriented  tools like grep.  There exist commands
       such as dpkg-iasearch(1) or dpkg-dctrl(1) but  their  capabilities  are
       limited.   Graphical  package  management  tools  such  as  aptitude or
       synaptic have search  capabilities.   Although  ara  can  call  apt  to
       install  or  remove  packages,  its  orientation  is that of a powerful
       search tool.  Indeed, the name ara comes from the  imperative  form  of
       the Turkish verb aramak which means "to search".

THE DEBIAN PACKAGE DATABASE

       The   database   of   Debian   packages   is   a   huge  text  file  at
       /var/lib/dpkg/available  (or  a  collection   of   text   files   under
       /var/lib/apt/lists/).   These files are in a mailbox-like format, and a
       typical entry looks like this:

       Priority: required
       Section: base
       Installed-Size: 460
       Origin: debian
       Maintainer: Dpkg Development <debian-dpkg@lists.debian.org>
       Bugs: debbugs://bugs.debian.org
       Architecture: i386
       Source: dpkg
       Version: 1.10.24
       Replaces: dpkg (<< 1.10.3)
       Depends: libc6 (>= 2.3.2.ds1-4), ....
       Filename: pool/main/d/dpkg/dselect_1.10.24_i386.deb
       Size: 119586
       MD5sum: c740f7f68dab08badf4f60b51a33500a
       Description: a user tool to manage Debian packages
        dselect is the primary user interface for installing, removing and
        managing Debian packages. It is a front-end to dpkg.

       Each package is thus described by a set of fields (like Package, Description, Version...).

QUERY SYNTAX AND SEMANTICS

       Here we describe the query syntax in some detail.  As of  version  1.0,
       ara  introduces  new,  simplified syntax which is quite traditional and
       should be familiar to anyone having used search engines.  Search  terms
       are  simply  combined with AND, OR and NOT boolean operators.  Having a
       look at the EXAMPLES section at the end of this manual  should  provide
       you a starting point.

       Consider the set D of Debian package descriptions contained in the file
       /var/lib/dpkg/available (or in files under /var/lib/apt/lists/).   Each
       description  is  a  set  of couples of the form (f,v) where f and v are
       strings: f is the name of  the  field  (namely,  Package,  Description,
       Filename,  Depends,  etc.);  v is its value.  Thus D is a set of set of
       couples, forming the universe.  Queries select subsets of the  universe
       D.   Output  options  select  which  fields of the selected part of the
       universe to display, and how to display them.

   Queries
       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
       Atomic  expressions  can   be   of   the   forms   pattern,   /regexp/,
       quoted_string,  fieldspec  operator1  string,  or  fieldspec  operator2
       regexp.

   Boolean operators and constants
       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.

   Field specifiers
       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).

   Current fields specifiers and simplified atomic expressions
       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
       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.

   Variables
       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)

   Operators
       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
       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.

   Remark
       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     araPack*=~/halt\|reboot\|shutdown /

OPTIONS

   Operation
       -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 options
       -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.

   Options pertaining to the terminal
       -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)

   Display styles
       -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.

EXAMPLES

       araSection=utils’
              List the name of every package in section utils.

       araSection=utils and !Depends:(gnome|kde|gtk)’
               ...  except  those  whose  dependency  field matches the regexp
              gnome\|kde\|gtk

       ara -listSection=utils and Status:(installed & !not-installed)’
              List all installed packages in section utils.

       ara   -shortsection=utils    and    !depends:(gtk|gnome|kde)    and
       priority=optional’
               ... list multiple  names  per  line,  and  show  only  optional
              packages.

       ara  -shortsection=utils & (!depends:(gtk|gnome|kde) | size<100000) &
       priority=optional’
              Well,  exclude  gtk,gnome  or  kde stuff only if 100000 bytes or
              greater.

       ara -noborders -fields Package,Size,Maintainer:20 -table \
                  -shortsection=utils & (!depends:(gtk|gnome|kde) | size<100000) & priority=optional’

        ... show Package, Size and Maintainer fields from the above results as
       a nice ascii table, limiting the maintainer field to 20 characters, but
       without crude ASCII borders.

       ara -old -fields Package:8,Size,Description:100 \
                  -tableSection=games and not (Depends:(gtk|sdl|kde|opengl|gnome|qt)
                  or /shoot\|kill\|destroy\|blast\|race\|bomb/iw
                  or /multi\(-\|\)player\|strategy\|conquest\|3\(-\|\)d/iw)
                  and Depends:(xlibs or vga)
                  and Size <= 1000000’

       Assuming a 125-column display, display the first  eight  characters  of
       the  package  name, the size in bytes, and the first hundred characters
       of the (first line) of the description of all  packages  in  the  games
       section  whose  size does not exceeding one million bytes, and which do
       not depend on fancy stuff like GTK, SDL, KDE, OpenGL, Qt or  Gnome,  do
       not  mention  some form of violence (to shoot, to kill, etc.)  in their
       description, are not described as multi-player, strategy,  conquest  or
       three-dimensional,  and  yet  depend on either xlibs or svga to exclude
       console-based games.

SPEED

       ara reads the whole database into memory and  then  processes  queries.
       Since  the  database  is  usually  big,  this takes some time. However,
       queries then run quite fast. So specify multiple  queries  or  use  the
       -interactive option to amortize the cost of reading the database.

LICENSE

       ara is released under the GNU General Public License, version 2, a copy
       of which is included in the source distribution.

THANKS

       Many thanks to George Danchev, Thomas Schoepf and Sven Luther for doing
       the Debian packaging of ara and many helpful comments.

CONFIGURATION FILES

       The  system-wide  configuration  file  for ara is /etc/ara.config.  Its
       syntax is self-evident and follows the Ocaml lexical conventions.

       Values in the user-specific  configuration  file  $HOME/.ara/ara.config
       override those of /etc/ara.config.

OTHER FILES

       Command line history is saved in $HOME/.ara/ara.history.

       The following databases are loaded by default:

       /var/lib/dpkg/available
       /var/lib/dpkg/status
       /var/lib/apt/lists/*_Packages
       /var/lib/apt/lists/*_Sources

ENVIRONMENT VARIABLES

       In  ara  the  variables  LINES  and  COLUMNS  are used to determine the
       dimensions of the terminal.  Note that these variables are not exported
       by  default  in your shell ; add export LINES COLUMNS in your .zshrc or
       .bashrc.

SEE ALSO

       xara(1),    apt-cache(8),     aptitude(8),     dpkg(8),     dselect(8),
       grep-aptavail(1),   grep-available(1),  grep-dctrl(1),  grep-status(1),
       grep-dctrl(1), packagesearch(1), synaptic(1).

AUTHOR

       Oguz           Berke           Durak            <berke-dev@ouvaton.org>
       http://abaababa.ouvaton.org/ara/

KNOWN BUGS

       Due  to  lack of Unicode support, non-ASCII characters lead to problems
       under Unicode terminals.  Note that the database files are  encoded  in
       Latin1.

                               November 1, 2004