     [file version.texi not included]

     START-INFO-DIR-ENTRY
     * ID database: (id).		Identifier database utilities.
     * aid: (id)aid invocation::			Matching strings.
     * eid: (id)eid invocation::			Invoking an editor on matches.
     * fid: (id)fid invocation::			Listing a file's identifiers.
     * gid: (id)gid invocation::			Listing all matching lines.
     * idx: (id)idx invocation::			Testing mkid scanners.
     * iid: (id)iid invocation::			Interactive complex queries.
     * lid: (id)lid invocation::			Matching patterns.
     * mkid: (id)mkid invocation::			Creating an ID database.
     * pid: (id)pid invocation::			Looking up filenames.
     END-INFO-DIR-ENTRY

This file documents the mkid identifier database utilities.

Copyright (C) 1991, 1995 Tom Horsley.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation.

ID database utilities
*********************

This manual documents version VERSION of the ID database utilities.

Introduction
************

An ID database is a binary file containing a list of filenames, a list of identifiers, and a matrix indicating which identifiers appear in which files.  With this database and some tools to manipulate it (described in this manual), a host of tasks become simpler and faster. For example, you can list all files containing a particular #include throughout a huge source hierarchy, search for all the memos containing references to a project, or automatically invoke an editor on all files containing references to some function.  Anyone with a large software project to maintain, or a large set of text files to organize, can benefit from an ID database.

Although the ID utilities are most commonly used with identifiers, numeric constants are also stored in the database, and can be searched for in the same way (independent of radix, if desired).

There are a number of programs in the ID family:

mkid
     scans files for identifiers and numeric constants and builds the ID database file.

gid
     lists all lines that match given patterns.

lid
     lists the filenames containing identifiers that match given patterns.

aid
     lists the filenames containing identifiers that contain given strings, independent of case.

eid
     invokes an editor on each file containing identifiers that match given patterns.

fid
     lists all identifiers recorded in the database for given files, or identifiers common to two files.

pid
     matches the filenames in the database, rather than the identifiers.

iid
     interactively supports more complex queries, such as intersection and union.

idx
     helps with testing of new mkid scanners.

Please report bugs to gkm@magilla.cichlid.com.  Remember to include the version number, machine architecture, input files, and any other information needed to reproduce the bug: your input, what you expected, what you got, and why it is wrong.  Diffs are welcome, but please include a description of the problem as well, since this is sometimes difficult to infer.  See Bugs (GNU CC).

Past and future
===============

Greg McGary conceived of the ideas behind mkid when he began hacking the Unix kernel in 1984.  He needed a navigation tool to help him find his way the expansive, unfamiliar landscape.  The first mkid-like tools were shell scripts, and produced an ASCII database that looks much like the output of lid with no arguments.  It took over an hour on a VAX 11/750 to build a database for a 4.1BSD-ish kernel.  Lookups were done with the system utility look, modified to handle very long lines.

In 1986, Greg rewrote mkid, lid, fid and idx in C to improve performance.  Database-build times were shortened by an order of magnitude.  The mkid tools were first posted to comp.sources.unix in September 1987.

Over the next few years, several versions diverged from the original source.  Tom Horsley at Harris Computer Systems Division stepped forward to take over maintenance and integrated some of the fixes from divergent versions.  He also wrote the iid program.  A first release of mkid version 2 was posted to alt.sources near the end of 1990.  At that time, Tom wrote this Texinfo manual with the encouragement the net community.  (Tom especially thanks Doug Scofield and Bill Leonard whom he dragooned into helping poorfraed and edit---they found several problems in the initial version.)  Karl Berry revamped the manual for Texinfo style, indexing, and organization in 1995.

In January 1995, Greg McGary reemerged as the primary maintaner and launched development of mkid version 3, whose primary new feature is an efficient algorithm for building databases that is linear in both time and space over the size of the input text.  (The old algorithm was quadratic in space and therefore choked on very large source trees.) The code is released under the GNU Public License, and might become a part of the GNU system.  mkid 3 is an interim release, since several significant enhancements are still in the works: an optional coupling with GNU grep, so that grep can use an ID database for hints; a cscope work-alike query interface; incremental update of the ID database; and an automatic file-tree walker so you need not explicitly supply every filename argument to the mkid program.

mkid: Creating ID databases
***************************

