Provided by: ara_1.0.31build2_amd64 bug

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 ara 'Pack*=~/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

       ara 'Section=utils'
              List the name of every package in section utils.

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

       ara -list 'Section=utils and Status:(installed & !not-installed)'
              List all installed packages in section utils.

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

       ara -short 'section=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 \
                  -short 'section=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 \
                  -table 'Section=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                                  ARA(1)