path: root/mkid.info

This is Info file mkid.info, produced by Makeinfo-1.55 from the input
file mkid.texinfo.

START-INFO-DIR-ENTRY
* mkid: (mkid).			Identifier database utilities
END-INFO-DIR-ENTRY

   This file documents the `mkid' identifier database utilities.

   Copyright (C) 1991 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.


File: mkid.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

* Menu:

* Overview::                    What is an ID database and what tools manipulate it?
* Mkid::                        Mkid
* Database Query Tools::        Database Query Tools
* Iid::                         Iid
* Other Tools::                 Other Tools
* Command Index::               Command Index


File: mkid.info,  Node: Overview,  Next: Mkid,  Prev: Top,  Up: Top

Overview
********

   An ID database is simply a file containing a list of file names, a
list of identifiers, and a binary relation (stored as a bit matrix)
indicating which of the identifiers appear in each file.  With this
database and some tools to manipulate the data, a host of tasks become
simpler and faster. You can `grep' through hundreds of files for a
name, skipping the files that don't contain the name.  You can search
for all the memos containing references to a project.  You can edit
every file that calls some function, adding a new required argument.
Anyone with a large software project to maintain, or a large set of
text files to organize can benefit from the ID database and the tools
that manipulate it.

   There are several programs in the ID family.  The `mkid' program
scans the files, finds the identifiers and builds the ID database.  The
`lid' and `aid' tools are used to generate lists of file names
containing an identifier (perhaps to recompile every file that
references a macro which just changed). The `eid' program will invoke
an editor on each of the files containing an identifier and the `gid'
program will `grep' for an identifier in the subset of files known to
contain it.  The `pid' tool is used to query the path names of the
files in the database (rather than the contents).  Finally, the `iid'
tool is an interactive program supporting complex queries to intersect
and join sets of file names.

* Menu:

* History::                     History


File: mkid.info,  Node: History,  Prev: Overview,  Up: Overview

History
=======

   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 built with 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.1BSDish kernel.  Lookups
were done with the UNIX command `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'
September of 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 pre-release of `mkid2'
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 thanks Doug Scofield and Bill Leonard whom I dragooned into
helping me poorf raed and edit -- they found several problems in the
initial version.)

   In January, 1995, Greg McGary reemerged as the primary maintaner and
is hereby launching `mkid-3' whose primary new feature is an efficient
algorithm for building databases that is linear over the size of the
input text for both time and space.  (The old algorithm was quadratic
for space and choked on very large source trees.)  The code is now under
GPL and might become a part of the GNU system.  `Mkid-3' is an interim
release, since several significant enhacements are in the works.  These
include 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 file name argument to the `mkid'
program.


File: mkid.info,  Node: Mkid,  Next: Database Query Tools,  Prev: Overview,  Up: Top

Mkid
****

   The `mkid' program builds the ID database.  To do this it must scan
each of the files included in the database.  This takes some time, but
once the work is done the query programs run very rapidly.

   The `mkid' program knows how to scan a variety of of files. For
example, it knows how to skip over comments and strings in a C program,
only picking out the identifiers used in the code.

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

   All the places in this document where identifiers are written about
should really mention identifiers and numbers, but that gets fairly
clumsy after a while, so you should always keep in mind that numbers are
included in the database as well as identifiers.

* Menu:

* Mkid Command Line Options::   Mkid Command Line Options
* Builtin Scanners::            Builtin Scanners
* Adding Your Own Scanner::     Adding Your Own Scanner
* Mkid Examples::               Mkid Examples


File: mkid.info,  Node: Mkid Command Line Options,  Next: Builtin Scanners,  Prev: Mkid,  Up: Mkid