The mkid program builds an ID database.  To do this, it must scan each file you tell it to include in the database.  This takes some time, but once the work is done the query programs run very rapidly.  (You can run mkid as a cron job to regularly update your databases.)

The mkid program knows how to extract identifiers from various types of files.  For example, it can recognize and skip over comments and string constants in a C program.

Identifiers are not the only thing included in the database.  Numbers are also recognized and included in the database indexed by their binary value.  This feature allows you to find uses of constants without regard to the radix used to specify them, since the same number can frequently be written in many different ways (for instance, 47, 0x2f, 057 in C).

All the places in this document which mention identifiers should really mention both identifiers and numbers, but that gets fairly clumsy after a while, so you just need to keep in mind that numbers are included in the database as well as identifiers.

The ID files that mkid creates are architecture- and byte-order-independent; you can share them at will across systems.

mkid options
============

By default, mkid scans the files you specify and writes the database to a file named ID in the current directory.

     mkid [-v] [-SSCANARG] [-aARGFILE] [-] [-fIDFILE]
     FILES...

The program accepts the following options.

-v
     Verbose.  mkid tells you as it scans each file and indicates which scanner it is using.  It also summarizes some statistics about the database at the end.

-SSCANARG
     Specify options regarding mkid's scanners.  See Scanner option formats.

-aARGFILE
     Read additional command line arguments from ARGFILE.  This is typically used to specify lists of filenames longer than will fit on a command line; some systems have severe limitations on the total length of a command line.

-
     Read additional command line arguments from standard input.

-fIDFILE
     Write the database to the file IDFILE, instead of ID.  The database stores filenames relative to the directory containing the database, so if you move the database to a different directory after creating it, you may have trouble finding files.

The remaining arguments FILES are the files to be scanned and included in the database.  If no files are given at all (either on command line or via -a or -), mkid does nothing.

Scanners
========

To determine which identifiers to extract from a file and store in the database, mkid calls a scanner; we say a scanner recognizes a particular language.  Scanners for several languages are built-in to mkid; you can add your own scanners as well, as explained in the sections below.

mkid determines which scanner to use for a particular file by looking at the suffix of the filename.  This suffix is everything after and including the last . in a filename; for example, the suffix of foo.c is .c.  mkid has a built-in list of bindings from some suffixes to corresponding scanners; for example, .c files are (not surprisingly) scanned by the predefined C language scanner.

If mkid cannot determine what scanner to use for a particular file, either because the file has no suffix (e.g., foo) or because mkid has no binding for the file's suffix (e.g., foo.bar), it uses the scanner bound to the .default suffix.  By default, this is the plain text scanner (see Plain text scanner), but you can change this with the -S option, as explained below.

Scanner option formats
----------------------

With the -S option, you can change which language scanner to use for which files, give language-specific options, and get some limited online help about scanner options.

Here are the different forms of the -S option:

-S.SUFFIX=SCANNER
     Use SCANNER for a file with the given .SUFFIX.  For example, -S.yacc=c tells mkid to use the c language scanner for all files ending in .yacc.

-S.SUFFIX=?
     Display which scanner is used for the given .SUFFIX.

-S?=SCANNER
     Display which suffixes SCANNER is used for.

-S?=?
     Display the scanner binding for every known suffix.

-SSCANNER+ARG
-SSCANNER-ARG
     Each scanner accepts certain scanner-dependent arguments.  These options all have one of these forms.  See Predefined scanners.

-SSCANNER?
     Display the scanner-specific options accepted by SCANNER.

-SNEW-SCANNER/OLD-SCANNER/FILTER-COMMAND
     Define NEW-SCANNER in terms of OLD-SCANNER and FILTER-COMMAND.  See Defining scanners with options.

Predefined scanners
-------------------

mkid has built-in scanners for several types of languages; you can get the list by running mkid -S?=?. The supported languages are documented below (This is not strictly true: vhil is a supported language, but it is an obsolete and arcane dialect of C and should be ignored.).

C scanner
.........

The C scanner is the most commonly used.  Files with the usual .c and .h suffixes, and the .y (yacc) and .l (lex) suffixes, are processed with this scanner (by default).

Scanner-specific options:

-Sc-sCHARACTER
     Allow the specified CHARACTER in identifiers. For example, if you use $ in identifiers, you'll want to use -Sc-s$.

