rsalz@bbn.com (Rich Salz) (06/06/91)
Submitted-by: Tom Horsley <tom@hcx2.ssd.csd.harris.com>
Posting-number: Volume 24, Issue 95
Archive-name: mkid2/part07
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 7 (of 7)."
# Contents: id.texinfo
# Wrapped by tom@hcx2 on Tue Feb 26 10:03:09 1991
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'id.texinfo' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'id.texinfo'\"
else
echo shar: Extracting \"'id.texinfo'\" \(38176 characters\)
sed "s/^X//" >'id.texinfo' <<'END_OF_FILE'
X\input texinfo @c -*-texinfo-*-
X@comment %**start of header (This is for running Texinfo on a region.)
X@setfilename id-info
X@settitle The ID Database
X@setchapternewpage odd
X@comment %**end of header (This is for running Texinfo on a region.)
X
X@ifinfo
XThis manual is not copyrighted, but for your information it was written
Xin 1991 by Tom Horsley.
X
XAs far as I am concerned, this manual is in the public domain. Not even
Xcopyleft applies. If you think you can sell it for a profit, go right
Xahead...
X
XThe above non-copyright notice applies only to this manual, refer to the
Xsource code for information on the copyright status (if any) of the files.
X
XThe id-info file for this document may be created using the makeinfo.c
Xprogram release with the 2.32 version of the texinfo.tex macros. Due to
Xthe extensive use of various definition commands and nested constructs
Xdon't expect to get a good info file with texinfo-format-buffer or very
Xearly versions of makeinfo.c.
X
XI obtained the texinfo.tex macros and the makeinfo.c file from the
Xfile pub/gnu/texinfo2.tar.Z on prep.ai.mit.edu.
X@end ifinfo
X
X@titlepage
X@title The ID Database
X@subtitle mkid and friends
X@subtitle lid, gid, aid, eid, pid, iid
X@author Tom Horsley
X
X@page
X@vskip 0pt plus 1filll
XThis manual is not copyrighted, but for your information it was written
Xin 1991 by Tom Horsley.
X
XAs far as I am concerned, this manual is in the public domain. Not even
Xcopyleft applies. If you think you can sell it for a profit, go right
Xahead...
X
XThe above non-copyright notice applies only to this manual, refer to the source
Xcode for information on the copyright status (if any) of the files.
X
XThis document was prepared using version 2.32 of the @file{texinfo.tex}
Xmacro package, but I suspect any version greater or equal to 2.0 will work.
X@end titlepage
X
X@node Top, Overview, (dir), (dir)
X
X@menu
X* Overview:: What is an ID database and what tools manipulate it?
X* Mkid:: Mkid
X* Database Query Tools:: Database Query Tools
X* Iid:: Iid
X* Other Tools:: Other Tools
X* Command Index:: Command Index
X@end menu
X
X@node Overview, Mkid, Top, Top
X@chapter Overview
X@cindex Reference to First Chapter
XAn ID database is simply a file containing a list of file names, a list of
Xidentifiers, and a binary relation (stored as a bit matrix) indicating which
Xof the identifiers appear in each file. With this database and some tools
Xto manipulate the data, a host of tasks become simpler and faster. You can
X@code{grep} through hundreds of files for a name, skipping the files that
Xdon't contain the name. You can search for all the memos containing
Xreferences to a project. You can edit every file that calls some function,
Xadding a new required argument. Anyone with a large software project to
Xmaintain, or a large set of text files to organize can benefit from the ID
Xdatabase and the tools that manipulate it.
X
XThere are several programs in the ID family. The @code{mkid} program
Xscans the files, finds the identifiers and builds the ID database. The
X@code{lid} and @code{aid} tools are used to generate lists of file names
Xcontaining an identifier (perhaps to recompile every file that
Xreferences a macro which just changed). The @code{eid} program will
Xinvoke an editor on each of the files containing an identifier and the
X@code{gid} program will @code{grep} for an identifier in the subset of
Xfiles known to contain it. The @code{pid} tool is used to query the
Xpath names of the files in the database (rather than the contents).
XFinally, the @code{iid} tool is an interactive program supporting
Xcomplex queries to intersect and join sets of file names.
X
X@menu
X* History:: History
X@end menu
X
X@node History, , Overview, Overview
X@section History
XMost of the ID programs were written by Greg McGary and first posted to
Xthe net in 1987. Since then several versions have diverged from the
Xoriginal source. The @code{iid} program was written by Tom Horsley at
XHarris. This version (the one you are getting with this document) is
Xbased on the latest source in use at Harris Computer Systems Division.
XIt contains a few patches from other sources, but none of the major
Xchanges made at other sites. This release is the first attempt to start
Xthe process of merging the separate versions.
X
XA pre-release version of @code{mkid} was posted to @file{alt.sources}
Xnear the end of 1990. At that time I mentioned that I was thinking about
Xwriting a texinfo manual. I got a lot of encouragement from the net to
Xdo so, and this manual is the result. I would like to thank Doug Scofield
Xand Bill Leonard whom I dragooned into helping me poorf raed and
Xedit --- they found several problems in the initial version.
X
X@node Mkid, Database Query Tools, Overview, Top
X@chapter Mkid
XThe @code{mkid} program builds the ID database. To do this it must scan
Xeach of the files included in the database. This often takes
Xquite a while, but once the work is done the query programs run very
Xrapidly.
X
XThe @code{mkid} program knows how to scan a variety of of files. For
Xexample, it knows how to skip over comments and strings in a C program,
Xonly picking out the identifiers used in the code.
X
XIdentifiers are not the only thing included in the database.
XNumbers are also scanned and included in the database indexed by
Xtheir binary value. Since the same number can be written many
Xdifferent ways (47, 0x2f, 057 in a C program for instance), this
Xfeature allows you to find hard coded uses of constants without
Xregard to the radix used to specify them.
X
XAll the places in this document where identifiers are written about
Xshould really mention identifiers and numbers, but that gets fairly
Xclumsy after a while, so you should always keep in mind that numbers are
Xincluded in the database as well as identifiers.
X
X@menu
X* Mkid Command Line Options:: Mkid Command Line Options
X* Builtin Scanners:: Builtin Scanners
X* Adding Your Own Scanner:: Adding Your Own Scanner
X* Mkid Examples:: Mkid Examples
X@end menu
X
X@node Mkid Command Line Options, Builtin Scanners, Mkid, Mkid
X@section Mkid Command Line Options
X@deffn Command mkid [@code{-v}] [@code{-S@var{scanarg}}] [@code{-a@var{arg-file}}] [@code{-}] [@code{-f@var{out-file}}] [@code{-s@var{directory}}] [@code{-r@var{directory}}] [@code{-u}] [@code{files}@dots{}]
X@table @code
X@item -v
XVerbose. Mkid tells you as it scans each file and indicates which scanner
Xit is using. It also summarizes some statistics about the database at
Xthe end.
X@item -S@var{scanarg}
XThe @code{-S} option is used to specify arguments to the various language
Xscanners. @xref{Scanner Arguments}, for details.
X@item -a@var{arg-file}
XName a file containing additional command line arguments (one per line). This
Xmay be used to specify lists of file names longer than will fit on a command
Xline.
X@item -
XA simple @code{-} by itself means read arguments from stdin.
X@item -f@var{out-file}
XSpecify the name of the database file to create. The default name is @code{ID}
X(in the current directory), but you may specify any name. The file names
Xstored in the database will be stored relative to the directory containing
Xthe database, so if you move the database after creating it, you may have
Xtrouble finding files unless they remain in the same relative position.
X@item -s@var{directory}
XSpecify a directory to search for SCCS files in case a file named on the
Xcommand line does not exist.
X@item -r@var{directory}
XSpecify a directory to search for RCS files in case a file named on the
Xcommand line does not exist.
X@item -u
XThe @code{-u} option updates an existing database by rescanning any files
Xthat have changed since the database was written. Unfortunately you cannot
Xincrementally add new files to a database.
X@item files
XRemaining arguments are names of files to be scanned and included in the
Xdatabase.
X@end table
X@end deffn
X
X@menu
X* Scanner Arguments:: Scanner Arguments
X@end menu
X
X@node Scanner Arguments, , Mkid Command Line Options, Mkid Command Line Options
X@subsection Scanner Arguments
XScanner arguments all start with @code{-S}. Scanner arguments are used to tell
X@code{mkid} which language scanner to use for which files, to pass language
Xspecific options to the individual scanners, and to get some limited
Xonline help about scanner options.
X
X@code{Mkid} usually determines which language scanner to use on a file
Xby looking at the suffix of the file name. The suffix starts at the last
X@samp{.} in a file name and includes the @samp{.} and all remaining
Xcharacters (for example the suffix of @file{fred.c} is @file{.c}). Not
Xall files have a suffix, and not all suffixes are bound to a specific
Xlanguage by mkid. If @code{mkid} cannot determine what language a file
Xis, it will use the language bound to the @file{.default} suffix. The
Xplain text scanner is normally bound to @file{.default}, but the
X@code{-S} option can be used to change any language bindings.
X
XThere are several different forms for scanner options:
X@table @code
X@item -S.@var{<suffix>}=@var{<language>}
X@code{Mkid} determines which language scanner to use on a file by examining the
Xfile name suffix. The @samp{.} is part of the suffix and must be specified
Xin this form of the @code{-S} option. For example @samp{-S.y=c} tells
X@code{mkid} to use the @samp{c} language scanner for all files ending in
Xthe @samp{.y} suffix.
X@item -S.@var{<suffix>}=?
X@code{Mkid} has several built in suffixes it already recognizes. Passing
Xa @samp{?} will cause it to print the language it will use to scan files
Xwith that suffix.
X@item -S?=@var{<language>}
XThis form will print which suffixes are scanned with the given language.
X@item -S?=?
XThis prints all the suffix@expansion{}language bindings recognized by
X@code{mkid}.
X@item -S@var{<language>}-@var{<arg>}
XEach language scanner accepts scanner dependent arguments. This form of the
X@code{-S} option is used to pass arbitrary arguments to the language scanners.
X@item -S@var{<language>}?
XPassing a @samp{?} instead of a language option will print a brief summary
Xof the options recognized by the specified language scanner.
X@item -S@var{<new language>}/@var{<builtin language>}/@var{<filter command>}
XThis form specifies a new language defined in terms of a builtin language
Xand a shell command that will be used to filter the file prior to passing
Xon to the builtin language scanner.
X@end table
X
X@node Builtin Scanners, Adding Your Own Scanner, Mkid Command Line Options, Mkid
X@section Builtin Scanners
XIf you run @code{mkid -S?=?} you will find bindings for a number of
Xlanguages; unfortunately pascal, though mentioned in the list, is not
Xactually supported. The supported languages are documented below
X@footnote{This is not strictly true --- vhil is a supported language, but
Xit is an obsolete and arcane dialect of C and should be ignored}.
X
X@menu
X* C:: C
X* Plain Text:: Plain Text
X* Assembler:: Assembler
X@end menu
X
X@node C, Plain Text, Builtin Scanners, Builtin Scanners
X@subsection C
X
XThe C scanner is probably the most popular. It scans identifiers out of
XC programs, skipping over comments and strings in the process. The
Xnormal @file{.c} and @file{.h} suffixes are automatically recognized as
XC language, as well as the more obscure @file{.y} (yacc) and @file{.l}
X(lex) suffixes.
X
XThe @code{-S} options recognized by the C scanner are:
X
X@table @code
X@item -Sc-s@var{<character>}
XAllow the specified @var{<character>} in identifiers (some dialects of
XC allow @code{$} in identifiers, so you could say @code{-Sc-s$} to
Xaccept that dialect).
X@item -Sc-u
XDon't strip leading underscores from identifier names (this is the default
Xmode of operation).
X@item -Sc+u
XDo strip leading underscores from identifier names (I don't know why you
Xwould want to do this in C programs, but the option is available).
X@end table
X
X@node Plain Text, Assembler, C, Builtin Scanners
X@subsection Plain Text
XThe plain text scanner is designed for scanning documents. This is
Xtypically the scanner used when adding custom scanners, and several
Xcustom scanners are built in to @code{mkid} and defined in terms of filters
Xand the text scanner. A troff scanner runs @code{deroff} over the file
Xthen feeds the result to the text scanner. A compressed man page scanner
Xruns @code{pcat} piped into @code{col -b}, and a @TeX{} scanner runs
X@code{detex}.
X
XOptions:
X
X@table @code
X@item -Stext+a@var{<character>}
XInclude the specified character in identifiers. By default, standard
XC identifiers are recognized.
X@item -Stext-a@var{<character>}
XExclude the specified character from identifiers.
X@item -Stext+s@var{<character>}
XSqueeze the specified character out of identifiers. By default, the
Xcharacters @samp{'}, @samp{-}, and @samp{.} are squeezed out of identifiers.
XThis generates transformations like @var{fred's}@expansion{}@var{freds} or
X@var{a.s.p.c.a.}@expansion{}@var{aspca}.
X@item -Stext-s@var{<character>}
XDo not squeeze out the specified character.
X@end table
X
X@node Assembler, , Plain Text, Builtin Scanners
X@subsection Assembler
XAssemblers come in several flavors, so there are several options to
Xcontrol scanning of assembly code:
X
X@table @code
X@item -Sasm-c@var{<character>}
XThe specified character starts a comment that extends to end of line
X(in many assemblers this is a semicolon or number sign --- there is
Xno default value for this).
X@item -Sasm+u
XStrip the leading underscores off identifiers (the default behavior).
X@item -Sasm-u
XDo not strip the leading underscores.
X@item -Sasm+a@var{<character>}
XThe specified character is allowed in identifiers.
X@item -Sasm-a@var{<character>}
XThe specified character is allowed in identifiers, but any identifier
Xcontaining that character is ignored (often a @samp{.} or @samp{@@}
Xwill be used to indicate an internal temp label, you may want to
Xignore these).
X@item -Sasm+p
XRecognize C preprocessor directives in assembler source (default).
X@item -Sasm-p
XDo not recognize C preprocessor directives in assembler source.
X@item -Sasm+C
XSkip over C style comments in assembler source (default).
X@item -Sasm-C
XDo not skip over C style comments in assembler source.
X@end table
X
X@node Adding Your Own Scanner, Mkid Examples, Builtin Scanners, Mkid
X@section Adding Your Own Scanner
X
XThere are two ways to add new scanners to @code{mkid}. The first is to
Xmodify the code in @file{getscan.c} and add a new @file{scan-*.c} file
Xwith the code for your scanner. This is not too hard, but it requires
Xrelinking and installing a new version of @code{mkid}, which might be
Xinconvenient, and would lead to the proliferation of @code{mkid}
Xversions.
X
XThe second technique uses the @code{-S<lang>/<lang>/<filter>} form
Xof the @code{-S} option to specify a new language scanner. In this form
Xthe first language is the name of the new language to be defined,
Xthe second language is the name of an existing language scanner to
Xbe invoked on the output of the filter command specified as the
Xthird component of the @code{-S} option.
X
XThe filter is an arbitrary shell command. Somewhere in the filter string,
Xa @code{%s} should occur. This @code{%s} is replaced by the name of the
Xsource file being scanned, the shell command is invoked, and whatever
Xcomes out on @var{stdout} is scanned using the builtin scanner.
X
XFor example, no scanner is provided for texinfo files (like this one).
XIf I wished to index the contents of this file, but avoid indexing the
Xtexinfo directives, I would need a filter that stripped out the texinfo
Xdirectives, but left the remainder of the file intact. I could then use
Xthe plain text scanner on the remainder. A quick way to specify this
Xmight be:
X
X@example
X'-S/texinfo/text/sed s,@@[a-z]*,,g < %s'
X@end example
X
XThis defines a new language scanner (@var{texinfo}) defined in terms of
Xa @code{sed} command to strip out texinfo directives (at signs followed
Xby letters). Once the directives are stripped, the remaining text is run
Xthrough the plain text scanner.
X
XThis is just an example, to do a better job I would actually need to
Xdelete some lines (such as those beginning with @code{@@end}) as well
Xas deleting the @code{@@} directives embedded in the text.
X
X@node Mkid Examples, , Adding Your Own Scanner, Mkid
X@section Mkid Examples
X
XThe simplest example of @code{mkid} is something like:
X
X@example
Xmkid *.[chy]
X@end example
X
XThis will build an ID database indexing all the
Xidentifiers and numbers in the @file{.c}, @file{.h}, and @file{.y} files
Xin the current directory. Because those suffixes are already known to
X@code{mkid} as C language files, no other special arguments are required.
X
XFrom a simple example, lets go to a more complex one. Suppose you want
Xto build a database indexing the contents of all the @var{man} pages.
XSince @code{mkid} already knows how to deal with @file{.z} files, let's
Xassume your system is using the @code{compress} program to store
Xcompressed cattable versions of the @var{man} pages. The
X@code{compress} program creates files with a @code{.Z} suffix, so
X@code{mkid} will have to be told how to scan @file{.Z} files. The
Xfollowing code shows how to combine the @code{find} command with the
Xspecial scanner arguments to @code{mkid} to generate the required ID
Xdatabase:
X
X@example
Xcd /usr/catman
Xfind . -name '*.Z' -print | mkid '-Sman/text/uncompress -c < %s' -S.Z=man -
X@end example
X
XThis example first switches to the @file{/usr/catman} directory where
Xthe compressed @var{man} pages are stored. The @code{find} command then
Xfinds all the @file{.Z} files under that directory and prints their
Xnames. This list is piped into the @code{mkid} program. The @code{-}
Xargument by itself (at the end of the line) tells @code{mkid} to read
Xarguments (in this case the list of file names) from @var{stdin}. The
Xfirst @code{-S} argument defines a new language (@var{man}) in terms of
Xthe @code{uncompress} utility and the existing text scanner. The second
X@code{-S} argument tells @code{mkid} to treat all @file{.Z} files as
Xlanguage @var{man}. In practice, you might find the @code{mkid}
Xarguments need to be even more complex, something like:
X
X@example
Xmkid '-Sman/text/uncompress -c < %s | col -b' -S.Z=man -
X@end example
X
XThis will take the additional step of getting rid of any underlining and
Xbackspacing which might be present in the compressed @var{man} pages.
X
X@node Database Query Tools, Iid, Mkid, Top
X@chapter Database Query Tools
X
XThe ID database is useless without database query tools. The remainder
Xof this document describes those tools.
X
XThe @code{lid}, @code{gid},
X@code{aid}, @code{eid}, and @code{pid} programs are all the same program
Xinstalled with links to different names. The name used to invoke the
Xprogram determines how it will act.
X
XThe @code{iid} program is an interactive query shell that sits on top
Xof the other query tools.
X
X@menu
X* Common Options:: Common command line options
X* Patterns:: Identifier pattern matching
X* Lid:: Look up identifiers
X* Aid:: Case insensitive lid
X* Gid:: Grep for identifiers
X* Eid:: Edit files with matching identifiers
X* Pid:: Look up path names in database
X@end menu
X
X@node Common Options, Patterns, Database Query Tools, Database Query Tools
X@section Common Options
X
XSince many of the programs are really links to one common program, it
Xis only reasonable to expect that most of the query tools would share
Xcommon command line options. Not all options make sense for all programs,
Xbut they are all described here. The description of each program
Xgives the options that program uses.
X
X@table @code
X@item -f@var{<file>}
XRead the database specified by @var{<file>}. Normally the tools look
Xfor a file named @file{ID} in either the current directory or in any
Xof the directories above the current directory. This means you can keep
Xa global @file{ID} database in the root of a large source tree and use
Xthe query tools from anywhere within that tree.
X@item -r@var{<directory>}
XThe query tools usually assume the file names in the database are relative
Xto the directory holding the database. The @code{-r} option tells the
Xtools to look for the files relative to @var{<directory>} regardless
Xof the location of the database.
X@item -c
XThis is shorthand for @code{-r`pwd`}. It tells the query tools to assume
Xthe file names are stored relative to the current working directory.
X@item -e
XForce the pattern arguments to be treated as regular expressions.
XNormally the query tools attempt to guess if the patterns are regular
Xexpressions or simple identifiers by looking for special characters
Xin the pattern.
X@item -w
XForce the pattern arguments to be treated as simple words even if
Xthey contain special regular expression characters.
X@item -k
XNormally the query tools that generate lists of file names attempt to
Xcompress the lists using the @code{csh} brace notation. This option
Xsuppresses the file name compression and outputs each name in full.
X(This is particularly useful if you are a @code{ksh} user and want to
Xfeed the list of names to another command --- the @code{-k} option
Xcomes from the @code{k} in @code{ksh}).
X@item -g
XIt is possible to build the query tools so the @code{-k} option is the
Xdefault behavior. If this is the case for your system, the @code{-g}
Xoption turns on the globbing of file names using the @code{csh} brace
Xnotation.
X@item -n
XNormally the query tools that generate lists of file names also list
Xthe matching identifier at the head of the list of names. This is
Xirritating if you want just a list of names to feed to another command,
Xso the @code{-n} option suppresses the identifier and lists only
Xfile names.
X@item -b
XThis option is only used by the @code{pid} tool. It restricts @code{pid}
Xto pattern match only the basename part of a file name. Normally the
Xabsolute file name is matched against the pattern.
X@item -d -o -x -a
XThese options may be used in any combination to limit the radix of
Xnumeric matches. The @code{-d} option will allow matches on decimal
Xnumbers, @code{-o} on octal, and @code{-x} on hexadecimal numbers.
XThe @code{-a} option is shorthand for specifying all three. Any
Xcombination of these options may be used.
X@item -m
XMerge multiple lines of output into a single line. (If your query
Xmatches more than one identifier the default action is to generate
Xa separate line of output for each matching identifier).
X@item -s
XSearch for identifiers that appear only once in the database. This
Xhelps to locate identifiers that are defined but never used.
X@item -u@var{<number>}
XList identifiers that conflict in the first @var{<number>} characters.
XThis could be useful porting programs to brain-dead computers that
Xrefuse to support long identifiers, but your best long term option
Xis to set such computers on fire.
X@end table
X
X@node Patterns, Lid, Common Options, Database Query Tools
X@section Patterns
X
XYou can attempt to match either simple identifiers or numbers in a
Xquery, or you can specify a regular expression pattern which may
Xmatch many different identifiers in the database. The query
Xprograms use either @var{regex} and @var{regcmp} or @var{re_comp}
Xand @var{re_exec}, depending on which one is available in the library
Xon your system. These might not always support the exact same
Xregular expression syntax, so consult your local @var{man} pages
Xto find out. Any regular expression routines should support the following
Xsyntax:
X
X@table @code
X@item .
XA dot matches any character.
X@item [ ]
XBrackets match any of the characters specified within the brackets. You
Xcan match any characters @emph{except} the ones in brackets by typing
X@code{^} as the first character. A range of characters can be specified
Xusing @code{-}.
X@item *
XAn asterisk means repeat the previous pattern zero or more times.
X@item ^
XAn @code{^} at the beginning of a pattern means the pattern must match
Xstarting at the first character of the identifier.
X@item $
XA @code{$} at the end of the pattern means the pattern must match ending
Xat the last character in the identifier.
X@end table
X
X@node Lid, Aid, Patterns, Database Query Tools
X@section Lid
X
X@deffn Command lid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-ewdoxamskgnc}] patterns@dots{}
X@end deffn
X
XThe @code{lid} program stands for @var{lookup identifier}.
XIt searches the database for any identifiers matching the patterns
Xand prints the names of the files that match each pattern. The exact
Xformat of the output depends on the options.
X
X@node Aid, Gid, Lid, Database Query Tools
X@section Aid
X
X@deffn Command aid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-doxamskgnc}] patterns@dots{}
X@end deffn
X
XThe @code{aid} command is an abbreviation for @var{apropos identifier}.
XThe patterns cannot be regular expressions, but it looks for them using
Xa case insensitive match, and any pattern that is a substring of an
Xidentifier in the database will match that identifier.
X
XFor example @samp{aid get} might match the identifiers @code{fgets},
X@code{GETLINE}, and @code{getchar}.
X
X@node Gid, Eid, Aid, Database Query Tools
X@section Gid
X
X@deffn Command gid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-doxasc}] patterns@dots{}
X@end deffn
X
XThe @code{gid} command stands for @var{grep for identifiers}. It finds
Xidentifiers in the database that match the specified patterns, then
X@code{greps} for those identifiers in just the set of files containing
Xmatches. In a large source tree, this saves a fantastic amount of time.
X
XThere is an @var{emacs} interface to this program (@pxref{Gnuemacs Interface}).
XIf you are an @var{emacs} user, you will probably prefer the @var{emacs}
Xinterface over the @code{eid} tool.
X
X@node Eid, Pid, Gid, Database Query Tools
X@section Eid
X
X@deffn Command eid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-doxasc}] patterns@dots{}
X@end deffn
X
XThe @code{eid} command allows you to invoke an editor on each file containing
Xa matching pattern. The @code{EDITOR} environment variable is the name of the
Xprogram to be invoked. If the specified editor can accept an initial search
Xargument on the command line, you can use the @code{EIDARG}, @code{EIDLDEL},
Xand @code{EIDRDEL} environment variables to specify the form of that argument.
X
X@table @code
X@item EDITOR
XThe name of the editor program to invoke.
X@item EIDARG
XA printf string giving the form of the argument to pass containing the
Xinitial search string (the matching identifier). For @code{vi}
Xit should be set to @samp{+/%s/'}.
X@item EIDLDEL
XA string giving the regular expression pattern that forces a match at
Xthe beginning (left end) of a word. This string is inserted in front
Xof the matching identifier when composing the search argument. For @code{vi},
Xthis should be @samp{\<}.
X@item EIDRDEL
XThe matching right end word delimiter. For @code{vi}, use @samp{\>}.
X@end table
X
X@node Pid, , Eid, Database Query Tools
X@section Pid
X
X@deffn Command pid [@code{-f@var{<file>}}] [@code{-u@var{<n>}}] [@code{-r@var{<dir>}}] [@code{-ebkgnc}] patterns@dots{}
X@end deffn
X
XThe @code{pid} tool is unlike all the other tools. It matches the
Xpatterns against the file names in the database rather than the
Xidentifiers in the database. Patterns are treated as shell wild card
Xpatterns unless the @code{-e} option is given, in which case full
Xregular expression matching is done.
X
XThe wild card pattern is matched against the absolute path name of the
Xfile. Most shells treat slashes @samp{/} and file names that start with
Xdot @samp{.} specially, @code{pid} does not do this. It simply attempts
Xto match the absolute path name string against the wild card pattern.
X
XThe @code{-b} option restricts the pattern matching to the base name of
Xthe file (all the leading directory names are stripped prior to pattern
Xmatching).
X
X@node Iid, Other Tools, Database Query Tools, Top
X@chapter Iid
X
X@deffn Command iid [@code{-a}] [@code{-c@var{<command>}}] [@code{-H}]
X@table @code
X@item -a
XNormally @code{iid} uses the @code{lid} command to search for names.
XIf you give the @code{-a} option on the command line, then it will
Xuse @code{aid} as the default search engine.
X@item -c@var{<command>}
XIn normal operation, @code{iid} starts up and prompts you for commands
Xused to build sets of files. The @code{-c} option is used to pass a
Xsingle query command to @code{iid} which it then executes and exits.
X@item -H
XThe @code{-H} option prints a short help message and exits. To get more
Xhelp use the @code{help} command from inside @code{iid}.
X@end table
X@end deffn
X
XThe @code{iid} program is an interactive ID query tool. It operates by
Xrunning the other query programs (such as @code{lid} and @code{aid})
Xand creating sets of file names returned by these queries. It also
Xprovides operators for @code{anding} and @code{oring} these sets to
Xcreate new sets.
X
XThe @code{PAGER} environment variable names the program @code{iid} uses
Xto display files. If you use @code{emacs}, you might want to set
X@code{PAGER} so it invokes the @code{emacsclient} program. Check the
Xfile @file{lisp/server.el} in the emacs source tree for documentation on
Xthis. It is useful not only with X windows, but also when running
X@code{iid} from an emacs shell buffer. There is also a somewhat spiffier
Xversion called gnuserv by Andy Norman
X(@code{ange%anorman@@hplabs.hp.com}) which appeared in @file{comp.emacs}
Xsometime in 1989.
X
X@menu
X* Ss and Files commands:: Ss and Files commands
X* Sets:: Sets
X* Show:: Show
X* Begin:: Begin
X* Help:: Help
X* Off:: Off
X* Shell Commands as Queries:: Shell Commands as Queries
X* Shell Escape:: Shell Escape
X@end menu
X
X@node Ss and Files commands, Sets, Iid, Iid
X@section Ss and Files commands
X
XThe primary query commands are @code{ss} (for select sets) and @code{files}
X(for show file names). These commands both take a query expression as an
Xargument.
X
X@deffn Subcommand ss query
XThe @code{ss} command runs a query and builds a set (or sets) of file names. The
Xresult is printed as a summary of the sets constructed showing how many file
Xnames are in each set.
X@end deffn
X
X@deffn Subcommand files query
XThe @code{files} command is like the @code{ss} command, but rather than printing
Xa summary, it displays the full list of matching file names.
X@end deffn
X
X@deffn Subcommand f query
XThe @code{f} command is merely a shorthand notation for @code{files}.
X@end deffn
X
XDatabase queries are simple expressions with operators like @code{and}
Xand @code{or}. Parentheses can be used to group operations. The complete
Xset of operators is summarized below:
X
X@table @code
X@item @var{pattern}
XAny pattern not recognized as one of the keywords in this table is treated
Xas an identifier to be searched for in the database. It is passed as an
Xargument to the default search program (normally @code{lid}, but @code{aid}
Xis used if the @code{-a} option was given when @code{iid} was started).
XThe result of this operation is a set of file names, and it is assigned a
Xunique set number.
X@item lid
X@code{lid} is a keyword. It is used to invoke @code{lid} with the list of
Xidentifiers following it as arguments. This forces the use of @code{lid}
Xregardless of the state of the @code{-a} option (@pxref{Lid}).
X@item aid
XThe @code{aid} keyword is like the @code{lid} keyword, but it forces the
Xuse of the @code{aid} program (@pxref{Aid}).
X@item match
XThe @code{match} operator invokes the @code{pid} program to do pattern
Xmatching on file names rather than identifiers. The set generated contains
Xthe file names that match the specified patterns (@pxref{Pid}).
X@item or
XThe @code{or} operator takes two sets of file names as arguments and generates
Xa new set containing all the files from both sets.
X@item and
XThe @code{and} operator takes two sets of file names and generates a new
Xset containing only files from both sets.
X@item not
XThe @code{not} operator inverts a set of file names, producing the set of
Xall files not in the input set.
X@item set number
XA set number consists of the letter @code{s} followed immediately by a number.
XThis refers to one of the sets created by a previous query operation. During
Xone @code{iid} session, each query generates a unique set number, so any
Xpreviously generated set may be used as part of any new query by referring
Xto the set number.
X@end table
X
XThe @code{not} operator has the highest precedence with @code{and}
Xcoming in the middle and @code{or} having the lowest precedence. The
Xoperator names are recognized using case insensitive matching, so
X@code{AND}, @code{and}, and @code{aNd} are all the same as far as
X@code{iid} is concerned. If you wish to use a keyword as an operand to
Xone of the query programs, you must enclose it in quotes. Any patterns
Xcontaining shell special characters must also be properly quoted or
Xescaped, since the query commands are run by invoking them with the
Xshell.
X
XSummary of query expression syntax:
X
X@example
XA <query> is:
X <set number>
X <identifier>
X lid <identifier list>
X aid <identifier list>
X match <wild card list>
X <query> or <query>
X <query> and <query>
X not <query>
X ( <query> )
X@end example
X
X@node Sets, Show, Ss and Files commands, Iid
X@section Sets
X
X@deffn Subcommand sets
X@end deffn
X
XThe @code{sets} command displays all the sets created so far. Each one
Xis described by the query command that generated it.
X
X@node Show, Begin, Sets, Iid
X@section Show
X
X@deffn Subcommand show set
X@end deffn
X
X@deffn Subcommand p set
X@end deffn
X
XThe @code{show} and @code{p} commands are equivalent. They both accept
Xa set number as an argument and run the program given in the @code{PAGER}
Xenvironment variable with the file names in that set as arguments.
X
X@node Begin, Help, Show, Iid
X@section Begin
X
X@deffn Subcommand begin directory
X@end deffn
X
X@deffn Subcommand b directory
X@end deffn
X
XThe @code{begin} command (and its abbreviated version @code{b}) is used
Xto begin a new @code{iid} session in a different directory (which presumably
Xcontains a different database). It flushes all the sets created so far
Xand switches to the specified directory. It is equivalent to exiting @code{iid},
Xchanging directories in the shell, and running @code{iid} again.
X
X@node Help, Off, Begin, Iid
X@section Help
X
X@deffn Subcommand help
X@end deffn
X
X@deffn Subcommand h
X@end deffn
X
X@deffn Subcommand ?
X@end deffn
X
XThe @code{help}, @code{h}, and @code{?} command are three different ways to
Xask for help. They all invoke the @code{PAGER} program to display a short
Xhelp file.
X
X@node Off, Shell Commands as Queries, Help, Iid
X@section Off
X
X@deffn Subcommand off
X@end deffn
X
X@deffn Subcommand quit
X@end deffn
X
X@deffn Subcommand q
X@end deffn
X
XThese three command (or just an end of file) all cause @code{iid} to exit.
X
X@node Shell Commands as Queries, Shell Escape, Off, Iid
X@section Shell Commands as Queries
X
XWhen the first word on an @code{iid} command is not recognized as a
Xbuiltin @code{iid} command, @code{iid} assumes the command is a shell
Xcommand which will write a list of file names to @var{stdout}. This list
Xof file names is used to generate a new set of files.
X
XAny set numbers that appear as arguments to this command are expanded
Xinto lists of file names prior to running the command.
X
X@node Shell Escape, , Shell Commands as Queries, Iid
X@section Shell Escape
X
XIf a command starts with a bang (@code{!}) character, the remainder of
Xthe line is run as a shell command. Any set numbers that appear as
Xarguments to this command are expanded into lists of file names prior to
Xrunning the command.
X
X@node Other Tools, Command Index, Iid, Top
X@chapter Other Tools
X
XThis chapter describes some support tools that work with the other ID
Xprograms.
X
X@menu
X* Gnuemacs Interface:: Using gid.el
X* Fid:: List identifiers in a file.
X* Idx:: Extract identifiers from source file.
X@end menu
X
X@node Gnuemacs Interface, Fid, Other Tools, Other Tools
X@section Gnuemacs Interface
X
XThe source distribution comes with a file named @file{gid.el}. This is
Xa Gnuemacs interface to the @code{gid} tool. If you put the file where
Xemacs can find it (somewhere in your @code{EMACSLOADPATH}) and
Xput @code{(autoload 'gid "gid" nil t)} in your @file{.emacs} file,
Xyou will be able to invoke the @code{gid} function using
X@kbd{M-x gid}.
X
XThis function prompts you with the word the cursor is on. If you want
Xto search for a different pattern, simply delete the line and type the
Xpattern of interest.
X
XIt runs @code{gid} in a @code{*compilation*} buffer, so the normal
X@code{next-error} function can be used to visit all the places the
Xidentifier is found (@pxref{Compilation,,,emacs,The Gnuemacs Manual}).
X
X@node Fid, Idx, Gnuemacs Interface, Other Tools
X@section Fid
X
X@deffn Command fid [@code{-f@var{<file>}}] file1 [file2]
X@table @code
X@item -f@var{<file>}
XLook in the named database.
X@item @var{file1}
XList the identifiers contained in file1 according to the database.
X@item @var{file2}
XIf a second file is given, list only the identifiers both files have
Xin common.
X@end table
X@end deffn
X
XThe @code{fid} program provides an inverse query. Instead of listing
Xfiles containing some identifier, it lists the identifiers found in
Xa file.
X
X@node Idx, , Fid, Other Tools
X@section Idx
X
X@deffn Command idx [@code{-s@var{<directory>}}] [@code{-r@var{<directory>}}] [@code{-S@var{<scanarg>}}] files@dots{}
XThe @code{-s}, @code{-r}, and @code{-S} arguments to @code{idx}
Xare identical to the same arguments on @code{mkid}
X(@pxref{Mkid Command Line Options}).
X@end deffn
X
XThe @code{idx} command is more of a test frame for scanners than a tool
Xdesigned to be independently useful. It takes the same scanner arguments
Xas @code{mkid}, but rather than building a database, it prints the
Xidentifiers found to @var{stdout}, one per line. You can use it to try
Xout a scanner on a sample file to make sure it is extracting the
Xidentifiers you believe it should extract.
X
X@node Command Index, , Other Tools, Top
X@unnumbered Command Index
X
X@printindex fn
X
X@contents
X@bye
END_OF_FILE
if test 38176 -ne `wc -c <'id.texinfo'`; then
echo shar: \"'id.texinfo'\" unpacked with wrong size!
fi
# end of 'id.texinfo'
fi
echo shar: End of archive 7 \(of 7\).
cp /dev/null ark7isdone
MISSING=""
for I in 1 2 3 4 5 6 7 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 7 archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
exit 0 # Just in case...
--
Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.
Use a domain-based address or give alternate paths, or you may lose out.