diff options
Diffstat (limited to 'mkid.texinfo')
| -rw-r--r-- | mkid.texinfo | 957 |
1 files changed, 0 insertions, 957 deletions
diff --git a/mkid.texinfo b/mkid.texinfo deleted file mode 100644 index 076b313..0000000 --- a/mkid.texinfo +++ /dev/null @@ -1,957 +0,0 @@ -\input 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 - -@ifinfo -@node Top, Overview, (dir), (dir) -@top GNU @code{mkid} - -@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 - -@end ifinfo - -@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 |