-Sc+u
     Strip leading underscores from identifiers. You might to do this in peculiar circumstances, such as trying to parse the output from nm or some other system utility.

-Sc-u
     Don't strip leading underscores from identifiers; this is the default.

Plain text scanner
..................

The plain text scanner is intended for scanning most non-source-code files.  This is typically the scanner used when adding custom scanners via -S (see Defining scanners with options).

Scanner-specific options:

-Stext+aCHARACTER
     Include CHARACTER in identifiers.  By default, letters (a--z and A--Z) and underscore are included.

-Stext-aCHARACTER
     Exclude CHARACTER from identifiers.

-Stext+sCHARACTER
     Squeeze CHARACTER from identifiers, i.e., do not terminate an identifier when CHARACTER is seen.  By default, the characters ', -, and . are squeezed out of identifiers.  For example, the input fred's leads to the identifier freds.

-Stext-sCHARACTER
     Do not squeeze CHARACTER.

Assembler scanner
.................

Since assembly languages come in several flavors, this scanner has a number of options:

-Sasm-cCHARACTER
     Define CHARACTER as starting a comment that extends to the end of the input line; no default.  In many assemblers this is ; or #.

-Sasm+u
-Sasm-u
     Strip (+u) or do not strip (-u) leading underscores from identifiers.  The default is to strip them.

-Sasm+aCHARACTER
     Allow CHARACTER in identifiers.

-Sasm-aCHARACTER
     Allow CHARACTER in identifiers, but if an identifier contains CHARACTER, ignore it. This is useful to ignore temporary labels, which can be generated in great profusion; these often contain . or @.

-Sasm+p
-Sasm-p
     Recognize (+p) or do not recognize (-p) C preprocessor directives in assembler source. The default is to recognize them.

-Sasm+C
-Sasm-C
     Skip over (+C) or do not skip over (-C) C style comments in assembler source.  The default is to skip them.

Defining new scanners
---------------------

You can add new scanners to mkid in two ways: modify the source code and recompile, or at runtime via the -S option.  Each has their advantages and disadvantages, as explained below.

If you create a new scanner that would be of use to others, please consider sending it back to the maintainer, gkm@magilla.cichlid.com, for inclusion in future releases of mkid.

Defining scanners in source code
................................

To add a new scanner in source code, you should add a new section to the file scanners.c.  Copy one of the existing scanners (most likely either C or plain text), and modify as necessary.  Also add the new scanner to the languages_0 and suffixes_0 tables near the beginning of the file.

This is not a terribly difficult programming task, but it requires recompiling and installing the new version of mkid, which may be inconvenient.

This method leads to scanners which operate much more quickly than ones that depend on external programmers.  It is also likely the easiest way to define scanners for new programming languages.

Defining scanners with options
..............................

You can use the -S option on the command line to define a new language scanner:

     -SNEW-SCANNER/EXISTING-SCANNER/FILTER

Here, NEW-SCANNER is the name of the new scanner being defined, EXISTING-SCANNER is the name of an existing scanner, and FILTER is a shell command or pipeline.

The new scanner works by passing the input file to FILTER, and then arranging for the result to be passed through EXISTING-SCANNER. Typically, EXISTING-SCANNER is text.

Somewhere within FILTER, the string%s should occur.  This %s is replaced by the name of the source file being scanned.

For example, mkid has no built-in scanner for Texinfo files (like this one).  In indexing a Texinfo file, you most likely would want to ignore the Texinfo @-commands. Here's one way to specify a new scanner to do this:

     -S/texinfo/text/sed s,@[a-z]*,,g %s

This defines a new language scanner (texinfo) defined in terms of a sed command to strip out Texinfo directives (an @ character followed by letters).  Once the directives are stripped, the remaining text is run through the plain text scanner.

This is a minimal example; to do a complete job, you would need to completely delete some lines, such as those beginning with @end or @node.

idx: Testing mkid scanners
--------------------------

idx prints the identifiers found in the files you specify to standard output. This is useful in debugging new mkid scanners (see Scanners). Synopsis:

     idx [-SSCANARG] FILES...

idx accepts the same -S options as mkid. See Scanner option formats.

The name ``idx'' stands for ``ID eXtract''.  The name may change in future releases, since this is such an infrequently used program.

