diff options
Diffstat (limited to 'mkid.texinfo')
| -rw-r--r-- | mkid.texinfo | 953 |
1 files changed, 953 insertions, 0 deletions
diff --git a/mkid.texinfo b/mkid.texinfo new file mode 100644 index 0000000..e1fcc3f --- /dev/null +++ b/mkid.texinfo @@ -0,0 +1,953 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename mkid.info +@settitle The ID Database +@setchapternewpage odd +@comment %**end of header (This is for running Texinfo on a region.) + +@include version.texi + +@ifinfo +@format +START-INFO-DIR-ENTRY +* mkid: (mkid). Identifier database utilities +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +This file documents the @code{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. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +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. +@end ifinfo + +@titlepage +@title The MKID Identifier Database, version @value{VERSION} +@subtitle A Simple, Fast, High-Capacity Cross-Referencer +@subtitle lid, gid, aid, eid, pid, iid +@author by Tom Horsley + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 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. +@end titlepage + +@node Top, Overview, (dir), (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 +@end menu + +@node Overview, Mkid, Top, Top +@chapter Overview +@cindex Reference to First Chapter +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 +@code{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 @code{mkid} program +scans the files, finds the identifiers and builds the ID database. The +@code{lid} and @code{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 @code{eid} program will +invoke an editor on each of the files containing an identifier and the +@code{gid} program will @code{grep} for an identifier in the subset of +files known to contain it. The @code{pid} tool is used to query the +path names of the files in the database (rather than the contents). +Finally, the @code{iid} tool is an interactive program supporting +complex queries to intersect and join sets of file names. + +@menu +* History:: History +@end menu + +@node History, , Overview, Overview +@section 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 @code{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 @file{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 @code{iid} program. A pre-release of +@code{mkid2} was posted to @file{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 @code{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. @code{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 @code{mkid} program. + +@node Mkid, Database Query Tools, Overview, Top +@chapter Mkid +The @code{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 @code{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 +@end menu + +@node Mkid Command Line Options, Builtin Scanners, Mkid, Mkid +@section Mkid Command Line Options +@deffn Command mkid [@code{-v}] [@code{-S@var{scanarg}}] [@code{-a@var{arg-file}}] [@code{-}] [@code{-f@var{out-file}}] [@code{-u}] [@code{files}@dots{}] +@table @code +@item -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. +@item -S@var{scanarg} +The @code{-S} option is used to specify arguments to the various language +scanners. @xref{Scanner Arguments}, for details. +@item -a@var{arg-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. +@item - +A simple @code{-} by itself means read arguments from stdin. +@item -f@var{out-file} +Specify the name of the database file to create. The default name is @code{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. +@item -u +The @code{-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. +@item files +Remaining arguments are names of files to be scanned and included in the +database. +@end table +@end deffn + +@menu +* Scanner Arguments:: Scanner Arguments +@end menu + +@node Scanner Arguments, , Mkid Command Line Options, Mkid Command Line Options +@subsection Scanner Arguments +Scanner arguments all start with @code{-S}. Scanner arguments are used to tell +@code{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. + +@code{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 +@samp{.} in a file name and includes the @samp{.} and all remaining +characters (for example the suffix of @file{fred.c} is @file{.c}). Not +all files have a suffix, and not all suffixes are bound to a specific +language by mkid. If @code{mkid} cannot determine what language a file +is, it will use the language bound to the @file{.default} suffix. The +plain text scanner is normally bound to @file{.default}, but the +@code{-S} option can be used to change any language bindings. + +There are several different forms for scanner options: +@table @code +@item -S.@var{<suffix>}=@var{<language>} +@code{Mkid} determines which language scanner to use on a file by examining the +file name suffix. The @samp{.} is part of the suffix and must be specified +in this form of the @code{-S} option. For example @samp{-S.y=c} tells +@code{mkid} to use the @samp{c} language scanner for all files ending in +the @samp{.y} suffix. +@item -S.@var{<suffix>}=? +@code{Mkid} has several built in suffixes it already recognizes. Passing +a @samp{?} will cause it to print the language it will use to scan files +with that suffix. +@item -S?=@var{<language>} +This form will print which suffixes are scanned with the given language. +@item -S?=? +This prints all the suffix@expansion{}language bindings recognized by +@code{mkid}. +@item -S@var{<language>}-@var{<arg>} +Each language scanner accepts scanner dependent arguments. This form of the +@code{-S} option is used to pass arbitrary arguments to the language scanners. +@item -S@var{<language>}? +Passing a @samp{?} instead of a language option will print a brief summary +of the options recognized by the specified language scanner. +@item -S@var{<new language>}/@var{<builtin language>}/@var{<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. +@end table + +@node Builtin Scanners, Adding Your Own Scanner, Mkid Command Line Options, Mkid +@section Builtin Scanners +If you run @code{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 +@footnote{This is not strictly true --- vhil is a supported language, but +it is an obsolete and arcane dialect of C and should be ignored}. + +@menu +* C:: C +* Plain Text:: Plain Text +* Assembler:: Assembler +@end menu + +@node C, Plain Text, Builtin Scanners, Builtin Scanners +@subsection 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 @file{.c} and @file{.h} suffixes are automatically recognized as +C language, as well as the more obscure @file{.y} (yacc) and @file{.l} +(lex) suffixes. + +The @code{-S} options recognized by the C scanner are: + +@table @code +@item -Sc-s@var{<character>} +Allow the specified @var{<character>} in identifiers (some dialects of +C allow @code{$} in identifiers, so you could say @code{-Sc-s$} to +accept that dialect). +@item -Sc-u +Don't strip leading underscores from identifier names (this is the default +mode of operation). +@item -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). +@end table + +@node Plain Text, Assembler, C, Builtin Scanners +@subsection 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 @code{mkid} and defined in terms of filters +and the text scanner. A troff scanner runs @code{deroff} over the file +then feeds the result to the text scanner. A compressed man page scanner +runs @code{pcat} piped into @code{col -b}, and a @TeX{} scanner runs +@code{detex}. + +Options: + +@table @code +@item -Stext+a@var{<character>} +Include the specified character in identifiers. By default, standard +C identifiers are recognized. +@item -Stext-a@var{<character>} +Exclude the specified character from identifiers. +@item -Stext+s@var{<character>} +Squeeze the specified character out of identifiers. By default, the +characters @samp{'}, @samp{-}, and @samp{.} are squeezed out of identifiers. +This generates transformations like @var{fred's}@expansion{}@var{freds} or +@var{a.s.p.c.a.}@expansion{}@var{aspca}. +@item -Stext-s@var{<character>} +Do not squeeze out the specified character. +@end table + +@node Assembler, , Plain Text, Builtin Scanners +@subsection Assembler +Assemblers come in several flavors, so there are several options to +control scanning of assembly code: + +@table @code +@item -Sasm-c@var{<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). +@item -Sasm+u +Strip the leading underscores off identifiers (the default behavior). +@item -Sasm-u +Do not strip the leading underscores. +@item -Sasm+a@var{<character>} +The specified character is allowed in identifiers. +@item -Sasm-a@var{<character>} +The specified character is allowed in identifiers, but any identifier +containing that character is ignored (often a @samp{.} or @samp{@@} +will be used to indicate an internal temp label, you may want to +ignore these). +@item -Sasm+p +Recognize C preprocessor directives in assembler source (default). +@item -Sasm-p +Do not recognize C preprocessor directives in assembler source. +@item -Sasm+C +Skip over C style comments in assembler source (default). +@item -Sasm-C +Do not skip over C style comments in assembler source. +@end table + +@node Adding Your Own Scanner, Mkid Examples, Builtin Scanners, Mkid +@section Adding Your Own Scanner + +There are two ways to add new scanners to @code{mkid}. The first is to +modify the code in @file{getscan.c} and add a new @file{scan-*.c} file +with the code for your scanner. This is not too hard, but it requires +relinking and installing a new version of @code{mkid}, which might be +inconvenient, and would lead to the proliferation of @code{mkid} +versions. + +The second technique uses the @code{-S<lang>/<lang>/<filter>} form +of the @code{-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 @code{-S} option. + +The filter is an arbitrary shell command. Somewhere in the filter string, +a @code{%s} should occur. This @code{%s} is replaced by the name of the +source file being scanned, the shell command is invoked, and whatever +comes out on @var{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: + +@example +'-S/texinfo/text/sed s,@@[a-z]*,,g < %s' +@end example + +This defines a new language scanner (@var{texinfo}) defined in terms of +a @code{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 @code{@@end}) as well +as deleting the @code{@@} directives embedded in the text. + +@node Mkid Examples, , Adding Your Own Scanner, Mkid +@section Mkid Examples + +The simplest example of @code{mkid} is something like: + +@example +mkid *.[chy] +@end example + +This will build an ID database indexing all the +identifiers and numbers in the @file{.c}, @file{.h}, and @file{.y} files +in the current directory. Because those suffixes are already known to +@code{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 @var{man} pages. +Since @code{mkid} already knows how to deal with @file{.z} files, let's +assume your system is using the @code{compress} program to store +compressed cattable versions of the @var{man} pages. The +@code{compress} program creates files with a @code{.Z} suffix, so +@code{mkid} will have to be told how to scan @file{.Z} files. The +following code shows how to combine the @code{find} command with the +special scanner arguments to @code{mkid} to generate the required ID +database: + +@example +cd /usr/catman +find . -name '*.Z' -print | mkid '-Sman/text/uncompress -c < %s' -S.Z=man - +@end example + +This example first switches to the @file{/usr/catman} directory where +the compressed @var{man} pages are stored. The @code{find} command then +finds all the @file{.Z} files under that directory and prints their +names. This list is piped into the @code{mkid} program. The @code{-} +argument by itself (at the end of the line) tells @code{mkid} to read +arguments (in this case the list of file names) from @var{stdin}. The +first @code{-S} argument defines a new language (@var{man}) in terms of +the @code{uncompress} utility and the existing text scanner. The second +@code{-S} argument tells @code{mkid} to treat all @file{.Z} files as +language @var{man}. In practice, you might find the @code{mkid} +arguments need to be even more complex, something like: + +@example +mkid '-Sman/text/uncompress -c < %s | col -b' -S.Z=man - +@end example + +This will take the additional step of getting rid of any underlining and +backspacing which might be present in the compressed @var{man} pages. + +@node Database Query Tools, Iid, Mkid, Top +@chapter Database Query Tools + +The ID database is useless without database query tools. The remainder +of this document describes those tools. + +The @code{lid}, @code{gid}, +@code{aid}, @code{eid}, and @code{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 @code{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 +@end menu + +@node Common Options, Patterns, Database Query Tools, Database Query Tools +@section 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. + +@table @code +@item -f@var{<file>} +Read the database specified by @var{<file>}. Normally the tools look +for a file named @file{ID} in either the current directory or in any +of the directories above the current directory. This means you can keep +a global @file{ID} database in the root of a large source tree and use +the query tools from anywhere within that tree. +@item -r@var{<directory>} +The query tools usually assume the file names in the database are relative +to the directory holding the database. The @code{-r} option tells the +tools to look for the files relative to @var{<directory>} regardless +of the location of the database. +@item -c +This is shorthand for @code{-r`pwd`}. It tells the query tools to assume +the file names are stored relative to the current working directory. +@item -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. +@item -w +Force the pattern arguments to be treated as simple words even if +they contain special regular expression characters. +@item -k +Normally the query tools that generate lists of file names attempt to +compress the lists using the @code{csh} brace notation. This option +suppresses the file name compression and outputs each name in full. +(This is particularly useful if you are a @code{ksh} user and want to +feed the list of names to another command --- the @code{-k} option +comes from the @code{k} in @code{ksh}). +@item -g +It is possible to build the query tools so the @code{-k} option is the +default behavior. If this is the case for your system, the @code{-g} +option turns on the globbing of file names using the @code{csh} brace +notation. +@item -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 @code{-n} option suppresses the identifier and lists only +file names. +@item -b +This option is only used by the @code{pid} tool. It restricts @code{pid} +to pattern match only the basename part of a file name. Normally the +absolute file name is matched against the pattern. +@item -d -o -x -a +These options may be used in any combination to limit the radix of +numeric matches. The @code{-d} option will allow matches on decimal +numbers, @code{-o} on octal, and @code{-x} on hexadecimal numbers. +The @code{-a} option is shorthand for specifying all three. Any +combination of these options may be used. +@item -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). +@item -s +Search for identifiers that appear only once in the database. This +helps to locate identifiers that are defined but never used. +@item -u@var{<number>} +List identifiers that conflict in the first @var{<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. +@end table + +@node Patterns, Lid, Common Options, Database Query Tools +@section 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 @var{regex} and @var{regcmp} or @var{re_comp} +and @var{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 @var{man} pages +to find out. Any regular expression routines should support the following +syntax: + +@table @code +@item . +A dot matches any character. +@item [ ] +Brackets match any of the characters specified within the brackets. You +can match any characters @emph{except} the ones in brackets by typing +@code{^} as the first character. A range of characters can be specified +using @code{-}. +@item * +An asterisk means repeat the previous pattern zero or more times. +@item ^ +An @code{^} at the beginning of a pattern means the pattern must match +starting at the first character of the identifier. +@item $ +A @code{$} at the end of the pattern means the pattern must match ending +at the last character in the identifier. +@end table + +@node Lid, Aid, Patterns, Database Query Tools +@section Lid + +@deffn Command lid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-ewdoxamskgnc}] patterns@dots{} +@end deffn + +The @code{lid} program stands for @var{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. + +@node Aid, Gid, Lid, Database Query Tools +@section Aid + +@deffn Command aid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-doxamskgnc}] patterns@dots{} +@end deffn + +The @code{aid} command is an abbreviation for @var{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 @samp{aid get} might match the identifiers @code{fgets}, +@code{GETLINE}, and @code{getchar}. + +@node Gid, Eid, Aid, Database Query Tools +@section Gid + +@deffn Command gid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-doxasc}] patterns@dots{} +@end deffn + +The @code{gid} command stands for @var{grep for identifiers}. It finds +identifiers in the database that match the specified patterns, then +@code{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 @var{emacs} interface to this program (@pxref{GNU Emacs Interface}). +If you are an @var{emacs} user, you will probably prefer the @var{emacs} +interface over the @code{eid} tool. + +@node Eid, Pid, Gid, Database Query Tools +@section Eid + +@deffn Command eid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-doxasc}] patterns@dots{} +@end deffn + +The @code{eid} command allows you to invoke an editor on each file containing +a matching pattern. The @code{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 @code{EIDARG}, @code{EIDLDEL}, +and @code{EIDRDEL} environment variables to specify the form of that argument. + +@table @code +@item EDITOR +The name of the editor program to invoke. +@item EIDARG +A printf string giving the form of the argument to pass containing the +initial search string (the matching identifier). For @code{vi} +it should be set to @samp{+/%s/'}. +@item 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 @code{vi}, +this should be @samp{\<}. +@item EIDRDEL +The matching right end word delimiter. For @code{vi}, use @samp{\>}. +@end table + +@node Pid, , Eid, Database Query Tools +@section Pid + +@deffn Command pid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-ebkgnc}] patterns@dots{} +@end deffn + +The @code{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 @code{-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 @samp{/} and file names that start with +dot @samp{.} specially, @code{pid} does not do this. It simply attempts +to match the absolute path name string against the wild card pattern. + +The @code{-b} option restricts the pattern matching to the base name of +the file (all the leading directory names are stripped prior to pattern +matching). + +@node Iid, Other Tools, Database Query Tools, Top +@chapter Iid + +@deffn Command iid [@code{-a}] [@code{-c@var{<command>}}] [@code{-H}] +@table @code +@item -a +Normally @code{iid} uses the @code{lid} command to search for names. +If you give the @code{-a} option on the command line, then it will +use @code{aid} as the default search engine. +@item -c@var{<command>} +In normal operation, @code{iid} starts up and prompts you for commands +used to build sets of files. The @code{-c} option is used to pass a +single query command to @code{iid} which it then executes and exits. +@item -H +The @code{-H} option prints a short help message and exits. To get more +help use the @code{help} command from inside @code{iid}. +@end table +@end deffn + +The @code{iid} program is an interactive ID query tool. It operates by +running the other query programs (such as @code{lid} and @code{aid}) +and creating sets of file names returned by these queries. It also +provides operators for @code{anding} and @code{oring} these sets to +create new sets. + +The @code{PAGER} environment variable names the program @code{iid} uses +to display files. If you use @code{emacs}, you might want to set +@code{PAGER} so it invokes the @code{emacsclient} program. Check the +file @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 +@code{iid} from an emacs shell buffer. There is also a somewhat spiffier +version called gnuserv by Andy Norman +(@code{ange%anorman@@hplabs.hp.com}) which appeared in @file{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 +@end menu + +@node Ss and Files commands, Sets, Iid, Iid +@section Ss and Files commands + +The primary query commands are @code{ss} (for select sets) and @code{files} +(for show file names). These commands both take a query expression as an +argument. + +@deffn Subcommand ss query +The @code{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. +@end deffn + +@deffn Subcommand files query +The @code{files} command is like the @code{ss} command, but rather than printing +a summary, it displays the full list of matching file names. +@end deffn + +@deffn Subcommand f query +The @code{f} command is merely a shorthand notation for @code{files}. +@end deffn + +Database queries are simple expressions with operators like @code{and} +and @code{or}. Parentheses can be used to group operations. The complete +set of operators is summarized below: + +@table @code +@item @var{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 @code{lid}, but @code{aid} +is used if the @code{-a} option was given when @code{iid} was started). +The result of this operation is a set of file names, and it is assigned a +unique set number. +@item lid +@code{lid} is a keyword. It is used to invoke @code{lid} with the list of +identifiers following it as arguments. This forces the use of @code{lid} +regardless of the state of the @code{-a} option (@pxref{Lid}). +@item aid +The @code{aid} keyword is like the @code{lid} keyword, but it forces the +use of the @code{aid} program (@pxref{Aid}). +@item match +The @code{match} operator invokes the @code{pid} program to do pattern +matching on file names rather than identifiers. The set generated contains +the file names that match the specified patterns (@pxref{Pid}). +@item or +The @code{or} operator takes two sets of file names as arguments and generates +a new set containing all the files from both sets. +@item and +The @code{and} operator takes two sets of file names and generates a new +set containing only files from both sets. +@item not +The @code{not} operator inverts a set of file names, producing the set of +all files not in the input set. +@item set number +A set number consists of the letter @code{s} followed immediately by a number. +This refers to one of the sets created by a previous query operation. During +one @code{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. +@end table + +The @code{not} operator has the highest precedence with @code{and} +coming in the middle and @code{or} having the lowest precedence. The +operator names are recognized using case insensitive matching, so +@code{AND}, @code{and}, and @code{aNd} are all the same as far as +@code{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: + +@example +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> ) +@end example + +@node Sets, Show, Ss and Files commands, Iid +@section Sets + +@deffn Subcommand sets +@end deffn + +The @code{sets} command displays all the sets created so far. Each one +is described by the query command that generated it. + +@node Show, Begin, Sets, Iid +@section Show + +@deffn Subcommand show set +@end deffn + +@deffn Subcommand p set +@end deffn + +The @code{show} and @code{p} commands are equivalent. They both accept +a set number as an argument and run the program given in the @code{PAGER} +environment variable with the file names in that set as arguments. + +@node Begin, Help, Show, Iid +@section Begin + +@deffn Subcommand begin directory +@end deffn + +@deffn Subcommand b directory +@end deffn + +The @code{begin} command (and its abbreviated version @code{b}) is used +to begin a new @code{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 @code{iid}, +changing directories in the shell, and running @code{iid} again. + +@node Help, Off, Begin, Iid +@section Help + +@deffn Subcommand help +@end deffn + +@deffn Subcommand h +@end deffn + +@deffn Subcommand ? +@end deffn + +The @code{help}, @code{h}, and @code{?} command are three different ways to +ask for help. They all invoke the @code{PAGER} program to display a short +help file. + +@node Off, Shell Commands as Queries, Help, Iid +@section Off + +@deffn Subcommand off +@end deffn + +@deffn Subcommand quit +@end deffn + +@deffn Subcommand q +@end deffn + +These three command (or just an end of file) all cause @code{iid} to exit. + +@node Shell Commands as Queries, Shell Escape, Off, Iid +@section Shell Commands as Queries + +When the first word on an @code{iid} command is not recognized as a +builtin @code{iid} command, @code{iid} assumes the command is a shell +command which will write a list of file names to @var{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. + +@node Shell Escape, , Shell Commands as Queries, Iid +@section Shell Escape + +If a command starts with a bang (@code{!}) 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. + +@node Other Tools, Command Index, Iid, Top +@chapter 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. +@end menu + +@node GNU Emacs Interface, Fid, Other Tools, Other Tools +@section GNU Emacs Interface + +The source distribution comes with a file named @file{gid.el}. This is +a GNU emacs interface to the @code{gid} tool. If you put the file where +emacs can find it (somewhere in your @code{EMACSLOADPATH}) and put +@code{(autoload 'gid "gid" nil t)} in your @file{.emacs} file, you will +be able to invoke the @code{gid} function using @kbd{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 @code{gid} in a @code{*compilation*} buffer, so the normal +@code{next-error} function can be used to visit all the places the +identifier is found (@pxref{Compilation,,,emacs,The GNU Emacs Manual}). + +@node Fid, Idx, GNU Emacs Interface, Other Tools +@section Fid + +@deffn Command fid [@code{-f@var{<file>}}] file1 [file2] +@table @code +@item -f@var{<file>} +Look in the named database. +@item @var{file1} +List the identifiers contained in file1 according to the database. +@item @var{file2} +If a second file is given, list only the identifiers both files have +in common. +@end table +@end deffn + +The @code{fid} program provides an inverse query. Instead of listing +files containing some identifier, it lists the identifiers found in +a file. + +@node Idx, , Fid, Other Tools +@section Idx + +@deffn Command idx [@code{-s@var{<directory>}}] [@code{-r@var{<directory>}}] [@code{-S@var{<scanarg>}}] files@dots{} +The @code{-s}, @code{-r}, and @code{-S} arguments to @code{idx} +are identical to the same arguments on @code{mkid} +(@pxref{Mkid Command Line Options}). +@end deffn + +The @code{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 @code{mkid}, but rather than building a database, it prints the +identifiers found to @var{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. + +@node Command Index, , Other Tools, Top +@unnumbered Command Index + +@printindex fn + +@contents +@bye |