Mkid Command Line Options
=========================

 - Command: mkid [`-v'] [`-SSCANARG'] [`-aARG-FILE'] [`-']
          [`-fOUT-FILE'] [`-u'] [`files'...]
    `-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'
          The `-S' option is used to specify arguments to the various
          language scanners. *Note Scanner Arguments::, for details.

    `-aARG-FILE'
          Name a file containing additional command line arguments (one
          per line). This may be used to specify lists of file names
          longer than will fit on a command line.

    `-'
          A simple `-' by itself means read arguments from stdin.

    `-fOUT-FILE'
          Specify the name of the database file to create. The default
          name is `ID' (in the current directory), but you may specify
          any name. The file names stored in the database will be
          stored relative to the directory containing the database, so
          if you move the database after creating it, you may have
          trouble finding files unless they remain in the same relative
          position.

    `-u'
          The `-u' option updates an existing database by rescanning
          any files that have changed since the database was written.
          Unfortunately you cannot incrementally add new files to a
          database.

    `files'
          Remaining arguments are names of files to be scanned and
          included in the database.

* Menu:

* Scanner Arguments::           Scanner Arguments


File: mkid.info,  Node: Scanner Arguments,  Prev: Mkid Command Line Options,  Up: Mkid Command Line Options

Scanner Arguments
-----------------

   Scanner arguments all start with `-S'. Scanner arguments are used to
tell `mkid' which language scanner to use for which files, to pass
language specific options to the individual scanners, and to get some
limited online help about scanner options.

   `Mkid' usually determines which language scanner to use on a file by
looking at the suffix of the file name. The suffix starts at the last
`.' in a file name and includes the `.' and all remaining characters
(for example the suffix of `fred.c' is `.c'). Not all files have a
suffix, and not all suffixes are bound to a specific language by mkid.
If `mkid' cannot determine what language a file is, it will use the
language bound to the `.default' suffix. The plain text scanner is
normally bound to `.default', but the `-S' option can be used to change
any language bindings.

   There are several different forms for scanner options:
`-S.<SUFFIX>=<LANGUAGE>'
     `Mkid' determines which language scanner to use on a file by
     examining the file name suffix. The `.' is part of the suffix and
     must be specified in this form of the `-S' option. For example
     `-S.y=c' tells `mkid' to use the `c' language scanner for all
     files ending in the `.y' suffix.

`-S.<SUFFIX>=?'
     `Mkid' has several built in suffixes it already recognizes. Passing
     a `?' will cause it to print the language it will use to scan files
     with that suffix.

`-S?=<LANGUAGE>'
     This form will print which suffixes are scanned with the given
     language.

`-S?=?'
     This prints all the suffix==>language bindings recognized by
     `mkid'.

`-S<LANGUAGE>-<ARG>'
     Each language scanner accepts scanner dependent arguments. This
     form of the `-S' option is used to pass arbitrary arguments to the
     language scanners.

`-S<LANGUAGE>?'
     Passing a `?' instead of a language option will print a brief
     summary of the options recognized by the specified language
     scanner.

`-S<NEW LANGUAGE>/<BUILTIN LANGUAGE>/<FILTER COMMAND>'
     This form specifies a new language defined in terms of a builtin
     language and a shell command that will be used to filter the file
     prior to passing on to the builtin language scanner.


File: mkid.info,  Node: Builtin Scanners,  Next: Adding Your Own Scanner,  Prev: Mkid Command Line Options,  Up: Mkid

Builtin Scanners
================

   If you run `mkid -S?=?' you will find bindings for a number of
languages; unfortunately pascal, though mentioned in the list, is not
actually supported.  The supported languages are documented below (1).

* Menu:

* C::                           C
* Plain Text::                  Plain Text
* Assembler::                   Assembler

   ---------- Footnotes ----------

   (1)  This is not strictly true -- vhil is a supported language, but
it is an obsolete and arcane dialect of C and should be ignored


File: mkid.info,  Node: C,  Next: Plain Text,  Prev: Builtin Scanners,  Up: Builtin Scanners

C
-

   The C scanner is probably the most popular. It scans identifiers out
of C programs, skipping over comments and strings in the process.  The
normal `.c' and `.h' suffixes are automatically recognized as C
language, as well as the more obscure `.y' (yacc) and `.l' (lex)
suffixes.

   The `-S' options recognized by the C scanner are:

`-Sc-s<CHARACTER>'
     Allow the specified <CHARACTER> in identifiers (some dialects of C
     allow `$' in identifiers, so you could say `-Sc-s$' to accept that
     dialect).

`-Sc-u'
     Don't strip leading underscores from identifier names (this is the
     default mode of operation).

`-Sc+u'
     Do strip leading underscores from identifier names (I don't know
     why you would want to do this in C programs, but the option is
     available).


File: mkid.info,  Node: Plain Text,  Next: Assembler,  Prev: C,  Up: Builtin Scanners

Plain Text
----------

   The plain text scanner is designed for scanning documents. This is
typically the scanner used when adding custom scanners, and several
custom scanners are built in to `mkid' and defined in terms of filters
and the text scanner. A troff scanner runs `deroff' over the file then
feeds the result to the text scanner. A compressed man page scanner
runs `pcat' piped into `col -b', and a TeX scanner runs `detex'.

   Options:

`-Stext+a<CHARACTER>'
     Include the specified character in identifiers. By default,
     standard C identifiers are recognized.

`-Stext-a<CHARACTER>'
     Exclude the specified character from identifiers.

`-Stext+s<CHARACTER>'
     Squeeze the specified character out of identifiers. By default, the
     characters `'', `-', and `.' are squeezed out of identifiers.
     This generates transformations like FRED'S==>FREDS or
     A.S.P.C.A.==>ASPCA.

`-Stext-s<CHARACTER>'
     Do not squeeze out the specified character.


File: mkid.info,  Node: Assembler,  Prev: Plain Text,  Up: Builtin Scanners

Assembler
---------

   Assemblers come in several flavors, so there are several options to
control scanning of assembly code:

`-Sasm-c<CHARACTER>'
     The specified character starts a comment that extends to end of
     line (in many assemblers this is a semicolon or number sign --
     there is no default value for this).

`-Sasm+u'
     Strip the leading underscores off identifiers (the default
     behavior).

`-Sasm-u'
     Do not strip the leading underscores.

`-Sasm+a<CHARACTER>'
     The specified character is allowed in identifiers.

`-Sasm-a<CHARACTER>'
     The specified character is allowed in identifiers, but any
     identifier containing that character is ignored (often a `.' or `@'
     will be used to indicate an internal temp label, you may want to
     ignore these).

`-Sasm+p'
     Recognize C preprocessor directives in assembler source (default).

`-Sasm-p'
     Do not recognize C preprocessor directives in assembler source.

`-Sasm+C'
     Skip over C style comments in assembler source (default).

`-Sasm-C'
     Do not skip over C style comments in assembler source.


File: mkid.info,  Node: Adding Your Own Scanner,  Next: Mkid Examples,  Prev: Builtin Scanners,  Up: Mkid

Adding Your Own Scanner
=======================

   There are two ways to add new scanners to `mkid'. The first is to
modify the code in `getscan.c' and add a new `scan-*.c' file with the
code for your scanner. This is not too hard, but it requires relinking
and installing a new version of `mkid', which might be inconvenient,
and would lead to the proliferation of `mkid' versions.

   The second technique uses the  `-S<lang>/<lang>/<filter>' form of
the `-S' option to specify a new language scanner. In this form the
first language is the name of the new language to be defined, the
second language is the name of an existing language scanner to be
invoked on the output of the filter command specified as the third
component of the `-S' option.

   The filter is an arbitrary shell command. Somewhere in the filter
string, a `%s' should occur. This `%s' is replaced by the name of the
source file being scanned, the shell command is invoked, and whatever
comes out on STDOUT is scanned using the builtin scanner.

   For example, no scanner is provided for texinfo files (like this
one).  If I wished to index the contents of this file, but avoid
indexing the texinfo directives, I would need a filter that stripped
out the texinfo directives, but left the remainder of the file intact.
I could then use the plain text scanner on the remainder. A quick way
to specify this might be:

     '-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 (at signs followed by
letters). Once the directives are stripped, the remaining text is run
through the plain text scanner.

   This is just an example, to do a better job I would actually need to
delete some lines (such as those beginning with `@end') as well as
deleting the `@' directives embedded in the text.


File: mkid.info,  Node: Mkid Examples,  Prev: Adding Your Own Scanner,  Up: Mkid

Mkid Examples
=============

   The simplest example of `mkid' is something like:

     mkid *.[chy]

   This will build an ID database indexing all the identifiers and
numbers in the `.c', `.h', and `.y' files in the current directory.
Because those suffixes are already known to `mkid' as C language files,
no other special arguments are required.

   From a simple example, lets go to a more complex one. Suppose you
want to build a database indexing the contents of all the MAN pages.
Since `mkid' already knows how to deal with `.z' files, let's assume
your system is using the `compress' program to store compressed
cattable versions of the MAN pages.  The `compress' program creates
files with a `.Z' suffix, so `mkid' will have to be told how to scan
`.Z' files. The following code shows how to combine the `find' command
with the special scanner arguments to `mkid' to generate the required ID
database:

     cd /usr/catman
     find . -name '*.Z' -print | mkid '-Sman/text/uncompress -c < %s' -S.Z=man -

   This example first switches to the `/usr/catman' directory where the
compressed MAN pages are stored. The `find' command then finds all the
`.Z' files under that directory and prints their names.  This list is
piped into the `mkid' program. The `-' argument by itself (at the end
of the line) tells `mkid' to read arguments (in this case the list of
file names) from STDIN. The first `-S' argument defines a new language
(MAN) in terms of the `uncompress' utility and the existing text
scanner. The second `-S' argument tells `mkid' to treat all `.Z' files
as language MAN. In practice, you might find the `mkid' arguments need
to be even more complex, something like:

     mkid '-Sman/text/uncompress -c < %s | col -b' -S.Z=man -

   This will take the additional step of getting rid of any underlining
and backspacing which might be present in the compressed MAN pages.


File: mkid.info,  Node: Database Query Tools,  Next: Iid,  Prev: Mkid,  Up: Top

Database Query Tools
********************

   The ID database is useless without database query tools. The
remainder of this document describes those tools.

   The `lid', `gid', `aid', `eid', and `pid' programs are all the same
program installed with links to different names. The name used to
invoke the program determines how it will act.

   The `iid' program is an interactive query shell that sits on top of
the other query tools.

* Menu:

* Common Options::              Common command line options
* Patterns::                    Identifier pattern matching
* Lid::                         Look up identifiers
* Aid::                         Case insensitive lid
* Gid::                         Grep for identifiers
* Eid::                         Edit files with matching identifiers
* Pid::                         Look up path names in database


File: mkid.info,  Node: Common Options,  Next: Patterns,  Prev: Database Query Tools,  Up: Database Query Tools

Common Options
==============

   Since many of the programs are really links to one common program, it
is only reasonable to expect that most of the query tools would share
common command line options. Not all options make sense for all
programs, but they are all described here. The description of each
program gives the options that program uses.

`-f<FILE>'
     Read the database specified by <FILE>. Normally the tools look for
     a file named `ID' in either the current directory or in any of the
     directories above the current directory. This means you can keep a
     global `ID' database in the root of a large source tree and use
     the query tools from anywhere within that tree.

`-r<DIRECTORY>'
     The query tools usually assume the file names in the database are
     relative to the directory holding the database. The `-r' option
     tells the tools to look for the files relative to <DIRECTORY>
     regardless of the location of the database.

`-c'
     This is shorthand for `-r`pwd`'. It tells the query tools to assume
     the file names are stored relative to the current working
     directory.

`-e'
     Force the pattern arguments to be treated as regular expressions.
     Normally the query tools attempt to guess if the patterns are
     regular expressions or simple identifiers by looking for special
     characters in the pattern.

`-w'
     Force the pattern arguments to be treated as simple words even if
     they contain special regular expression characters.

`-k'
     Normally the query tools that generate lists of file names attempt
     to compress the lists using the `csh' brace notation. This option
     suppresses the file name compression and outputs each name in full.
     (This is particularly useful if you are a `ksh' user and want to
     feed the list of names to another command -- the `-k' option comes
     from the `k' in `ksh').

`-g'
     It is possible to build the query tools so the `-k' option is the
     default behavior. If this is the case for your system, the `-g'
     option turns on the globbing of file names using the `csh' brace
     notation.

`-n'
     Normally the query tools that generate lists of file names also
     list the matching identifier at the head of the list of names.
     This is irritating if you want just a list of names to feed to
     another command, so the `-n' option suppresses the identifier and
     lists only file names.

`-b'
     This option is only used by the `pid' tool. It restricts `pid' to
     pattern match only the basename part of a file name. Normally the
     absolute file name is matched against the pattern.

`-d -o -x -a'
     These options may be used in any combination to limit the radix of
     numeric matches. The `-d' option will allow matches on decimal
     numbers, `-o' on octal, and `-x' on hexadecimal numbers.  The `-a'
     option is shorthand for specifying all three. 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 action is to generate
     a separate line of output for each matching identifier).

`-s'
     Search for identifiers that appear only once in the database. This
     helps to locate identifiers that are defined but never used.

`-u<NUMBER>'
     List identifiers that conflict in the first <NUMBER> characters.
     This could be 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.


File: mkid.info,  Node: Patterns,  Next: Lid,  Prev: Common Options,  Up: Database Query Tools

Patterns
========

   You can attempt to match either simple identifiers or numbers in a
query, or you can specify a regular expression pattern which may match
many different identifiers in the database. The query programs use
either REGEX and REGCMP or RE_COMP and RE_EXEC, depending on which one
is available in the library on your system. These might not always
support the exact same regular expression syntax, so consult your local
MAN pages to find out. Any regular expression routines should support
the following syntax:

`.'
     A dot matches any character.

`[ ]'
     Brackets 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 `-'.

`*'
     An asterisk means repeat the previous pattern zero or more times.

`^'
     An `^' at the beginning of a pattern means the pattern must match
     starting at the first character of the identifier.

`$'
     A `$' at the end of the pattern means the pattern must match ending
     at the last character in the identifier.


File: mkid.info,  Node: Lid,  Next: Aid,  Prev: Patterns,  Up: Database Query Tools

Lid
===

 - Command: lid [`-f<FILE>'] [`-u<N>'] [`-r<DIR>'] [`-ewdoxamskgnc']
          PATTERNS...

   The `lid' program stands for LOOKUP IDENTIFIER.  It searches the
database for any identifiers matching the patterns and prints the names
of the files that match each pattern. The exact format of the output
depends on the options.


File: mkid.info,  Node: Aid,  Next: Gid,  Prev: Lid,  Up: Database Query Tools

Aid
===

 - Command: aid [`-f<FILE>'] [`-u<N>'] [`-r<DIR>'] [`-doxamskgnc']
          PATTERNS...

   The `aid' command is an abbreviation for APROPOS IDENTIFIER.  The
patterns cannot be regular expressions, but it looks for them using a
case insensitive match, and any pattern that is a substring of an
identifier in the database will match that identifier.

   For example `aid get' might match the identifiers `fgets',
`GETLINE', and `getchar'.


File: mkid.info,  Node: Gid,  Next: Eid,  Prev: Aid,  Up: Database Query Tools

Gid
===

 - Command: gid [`-f<FILE>'] [`-u<N>'] [`-r<DIR>'] [`-doxasc']
          PATTERNS...

   The `gid' command stands for GREP FOR IDENTIFIERS. It finds
identifiers in the database that match the specified patterns, then
`greps' for those identifiers in just the set of files containing
matches. In a large source tree, this saves a fantastic amount of time.

   There is an EMACS interface to this program (*note GNU Emacs
Interface::.).  If you are an EMACS user, you will probably prefer the
EMACS interface over the `eid' tool.


File: mkid.info,  Node: Eid,  Next: Pid,  Prev: Gid,  Up: Database Query Tools

Eid
===

 - Command: eid [`-f<FILE>'] [`-u<N>'] [`-r<DIR>'] [`-doxasc']
          PATTERNS...

   The `eid' command allows you to invoke an editor on each file
containing a matching pattern. The `EDITOR' environment variable is the
name of the program to be invoked. If the specified editor can accept
an initial search argument on the command line, you can use the
`EIDARG', `EIDLDEL', and `EIDRDEL' environment variables to specify the
form of that argument.

`EDITOR'
     The name of the editor program to invoke.

`EIDARG'
     A printf string giving the form of the argument to pass containing
     the initial search string (the matching identifier). For `vi' it
     should be set to `+/%s/''.

`EIDLDEL'
     A string giving the regular expression pattern that forces a match
     at the beginning (left end) of a word. This string is inserted in
     front of the matching identifier when composing the search
     argument. For `vi', this should be `\<'.

`EIDRDEL'
     The matching right end word delimiter. For `vi', use `\>'.


File: mkid.info,  Node: Pid,  Prev: Eid,  Up: Database Query Tools

Pid
===

 - Command: pid [`-f<FILE>'] [`-u<N>'] [`-r<DIR>'] [`-ebkgnc']
          PATTERNS...

   The `pid' tool is unlike all the other tools. It matches the
patterns against the file names in the database rather than the
identifiers in the database.  Patterns are treated as shell wild card
patterns unless the `-e' option is given, in which case full regular
expression matching is done.

   The wild card pattern is matched against the absolute path name of
the file. Most shells treat slashes `/' and file names that start with
dot `.' specially, `pid' does not do this. It simply attempts to match
the absolute path name string against the wild card pattern.

   The `-b' option restricts the pattern matching to the base name of
the file (all the leading directory names are stripped prior to pattern
matching).


File: mkid.info,  Node: Iid,  Next: Other Tools,  Prev: Database Query Tools,  Up: Top

Iid
***

 - Command: iid [`-a'] [`-c<COMMAND>'] [`-H']
    `-a'
          Normally `iid' uses the `lid' command to search for names.
          If you give the `-a' option on the command line, then it will
          use `aid' as the default search engine.

    `-c<COMMAND>'
          In normal operation, `iid' starts up and prompts you for
          commands used to build sets of files. The `-c' option is used
          to pass a single query command to `iid' which it then
          executes and exits.

    `-H'
          The `-H' option prints a short help message and exits. To get
          more help use the `help' command from inside `iid'.

   The `iid' program is an interactive ID query tool. It operates by
running the other query programs (such as `lid' and `aid') and creating
sets of file names returned by these queries. It also provides
operators for `anding' and `oring' these sets to create new sets.

   The `PAGER' environment variable names the program `iid' uses to
display files. If you use `emacs', you might want to set `PAGER' so it
invokes the `emacsclient' program. Check the file `lisp/server.el' in
the emacs source tree for documentation on this. It is useful not only
with X windows, but also when running `iid' from an emacs shell buffer.
There is also a somewhat spiffier version called gnuserv by Andy Norman
(`ange%anorman@hplabs.hp.com') which appeared in `comp.emacs' sometime
in 1989.

* Menu:

* Ss and Files commands::       Ss and Files commands
* Sets::                        Sets
* Show::                        Show
* Begin::                       Begin
* Help::                        Help
* Off::                         Off
* Shell Commands as Queries::   Shell Commands as Queries
* Shell Escape::                Shell Escape


File: mkid.info,  Node: Ss and Files commands,  Next: Sets,  Prev: Iid,  Up: Iid

Ss and Files commands
=====================

   The primary query commands are `ss' (for select sets) and `files'
(for show file names). These commands both take a query expression as an
argument.

 - Subcommand: ss QUERY
     The `ss' command runs a query and builds a set (or sets) of file
     names. The result is printed as a summary of the sets constructed
     showing how many file names are in each set.

 - Subcommand: files QUERY
     The `files' command is like the `ss' command, but rather than
     printing a summary, it displays the full list of matching file
     names.

 - Subcommand: f QUERY
     The `f' command is merely a shorthand notation for `files'.

   Database queries are simple expressions with operators like `and'
and `or'. Parentheses can be used to group operations. The complete set
of operators is summarized below:

`PATTERN'
     Any pattern not recognized as one of the keywords in this table is
     treated as an identifier to be searched for in the database. It is
     passed as an argument to the default search program (normally
     `lid', but `aid' is used if the `-a' option was given when `iid'
     was started).  The result of this operation is a set of file
     names, and it is assigned a unique set number.

`lid'
     `lid' is a keyword. It is used to invoke `lid' with the list of
     identifiers following it as arguments. This forces the use of `lid'
     regardless of the state of the `-a' option (*note Lid::.).

`aid'
     The `aid' keyword is like the `lid' keyword, but it forces the use
     of the `aid' program (*note Aid::.).

`match'
     The `match' operator invokes the `pid' program to do pattern
     matching on file names rather than identifiers. The set generated
     contains the file names that match the specified patterns (*note
     Pid::.).

`or'
     The `or' operator takes two sets of file names as arguments and
     generates a new set containing all the files from both sets.

`and'
     The `and' operator takes two sets of file names and generates a new
     set containing only files from both sets.

`not'
     The `not' operator inverts a set of file names, producing the set
     of all files not in the input set.

`set number'
     A set number consists of the letter `s' followed immediately by a
     number.  This refers to one of the sets created by a previous
     query operation. During one `iid' session, each query generates a
     unique set number, so any previously generated set may be used as
     part of any new query by referring to the set number.

   The `not' operator has the highest precedence with `and' coming in
the middle and `or' having the lowest precedence.  The operator names
are recognized using case insensitive matching, so `AND', `and', and
`aNd' are all the same as far as `iid' is concerned. If you wish to use
a keyword as an operand to one of the query programs, you must enclose
it in quotes.  Any patterns containing shell special characters must
also be properly quoted or escaped, since the query commands are run by
invoking them with the shell.

   Summary of query expression syntax:

     A <query> is:
        <set number>
        <identifier>
        lid <identifier list>
        aid <identifier list>
        match <wild card list>
        <query> or <query>
        <query> and <query>
        not <query>
        ( <query> )


File: mkid.info,  Node: Sets,  Next: Show,  Prev: Ss and Files commands,  Up: Iid

Sets
====

 - Subcommand: sets

   The `sets' command displays all the sets created so far. Each one is
described by the query command that generated it.


File: mkid.info,  Node: Show,  Next: Begin,  Prev: Sets,  Up: Iid

Show
====

 - Subcommand: show SET

 - Subcommand: p SET

   The `show' and `p' commands are equivalent. They both accept a set
number as an argument and run the program given in the `PAGER'
environment variable with the file names in that set as arguments.


File: mkid.info,  Node: Begin,  Next: Help,  Prev: Show,  Up: Iid

Begin
=====

 - Subcommand: begin DIRECTORY

 - Subcommand: b DIRECTORY

   The `begin' command (and its abbreviated version `b') is used to
begin a new `iid' session in a different directory (which presumably
contains a different database). It flushes 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.


File: mkid.info,  Node: Help,  Next: Off,  Prev: Begin,  Up: Iid

Help
====

 - Subcommand: help

 - Subcommand: h

 - Subcommand: ?

   The `help', `h', and `?' command are three different ways to ask for
help. They all invoke the `PAGER' program to display a short help file.


File: mkid.info,  Node: Off,  Next: Shell Commands as Queries,  Prev: Help,  Up: Iid

Off
===

 - Subcommand: off

 - Subcommand: quit

 - Subcommand: q

   These three command (or just an end of file) all cause `iid' to exit.


File: mkid.info,  Node: Shell Commands as Queries,  Next: Shell Escape,  Prev: Off,  Up: Iid

Shell Commands as Queries
=========================

   When the first word on an `iid' command is not recognized as a
builtin `iid' command, `iid' assumes the command is a shell command
which will write a list of file names to STDOUT. This list of file
names is used to generate a new set of files.

   Any set numbers that appear as arguments to this command are expanded
into lists of file names prior to running the command.


File: mkid.info,  Node: Shell Escape,  Prev: Shell Commands as Queries,  Up: Iid

Shell Escape
============

   If a command starts with a bang (`!') character, the remainder of
the line is run as a shell command. Any set numbers that appear as
arguments to this command are expanded into lists of file names prior to
running the command.


File: mkid.info,  Node: Other Tools,  Next: Command Index,  Prev: Iid,  Up: Top

Other Tools
***********

   This chapter describes some support tools that work with the other ID
programs.

* Menu:

* GNU Emacs Interface::         Using gid.el
* Fid::                         List identifiers in a file.
* Idx::                         Extract identifiers from source file.


File: mkid.info,  Node: GNU Emacs Interface,  Next: Fid,  Prev: Other Tools,  Up: Other Tools

GNU Emacs Interface
===================

   The source distribution comes with a file named `gid.el'.  This is a
GNU emacs interface to the `gid' tool.  If you put the file where emacs
can find it (somewhere in your `EMACSLOADPATH') and put `(autoload 'gid
"gid" nil t)' in your `.emacs' file, you will be able to invoke the
`gid' function using `M-x gid'.

   This function prompts you with the word the cursor is on. If you want
to search for a different pattern, simply delete the line and type the
pattern of interest.

   It runs `gid' in a `*compilation*' buffer, so the normal
`next-error' function can be used to visit all the places the
identifier is found (*note Compilation: (emacs)Compilation.).


File: mkid.info,  Node: Fid,  Next: Idx,  Prev: GNU Emacs Interface,  Up: Other Tools

Fid
===

 - Command: fid [`-f<FILE>'] FILE1 [FILE2]
    `-f<FILE>'
          Look in the named database.

    `FILE1'
          List the identifiers contained in file1 according to the
          database.

    `FILE2'
          If a second file is given, list only the identifiers both
          files have in common.

   The `fid' program provides an inverse query. Instead of listing
files containing some identifier, it lists the identifiers found in a
file.


File: mkid.info,  Node: Idx,  Prev: Fid,  Up: Other Tools

Idx
===

 - Command: idx [`-s<DIRECTORY>'] [`-r<DIRECTORY>'] [`-S<SCANARG>']
          FILES...
     The `-s', `-r', and `-S' arguments to `idx' are identical to the
     same arguments on `mkid' (*note Mkid Command Line Options::.).

   The `idx' command is more of a test frame for scanners than a tool
designed to be independently useful. It takes the same scanner arguments
as `mkid', but rather than building a database, it prints the
identifiers found to STDOUT, one per line. You can use it to try out a
scanner on a sample file to make sure it is extracting the identifiers
you believe it should extract.


File: mkid.info,  Node: Command Index,  Prev: Other Tools,  Up: Top

Command Index
*************

* Menu:

* ?:                                    Help.
* aid:                                  Aid.
* b:                                    Begin.
* begin:                                Begin.
* eid:                                  Eid.
* f:                                    Ss and Files commands.
* fid:                                  Fid.
* files:                                Ss and Files commands.
* gid:                                  Gid.
* h:                                    Help.
* help:                                 Help.
* idx:                                  Idx.
* iid:                                  Iid.
* lid:                                  Lid.
* mkid:                                 Mkid Command Line Options.
* off:                                  Off.
* p:                                    Show.
* pid:                                  Pid.
* q:                                    Off.
* quit:                                 Off.
* sets:                                 Sets.
* show:                                 Show.
* ss:                                   Ss and Files commands.



Tag Table:
Node: Top913
Node: Overview1298
Node: History2862
Node: Mkid5027
Node: Mkid Command Line Options6363
Node: Scanner Arguments8124
Node: Builtin Scanners10479
Node: C11144
Node: Plain Text12039
Node: Assembler13107
Node: Adding Your Own Scanner14295
Node: Mkid Examples16272
Node: Database Query Tools18249
Node: Common Options19190
Node: Patterns22906
Node: Lid24148
Node: Aid24570
Node: Gid25101
Node: Eid25721
Node: Pid26845
Node: Iid27735
Node: Ss and Files commands29605
Node: Sets33068
Node: Show33308
Node: Begin33636
Node: Help34123
Node: Off34404
Node: Shell Commands as Queries34634
Node: Shell Escape35160
Node: Other Tools35502
Node: GNU Emacs Interface35879
Node: Fid36685
Node: Idx37237
Node: Command Index37912

End Tag Table