mkid examples
=============

The simplest example of mkid is something like:

     mkid *.[chy]

This will build an ID database indexing identifiers and numbers in the all the .c, .h, and .y files in the current directory.  Because mkid already knows how to scan files with those suffixes, no additional options are needed.

Here's a more complex example. Suppose you want to build a database indexing the contents of all the man pages, and furthur suppose that your system is using gzip (see Gzip) to store compressed cat versions of the man pages in the directory /usr/catman.  The gzip program creates files with a .gz suffix, so you must tell mkid how to scan .gz files.  Here are the commands to do the job:

     cd /usr/catman
     find . -name \*.gz -print | mkid '-Sman/text/gzip <%s' -S.gz=man -

Explanation:

 1. We first cd to /usr/catman so the ID database will store the correct relative filenames.

 2. The find command prints the names of all .gz files under the current directory.  See find invocation (GNU shell utilities).

 3. This list is piped to mkid; the - option (at the end of the line) tells mkid to read arguments (in this case, as is typical, the list of filenames) from standard input.  See mkid options.

 4. The -Sman/text/gzip ... defines a new language man in terms of the gzip program and mkid's existing text scanner.  See Defining scanners with options.

 5. The -S.gz=man tells mkid to treat all .gz files as this new language man.  See Scanner option formats.

As a further complication, cat pages typically contain underlining and backspace sequences, which will confuse mkid.  To handle this, the gzip command becomes a pipeline, like this:

     mkid '-Sman/text/gzip <%s | col -b' -S.gz=man -

Common query arguments
**********************

Certain options, and regular expression syntax, are shared by the ID query tools.  So we describe those things in the sections below, instead of repeating the description for each tool.

Query options
=============

The ID query tools (not mkid) share certain command line options.  Not all of these options are recognized by all programs, but if an option is used by more than one program, it is described below. The description of each program gives the options that program uses.

-fIDFILE
     Read the database from IDFILE, in the current directory or in any directory above the current directory.  The default database name is ID.  Searching parent directories lets you have a single ID database at the root of a large source tree and then use the query tools from anywhere within that tree.

-rDIRECTORY
     Find files relative to DIRECTORY, instead of the directory in which the ID database was found.  This is useful if the ID database was moved after its creation.

-c
     Equivalent to -r`pwd`, i.e., find files relative to the current directory, instead of the directory in which the ID database was found.

-e
-w
     -e forces pattern arguments to be treated as regular expressions, and -w forces pattern arguments to be treated as constant strings.  By default, the query tools guess whether a pattern is regular expressions or constant strings by looking for special characters. See Patterns.

-k
-g
     -k suppresses use of shell brace notation in the output.  By default, the query tools that generate lists of filenames attempt to compress the lists using the usual shell brace notation, e.g., {foo,bar}.c to mean foo.c and bar.c.  (This is useful if you use ksh or the original (not GNU) sh and want to feed the list of names to another command, since those shells do not support this brace notation; the name of the -k option comes from the k in ksh).

     -g turns on use of brace notation; this is only needed if the query tools were compiled with -k as the default behavior.

-n
     Suppress the matching identifier before each list of filenames that the query tools output by default. This is useful if you want a list of just the names to feed to another command.

-d
-o
-x
-a
     These options may be used in any combination to specify the radix of numeric matches.  -d allows matching on decimal numbers, -o on octal numbers, and -x on hexadecimal numbers.  The -a option is equivalent to specifying all three; this is the default.  Any combination of these options may be used.

-m
     Merge multiple lines of output into a single line.  If your query matches more than one identifier, the default is to generate a separate line of output for each matching identifier.

-F-
-FN
-F-M
-FN-M
     Show identifiers matching at least N and at most M times. -F- is equivalent to -F1, i.e., find identifiers that appear only once in the database.  (This is useful to locate identifiers that are defined but never used, or used once and never defined.)

-uNUMBER
     List identifiers that conflict in the first NUMBER characters. This could be in useful porting programs to brain-dead computers that refuse to support long identifiers, but your best long term option is to set such computers on fire.

Patterns
========

Patterns, also called regular expressions, allow you to match many different identifiers in a single query.

The same regular expression syntax is recognized by all the query tools that handle regular expressions.  The exact syntax depends on how the ID tools were compiled, but the following constructs should always be supported:

.
     Match any single character.

[CHARS]
     Match any of the characters specified within the brackets.  You can match any characters except the ones in brackets by typing ^ as the first character.  A range of characters can be specified using -.  For example, [abc] and [a-c] both match a, b, or c, and [^abc] matches anything except a, b, or c.

*
     Match the previous construct zero or more times.

^
$
     ^ ($) at the beginning (end) of a pattern anchors the match to the first (last) character of the identifier.

The query programs use either the regex/regcmp or re_comp/re_exec functions, depending on which are available in the library on your system.  These do not always support the exact same regular expression syntax, so consult your local man pages to find out.

Query examples
==============

Here are some examples of the options described in the previous sections.

To restrict searches to exact matches, use ^...$. For example:

     prompt$ gid '^FILE$'
     ansi2knr.c:144: {	FILE *in, *out;
     ansi2knr.c:315:     FILE *out;
     fid.c:38: FILE *id_FILE;
     filenames.c:576: FILE *
     ...

To show identifiers not unique in the first 16 characters:

     prompt$ lid -u16
     RE_CONTEXT_INDEP_ANCHORS regex.c
     RE_CONTEXT_INDEP_OPS regex.c
     RE_SYNTAX_POSIX_BASIC regex.c
     RE_SYNTAX_POSIX_EXTENDED regex.c
     ...

Numbers are searched for numerically rather than textually. For example:

     prompt$ lid 0xff
     0377           {lid,regex}.c
     0xff           {bitops,fid,lid,mkid}.c
     255            regex.c

On the other hand, you can restrict a numeric search to a particular radix if you want:

     laurie$ lid -x 0xff
     0xff           {bitops,fid,lid,mkid}.c

Filenames in the output are always adjusted to be correct for the correct working directory. For example:

     prompt$ lid bdevsw
     bdevsw         sys/conf.h  cf/conf.c  io/bio.c  os/{fio,main,prf,sys3}.c
     prompt$ cd io
     prompt$ lid bdevsw
     bdevsw         ../sys/conf.h  ../cf/conf.c  bio.c  ../os/{fio,main,prf,sys3}.c

gid: Listing matching lines
***************************

Synopsis:

     gid [-fFILE] [-uN] [-rDIR] [-doxasc] [PATTERN...]

gid finds the identifiers in the database that match the specified PATTERNs, then searches for all occurrences of those identifiers, in only the files containing matches.  In a large source tree, this saves an enormous amount of time (compared to searching every source file).

With no PATTERN arguments, gid prints every line of every source file.

The name ``gid'' stands for ``grep for identifiers'', grep being the standard utility to search regular files.

See Common query arguments, for a description of the command-line options and PATTERN arguments.

gid uses the standard GNU output format for identifying source lines:

     FILENAME:LINENUM: TEXT

Here is an example:

     prompt$ gid FILE
     ansi2knr.c:144: {	FILE *in, *out;
     ansi2knr.c:315:     FILE *out;
     fid.c:38: FILE *id_FILE;
     ...

GNU Emacs gid interface
=======================

The mkid source distribution comes with a file gid.el, which defines a GNU Emacs interface to gid.  To install it, put gid.el somewhere that Emacs will find it (i.e., in your load-path) and put

     (autoload 'gid "gid" nil t)

in one of Emacs' initialization files, e.g., ~/.emacs. You will then be able to use M-x gid to run the command.

The gid function prompts you with the word around point.  If you want to search for something else, simply delete the line and type the pattern of interest.

The function then runs the gid program in a *compilation* buffer, so the normal next-error function can be used to visit all the places the identifier is found (see Compilation (The GNU Emacs Manual)).

Looking up identifiers
**********************

These commands look up identifiers in the ID database and operate on the files containing matches.

lid: Matching patterns
======================

Synopsis:

     lid [-fFILE] [-uN] [-rDIR] [-mewdoxaskgnc]
     PATTERN...

lid searches the database for identifiers matching the given PATTERN arguments and prints the names of the files that match each PATTERN.  With no PATTERNs, lid lists every entry in the database.

The name ``lid'' stands for ``lookup identifier''.

See Common query arguments, for a description of the command-line options and PATTERN arguments.

By default, each line of output consists of an identifier and all the files containing that identifier.

Here is an example showing a search for a single identifier (omitting some output to keep lines short):

     prompt$ lid FILE
     FILE           extern.h {fid,gets0,getsFF,idx,init,lid,mkid,...}.c

This example shows a regular expression search:

     prompt$ lid 'FILE$'
     AF_FILE        mkid.c
     AF_IDFILE      mkid.c
     FILE           extern.h {fid,gets0,getsFF,idx,init,lid,mkid,...}.c
     IDFILE         id.h {fid,lid,mkid}.c
     IdFILE         {fid,lid}.c
     ...

As you can see, when a regular expression is used, it is possible to get more than one line of output.  To merge multiple lines into one, use -m:

     prompt$ lid -m ^get
     ^get           extern.h {bitsvec,fid,gets0,getsFF,getscan,idx,lid,...}.c

aid: Matching strings
=====================

Synopsis:

     aid [-fFILE] [-uN] [-rDIR] [-mewdoxaskgnc]
     STRING...

aid searches the database for identifiers containing the given STRING arguments.  The search is case-insensitive.

The name ``aid'' stands for ``apropos identifier'', apropros being a command that does a similar search of the whatis database of man descriptions.

For example, aid get matches the identifiers fgets, GETLINE, and getchar.

The default output format is the same as lid; see the previous section.

See Common query arguments, for a description of the command-line options and PATTERN arguments.

eid: Invoking an editor on matches
==================================

Synopsis:

     eid [-fFILE] [-uN] [-rDIR] [-doxasc] [PATTERN]...

eid runs the usual search (see lid invocation) on the given arguments, shows you the output, and then asks:

     Edit? [y1-9^S/nq]

You can respond with:

y
     Edit all files listed.

1...9
     Start editing at the N + 1'st file.

/STRING or CTRL-SSTRING
     Start editing at the first filename containing STRING.

n
     Go on to the next PATTERN, i.e., edit nothing for this one.

q
     Quit eid.

eid invokes the editor defined by the EDITOR environment variable to edit a file.  If this editor can accept an initial search argument on the command line, eid can move automatically to the location of the match, via the environment variables below.

See Common query arguments, for a description of the command-line options and PATTERN arguments.

Here are the environment variables relevant to eid:

EDITOR
     The name of the editor program to invoke.

EIDARG
     The argument to pass to the editor to search for the matching identifier.  For vi, this should be +/%s/'.

EIDLDEL
     A regular expression to force a match at the beginning of a word (``left delimiter).  eid inserts this in front of the matching identifier when composing the search argument.  For vi, this should be \<.

EIDRDEL
     The end-of-word regular expression.  For vi, this should be \>.

For Emacs users, the interface in gid.el is probably preferable to eid.  See GNU Emacs gid interface.

Here is an example:

     prompt$ eid FILE \^print
     FILE           {ansi2knr,fid,filenames,idfile,idx,iid,lid,misc,...}.c
     Edit? [y1-9^S/nq] n
     ^print         {ansi2knr,fid,getopt,getopt1,iid,lid,mkid,regex,scanners}.c
     Edit? [y1-9^S/nq] 2

This will start editing at getopt.c.

fid: Listing a file's identifiers
=================================

fid lists the identifiers found in a given file.  Synopsis:

     fid [-fDBFILE] FILE1 [FILE2]

-fDBFILE
     Read the database from DBFILE instead of ID.

FILE1
     List all the identifiers contained in FILE1.

FILE2
     With a second file argument, list only the identifiers both files have in common.

The output is simply one identifier (or number) per line.

pid: Looking up filenames
*************************

pid matches the filenames stored in the ID database, rather than the identifiers.  Synopsis:

     pid [-fDBFILE] [-rDIR] [-ebkgnc] WILDCARD...

By default, the WILDCARD patterns are treated as shell globbing patterns, rather than the regular expressions the other utilities accept.  See the section below for details.

Besides the standard options given in the synopsis (see Query options), pid accepts the following:

-e
     Do the usual regular expression matching (see Patterns), instead of shell wildcard matching.

-b
     Match the basenames of the files in the database.  For example, pid -b foo will match the stored filename dir/foo, but not foo/file.

For example, the command:

     pid \*.c

lists all the .c files in the database.  (The \ here protects the * from being expanded by the shell.)

Wildcard patterns
=================

pid does simplified shell wildcard matching (unless the -e option is specified), rather than the regular expression matching done by the other utilities.  Here is a description of wildcard matching, also called globbing:

  * * matches zero or more characters.

  * ? matches any single character.

  * \ forces the next character to be taken literally.

  * [CHARS] matches any single character listed in CHARS.

  * [!CHARS] matches any character not listed in CHARS.

Most shells treat / and leading . characters specially. pid does not do this.  It simply matches the filename in the database against the wildcard pattern.

iid: Complex interactive queries
********************************

iid is an interactive query utility for ID databases.  It operates by running another query program (lid by default, aid if -a is specified) and manipulating the sets of filenames returned by these queries.

iid command line options
========================

iid recognizes the following options (the standard query options described in Query options are inapplicable):

-a
     Use aid for searches, instead of lid.

-cCOMMAND
     Execute COMMAND and exit, instead of prompting for interactive commands.

-H
     Print a usage message and exit successfully.  The help command inside iid gives more information.  See iid commands.

iid query expressions
=====================

An iid query expression generates a set of filenames or manipulates existing sets.  These expressions are operands to some of the iid commands (see the next section), not commands themselves.

Here are the possible constructs, highest precedence first:

sSET-NUMBER
     Refer to a set previously created by a query operation.  During each iid session, every query generates a different set number, so any previously generated set may be used as part of any new query by reference to its set number.

PATTERN
     iid treats any non-keyword input (i.e., anything not in this table) as an identifier to be searched for in the database.  It is passed to the search program (lid by default, aid if the -a option was specified).  The result of this operation is a set of filenames, and it is assigned a unique set number.

lid IDENTIFIER-LIST
     Invoke the lid program on IDENTIFIER-LIST and construct a new set from the result.

aid IDENTIFIER-LIST
     Like lid, but use the aid program.

match WILDCARDS
     Invoke the pid program on WILDCARDS, therefore matching on the filenames in the database instead of the identifiers.  The resulting set contains the filenames that match the specified patterns.  See pid invocation.

not EXPR
     The result is those filenames in the database that are not in EXPR.

EXPR1 and EXPR2
     The result is the intersection of the sets EXPR1 and EXPR2, i.e., only those filenames contained in both.

EXPR1 or EXPR2
     The result is the union of the sets EXPR1 and EXPR2, i.e., all the filenames contained in either or both.

Operator names are recognized independent of case, so AND, and, and aNd are all the same as far as iid is concerned.

To pass a keyword as an operand, you must enclose it in double quotes: the command lid "lid" generates the set of all filenames matching the string lid.

Patterns containing shell metacharacters (such as * or ?) must also be properly quoted, since the query commands are run by invoking them with the shell.

iid commands
============

This section describes the interactive commands that iid recognizes.  The database query expressions you can pass to the ss and files commands are described in the previous section.

Some commands output a summary line for sets. These lines show the set number, the number of filenames in the set, and the command that generated it.

ss QUERY
     Build the set(s) of filenames resulting from the query expression QUERY.  The output is a summary line for each set.

files QUERY
f QUERY
     Evaluate the query expression QUERY as in ss, but output the full list of matching filenames instead of a summary.

sets
     Output a summary line for each extant set.

show SET
p SET
     Pass the filename in the set number SET to the program named in the PAGER environment variable.  Typically, this is a page-at-a-time display program like less or more.  If you use Emacs, you might want to set PAGER to emacsclient (see Emacs Server (The GNU Emacs Manual)).

anything else
     When iid does not recognize the first word on an input line as a builtin iid command, it assumes the input is a shell command which will write a list of filenames to standard output, which it gathers into a set as usual.

     Any set numbers that appear in the input are expanded into the lists of filenames they represent prior to running the command.

!SHELL-COMMAND
     Expand set numbers appear in SHELL-COMMAND into the filenames they represent, and pass the result to /bin/sh. The output is not interpreted.

begin DIRECTORY
b DIRECTORY
     Begin a new iid session in a different directory (which presumably contains a different database).  It deletes all the sets created so far and switches to the specified directory.  It is equivalent to exiting iid, changing directories in the shell, and running iid again.

help
h
?
     Display a short help file using the program named in PAGER.

quit
q
off
     Quit iid. An end-of-file character (usually CTRL-D) also exits.