diff options
author | Greg McGary <greg@mcgary.org> | 1997-04-18 06:38:38 +0000 |
---|---|---|
committer | Greg McGary <greg@mcgary.org> | 1997-04-18 06:38:38 +0000 |
commit | 509a418a05787df17f1e942593541798facb5acf (patch) | |
tree | 659278333f2a8824e98868867567701117f6151d /id.info | |
parent | 37159f77c7753cb944e4f68436a181bab41d60f1 (diff) | |
download | idutils-509a418a05787df17f1e942593541798facb5acf.tar.gz idutils-509a418a05787df17f1e942593541798facb5acf.tar.bz2 idutils-509a418a05787df17f1e942593541798facb5acf.zip |
Initial revision
Diffstat (limited to 'id.info')
-rw-r--r-- | id.info | 1433 |
1 files changed, 1433 insertions, 0 deletions
@@ -0,0 +1,1433 @@ +This is Info file id.info, produced by Makeinfo-1.55 from the input +file id.texinfo. + +START-INFO-DIR-ENTRY +* ID database: (id). Identifier database utilities. +* aid: (id)aid invocation:: Matching strings. +* eid: (id)eid invocation:: Invoking an editor on matches. +* fid: (id)fid invocation:: Listing a file's identifiers. +* gid: (id)gid invocation:: Listing all matching lines. +* idx: (id)idx invocation:: Testing mkid scanners. +* iid: (id)iid invocation:: Interactive complex queries. +* lid: (id)lid invocation:: Matching patterns. +* mkid: (id)mkid invocation:: Creating an ID database. +* pid: (id)pid invocation:: Looking up filenames. +END-INFO-DIR-ENTRY + + This file documents the `mkid' identifier database utilities. + + Copyright (C) 1991, 1995 Tom Horsley. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice are +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation. + + +File: id.info, Node: Top, Next: Introduction, Prev: (DIR), Up: (DIR) + +ID database utilities +********************* + + This manual documents version 3.0.9 of the ID database utilities. + +* Menu: + +* Introduction:: Overview of the tools, and authors. +* mkid invocation:: Creating an ID database. +* Common query arguments:: Common lookup options and search patterns. +* gid invocation:: Listing all matching lines. +* Looking up identifiers:: lid, aid, eid, and fid. +* pid invocation:: Looking up filenames. +* iid invocation:: Interactive and complex queries. +* Index:: General index. + + +File: id.info, Node: Introduction, Next: mkid invocation, Prev: Top, Up: Top + +Introduction +************ + + An "ID database" is a binary file containing a list of filenames, a +list of identifiers, and a matrix indicating which identifiers appear in +which files. With this database and some tools to manipulate it +(described in this manual), a host of tasks become simpler and faster. +For example, you can list all files containing a particular `#include' +throughout a huge source hierarchy, search for all the memos containing +references to a project, or automatically invoke an editor on all files +containing references to some function. Anyone with a large software +project to maintain, or a large set of text files to organize, can +benefit from an ID database. + + Although the ID utilities are most commonly used with identifiers, +numeric constants are also stored in the database, and can be searched +for in the same way (independent of radix, if desired). + + There are a number of programs in the ID family: + +`mkid' + scans files for identifiers and numeric constants and builds the ID + database file. + +`gid' + lists all lines that match given patterns. + +`lid' + lists the filenames containing identifiers that match given + patterns. + +`aid' + lists the filenames containing identifiers that contain given + strings, independent of case. + +`eid' + invokes an editor on each file containing identifiers that match + given patterns. + +`fid' + lists all identifiers recorded in the database for given files, or + identifiers common to two files. + +`pid' + matches the filenames in the database, rather than the identifiers. + +`iid' + interactively supports more complex queries, such as intersection + and union. + +`idx' + helps with testing of new `mkid' scanners. + + Please report bugs to `gkm@magilla.cichlid.com'. Remember to +include the version number, machine architecture, input files, and any +other information needed to reproduce the bug: your input, what you +expected, what you got, and why it is wrong. Diffs are welcome, but +please include a description of the problem as well, since this is +sometimes difficult to infer. *Note Bugs: (gcc)Bugs. + +* Menu: + +* Past and future:: How the ID tools came about, and where they're going. + + +File: id.info, Node: Past and future, Up: Introduction + +Past and future +=============== + + Greg McGary conceived of the ideas behind mkid when he began hacking +the Unix kernel in 1984. He needed a navigation tool to help him find +his way the expansive, unfamiliar landscape. The first `mkid'-like +tools were shell scripts, and produced an ASCII database that looks much +like the output of `lid' with no arguments. It took over an hour on a +VAX 11/750 to build a database for a 4.1BSD-ish kernel. Lookups were +done with the system utility `look', modified to handle very long lines. + + In 1986, Greg rewrote `mkid', `lid', `fid' and `idx' in C to improve +performance. Database-build times were shortened by an order of +magnitude. The `mkid' tools were first posted to `comp.sources.unix' +in September 1987. + + Over the next few years, several versions diverged from the original +source. Tom Horsley at Harris Computer Systems Division stepped forward +to take over maintenance and integrated some of the fixes from divergent +versions. He also wrote the `iid' program. A first release of `mkid' +version 2 was posted to `alt.sources' near the end of 1990. At that +time, Tom wrote this Texinfo manual with the encouragement the net +community. (Tom especially thanks Doug Scofield and Bill Leonard whom +he dragooned into helping poorfraed and edit--they found several +problems in the initial version.) Karl Berry revamped the manual for +Texinfo style, indexing, and organization in 1995. + + In January 1995, Greg McGary reemerged as the primary maintaner and +launched development of `mkid' version 3, whose primary new feature is +an efficient algorithm for building databases that is linear in both +time and space over the size of the input text. (The old algorithm was +quadratic in space and therefore choked on very large source trees.) +The code is released under the GNU Public License, and might become a +part of the GNU system. `mkid' 3 is an interim release, since several +significant enhancements are still in the works: an optional coupling +with GNU `grep', so that `grep' can use an ID database for hints; a +`cscope' work-alike query interface; incremental update of the ID +database; and an automatic file-tree walker so you need not explicitly +supply every filename argument to the `mkid' program. + + +File: id.info, Node: mkid invocation, Next: Common query arguments, Prev: Introduction, Up: Top + +`mkid': Creating ID databases +***************************** + + The `mkid' program builds an ID database. To do this, it must scan +each file you tell it to include in the database. This takes some time, +but once the work is done the query programs run very rapidly. (You can +run `mkid' as a `cron' job to regularly update your databases.) + + The `mkid' program knows how to extract identifiers from various +types of files. For example, it can recognize and skip over comments +and string constants in a C program. + + Identifiers are not the only thing included in the database. Numbers +are also recognized and included in the database indexed by their binary +value. This feature allows you to find uses of constants without regard +to the radix used to specify them, since the same number can frequently +be written in many different ways (for instance, `47', `0x2f', `057' in +C). + + All the places in this document which mention identifiers should +really mention both identifiers and numbers, but that gets fairly +clumsy after a while, so you just need to keep in mind that numbers are +included in the database as well as identifiers. + + The ID files that `mkid' creates are architecture- and +byte-order-independent; you can share them at will across systems. + +* Menu: + +* mkid options:: Command-line options to mkid. +* Scanners:: Built-in and defining your own. +* mkid examples:: Examples of mkid usage. + + +File: id.info, Node: mkid options, Next: Scanners, Up: mkid invocation + +`mkid' options +============== + + By default, `mkid' scans the files you specify and writes the +database to a file named `ID' in the current directory. + + mkid [-v] [-SSCANARG] [-aARGFILE] [-] [-fIDFILE] FILES... + + The program accepts the following options. + +`-v' + Verbose. `mkid' tells you as it scans each file and indicates + which scanner it is using. It also summarizes some statistics + about the database at the end. + +`-SSCANARG' + Specify options regarding `mkid''s scanners. *Note Scanner option + formats::. + +`-aARGFILE' + Read additional command line arguments from ARGFILE. This is + typically used to specify lists of filenames longer than will fit + on a command line; some systems have severe limitations on the + total length of a command line. + +`-' + Read additional command line arguments from standard input. + +`-fIDFILE' + Write the database to the file IDFILE, instead of `ID'. The + database stores filenames relative to the directory containing the + database, so if you move the database to a different directory + after creating it, you may have trouble finding files. + + The remaining arguments FILES are the files to be scanned and +included in the database. If no files are given at all (either on +command line or via `-a' or `-'), `mkid' does nothing. + + +File: id.info, Node: Scanners, Next: mkid examples, Prev: mkid options, Up: mkid invocation + +Scanners +======== + + To determine which identifiers to extract from a file and store in +the database, `mkid' calls a "scanner"; we say a scanner "recognizes" a +particular language. Scanners for several languages are built-in to +`mkid'; you can add your own scanners as well, as explained in the +sections below. + + `mkid' determines which scanner to use for a particular file by +looking at the suffix of the filename. This "suffix" is everything +after and including the last `.' in a filename; for example, the suffix +of `foo.c' is `.c'. `mkid' has a built-in list of bindings from some +suffixes to corresponding scanners; for example, `.c' files are (not +surprisingly) scanned by the predefined C language scanner. + + If `mkid' cannot determine what scanner to use for a particular +file, either because the file has no suffix (e.g., `foo') or because +`mkid' has no binding for the file's suffix (e.g., `foo.bar'), it uses +the scanner bound to the `.default' suffix. By default, this is the +plain text scanner (*note Plain text scanner::.), but you can change +this with the `-S' option, as explained below. + +* Menu: + +* Scanner option formats:: Overview of the -S option. +* Predefined scanners:: The C, plain text, and assembler scanners. +* Defining new scanners:: Either in source code or at runtime with -S. +* idx invocation:: Testing mkid scanners. + + +File: id.info, Node: Scanner option formats, Next: Predefined scanners, Up: Scanners + +Scanner option formats +---------------------- + + With the `-S' option, you can change which language scanner to use +for which files, give language-specific options, and get some limited +online help about scanner options. + + Here are the different forms of the `-S' option: + +`-S.SUFFIX=SCANNER' + Use SCANNER for a file with the given `.SUFFIX'. For example, + `-S.yacc=c' tells `mkid' to use the `c' language scanner for all + files ending in `.yacc'. + +`-S.SUFFIX=?' + Display which scanner is used for the given `.SUFFIX'. + +`-S?=SCANNER' + Display which suffixes SCANNER is used for. + +`-S?=?' + Display the scanner binding for every known suffix. + +`-SSCANNER+ARG' +`-SSCANNER-ARG' + Each scanner accepts certain scanner-dependent arguments. These + options all have one of these forms. *Note Predefined scanners::. + +`-SSCANNER?' + Display the scanner-specific options accepted by SCANNER. + +`-SNEW-SCANNER/OLD-SCANNER/FILTER-COMMAND' + Define NEW-SCANNER in terms of OLD-SCANNER and FILTER-COMMAND. + *Note Defining scanners with options::. + + +File: id.info, Node: Predefined scanners, Next: Defining new scanners, Prev: Scanner option formats, Up: Scanners + +Predefined scanners +------------------- + + `mkid' has built-in scanners for several types of languages; you can +get the list by running `mkid -S?=?'. The supported languages are +documented below(1). + +* Menu: + +* C scanner:: For the C programming language. +* Plain text scanner:: For documents or other non-source code. +* Assembler scanner:: For assembly language. + + ---------- Footnotes ---------- + + (1) This is not strictly true: `vhil' is a supported language, but +it is an obsolete and arcane dialect of C and should be ignored. + + +File: id.info, Node: C scanner, Next: Plain text scanner, Up: Predefined scanners + +C scanner +......... + + The C scanner is the most commonly used. Files with the usual `.c' +and `.h' suffixes, and the `.y' (yacc) and `.l' (lex) suffixes, are +processed with this scanner (by default). + + Scanner-specific options: + +`-Sc-sCHARACTER' + Allow the specified CHARACTER in identifiers. For example, if you + use `$' in identifiers, you'll want to use `-Sc-s$'. + +`-Sc+u' + Strip leading underscores from identifiers. You might to do this in + peculiar circumstances, such as trying to parse the output from + `nm' or some other system utility. + +`-Sc-u' + Don't strip leading underscores from identifiers; this is the + default. + + +File: id.info, Node: Plain text scanner, Next: Assembler scanner, Prev: C scanner, Up: Predefined scanners + +Plain text scanner +.................. + + The plain text scanner is intended for scanning most non-source-code +files. This is typically the scanner used when adding custom scanners +via `-S' (*note Defining scanners with options::.). + + Scanner-specific options: + +`-Stext+aCHARACTER' + Include CHARACTER in identifiers. By default, letters (a-z and + A-Z) and underscore are included. + +`-Stext-aCHARACTER' + Exclude CHARACTER from identifiers. + +`-Stext+sCHARACTER' + Squeeze CHARACTER from identifiers, i.e., do not terminate an + identifier when CHARACTER is seen. By default, the characters + `'', `-', and `.' are squeezed out of identifiers. For example, + the input `fred's' leads to the identifier `freds'. + +`-Stext-sCHARACTER' + Do not squeeze CHARACTER. + + +File: id.info, Node: Assembler scanner, Prev: Plain text scanner, Up: Predefined scanners + +Assembler scanner +................. + + Since assembly languages come in several flavors, this scanner has a +number of options: + +`-Sasm-cCHARACTER' + Define CHARACTER as starting a comment that extends to the end of + the input line; no default. In many assemblers this is `;' or `#'. + +`-Sasm+u' +`-Sasm-u' + Strip (`+u') or do not strip (`-u') leading underscores from + identifiers. The default is to strip them. + +`-Sasm+aCHARACTER' + Allow CHARACTER in identifiers. + +`-Sasm-aCHARACTER' + Allow CHARACTER in identifiers, but if an identifier contains + CHARACTER, ignore it. This is useful to ignore temporary labels, + which can be generated in great profusion; these often contain `.' + or `@'. + +`-Sasm+p' +`-Sasm-p' + Recognize (`+p') or do not recognize (`-p') C preprocessor + directives in assembler source. The default is to recognize them. + +`-Sasm+C' +`-Sasm-C' + Skip over (`+C') or do not skip over (`-C') C style comments in + assembler source. The default is to skip them. + + +File: id.info, Node: Defining new scanners, Next: idx invocation, Prev: Predefined scanners, Up: Scanners + +Defining new scanners +--------------------- + + You can add new scanners to `mkid' in two ways: modify the source +code and recompile, or at runtime via the `-S' option. Each has their +advantages and disadvantages, as explained below. + + If you create a new scanner that would be of use to others, please +consider sending it back to the maintainer, `gkm@magilla.cichlid.com', +for inclusion in future releases of `mkid'. + +* Menu: + +* Defining scanners in source code:: +* Defining scanners with options:: + + +File: id.info, Node: Defining scanners in source code, Next: Defining scanners with options, Up: Defining new scanners + +Defining scanners in source code +................................ + + To add a new scanner in source code, you should add a new section to +the file `scanners.c'. Copy one of the existing scanners (most likely +either C or plain text), and modify as necessary. Also add the new +scanner to the `languages_0' and `suffixes_0' tables near the beginning +of the file. + + This is not a terribly difficult programming task, but it requires +recompiling and installing the new version of `mkid', which may be +inconvenient. + + This method leads to scanners which operate much more quickly than +ones that depend on external programmers. It is also likely the +easiest way to define scanners for new programming languages. + + +File: id.info, Node: Defining scanners with options, Prev: Defining scanners in source code, Up: Defining new scanners + +Defining scanners with options +.............................. + + You can use the `-S' option on the command line to define a new +language scanner: + + -SNEW-SCANNER/EXISTING-SCANNER/FILTER + +Here, NEW-SCANNER is the name of the new scanner being defined, +EXISTING-SCANNER is the name of an existing scanner, and FILTER is a +shell command or pipeline. + + The new scanner works by passing the input file to FILTER, and then +arranging for the result to be passed through EXISTING-SCANNER. +Typically, EXISTING-SCANNER is `text'. + + Somewhere within FILTER, the string`%s' should occur. This `%s' is +replaced by the name of the source file being scanned. + + For example, `mkid' has no built-in scanner for Texinfo files (like +this one). In indexing a Texinfo file, you most likely would want to +ignore the Texinfo @-commands. Here's one way to specify a new scanner +to do this: + + -S/texinfo/text/sed s,@[a-z]*,,g %s + + This defines a new language scanner (`texinfo') defined in terms of +a `sed' command to strip out Texinfo directives (an `@' character +followed by letters). Once the directives are stripped, the remaining +text is run through the plain text scanner. + + This is a minimal example; to do a complete job, you would need to +completely delete some lines, such as those beginning with `@end' or +@node. + + +File: id.info, Node: idx invocation, Prev: Defining new scanners, Up: Scanners + +`idx': Testing `mkid' scanners +------------------------------ + + `idx' prints the identifiers found in the files you specify to +standard output. This is useful in debugging new `mkid' scanners (*note +Scanners::.). Synopsis: + + idx [-SSCANARG] FILES... + + `idx' accepts the same `-S' options as `mkid'. *Note Scanner option +formats::. + + The name "idx" stands for "ID eXtract". The name may change in +future releases, since this is such an infrequently used program. + + +File: id.info, Node: mkid examples, Prev: Scanners, Up: mkid invocation + +`mkid' examples +=============== + + The simplest example of `mkid' is something like: + + mkid *.[chy] + + This will build an ID database indexing identifiers and numbers in +the all the `.c', `.h', and `.y' files in the current directory. +Because `mkid' already knows how to scan files with those suffixes, no +additional options are needed. + + Here's a more complex example. Suppose you want to build a database +indexing the contents of all the `man' pages, and furthur suppose that +your system is using `gzip' (*note Top: (gzip)Top.) to store compressed +`cat' versions of the `man' pages in the directory `/usr/catman'. The +`gzip' program creates files with a `.gz' suffix, so you must tell +`mkid' how to scan `.gz' files. Here are the commands to do the job: + + cd /usr/catman + find . -name \*.gz -print | mkid '-Sman/text/gzip <%s' -S.gz=man - + +Explanation: + + 1. We first `cd' to `/usr/catman' so the ID database will store the + correct relative filenames. + + 2. The `find' command prints the names of all `.gz' files under the + current directory. *Note find invocation: (sh-utils)find + invocation. + + 3. This list is piped to `mkid'; the `-' option (at the end of the + line) tells `mkid' to read arguments (in this case, as is typical, + the list of filenames) from standard input. *Note mkid options::. + + 4. The `-Sman/text/gzip ...' defines a new language `man' in terms of + the `gzip' program and `mkid''s existing text scanner. *Note + Defining scanners with options::. + + 5. The `-S.gz=man' tells `mkid' to treat all `.gz' files as this new + language `man'. *Note Scanner option formats::. + + + As a further complication, `cat' pages typically contain underlining +and backspace sequences, which will confuse `mkid'. To handle this, +the `gzip' command becomes a pipeline, like this: + + mkid '-Sman/text/gzip <%s | col -b' -S.gz=man - + + +File: id.info, Node: Common query arguments, Next: gid invocation, Prev: mkid invocation, Up: Top + +Common query arguments +********************** + + Certain options, and regular expression syntax, are shared by the ID +query tools. So we describe those things in the sections below, instead +of repeating the description for each tool. + +* Menu: + +* Query options:: -f -r -c -ew -kg -n -doxa -m -F -u. +* Patterns:: Regular expression syntax for searches. +* Examples: Query examples. Some common uses. + + +File: id.info, Node: Query options, Next: Patterns, Up: Common query arguments + +Query options +============= + + The ID query tools (*not* `mkid') share certain command line +options. Not all of these options are recognized by all programs, but +if an option is used by more than one program, it is described below. +The description of each program gives the options that program uses. + +`-fIDFILE' + Read the database from IDFILE, in the current directory or in any + directory above the current directory. The default database name + is `ID'. Searching parent directories lets you have a single ID + database at the root of a large source tree and then use the query + tools from anywhere within that tree. + +`-rDIRECTORY' + Find files relative to DIRECTORY, instead of the directory in + which the ID database was found. This is useful if the ID + database was moved after its creation. + +`-c' + Equivalent to `-r`pwd`', i.e., find files relative to the current + directory, instead of the directory in which the ID database was + found. + +`-e' +`-w' + `-e' forces pattern arguments to be treated as regular expressions, + and `-w' forces pattern arguments to be treated as constant + strings. By default, the query tools guess whether a pattern is + regular expressions or constant strings by looking for special + characters. *Note Patterns::. + +`-k' +`-g' + `-k' suppresses use of shell brace notation in the output. By + default, the query tools that generate lists of filenames attempt + to compress the lists using the usual shell brace notation, e.g., + `{foo,bar}.c' to mean `foo.c' and `bar.c'. (This is useful if you + use `ksh' or the original (not GNU) `sh' and want to feed the list + of names to another command, since those shells do not support + this brace notation; the name of the `-k' option comes from the + `k' in `ksh'). + + `-g' turns on use of brace notation; this is only needed if the + query tools were compiled with `-k' as the default behavior. + +`-n' + Suppress the matching identifier before each list of filenames + that the query tools output by default. This is useful if you want + a list of just the names to feed to another command. + +`-d' +`-o' +`-x' +`-a' + These options may be used in any combination to specify the radix + of numeric matches. `-d' allows matching on decimal numbers, `-o' + on octal numbers, and `-x' on hexadecimal numbers. The `-a' + option is equivalent to specifying all three; this is the default. + Any combination of these options may be used. + +`-m' + Merge multiple lines of output into a single line. If your query + matches more than one identifier, the default is to generate a + separate line of output for each matching identifier. + +`-F-' +`-FN' +`-F-M' +`-FN-M' + Show identifiers matching at least N and at most M times. `-F-' + is equivalent to `-F1', i.e., find identifiers that appear only + once in the database. (This is useful to locate identifiers that + are defined but never used, or used once and never defined.) + +`-uNUMBER' + List identifiers that conflict in the first NUMBER characters. + This could be in useful porting programs to brain-dead computers + that refuse to support long identifiers, but your best long term + option is to set such computers on fire. + + +File: id.info, Node: Patterns, Next: Query examples, Prev: Query options, Up: Common query arguments + +Patterns +======== + + "Patterns", also called "regular expressions", allow you to match +many different identifiers in a single query. + + The same regular expression syntax is recognized by all the query +tools that handle regular expressions. The exact syntax depends on how +the ID tools were compiled, but the following constructs should always +be supported: + +`.' + Match any single character. + +`[CHARS]' + Match any of the characters specified within the brackets. You can + match any characters *except* the ones in brackets by typing `^' + as the first character. A range of characters can be specified + using `-'. For example, `[abc]' and `[a-c]' both match `a', `b', + or `c', and `[^abc]' matches anything *except* `a', `b', or `c'. + +`*' + Match the previous construct zero or more times. + +`^' +`$' + `^' (`$') at the beginning (end) of a pattern anchors the match to + the first (last) character of the identifier. + + The query programs use either the `regex'/`regcmp' or +`re_comp'/`re_exec' functions, depending on which are available in the +library on your system. These do not always support the exact same +regular expression syntax, so consult your local `man' pages to find +out. + + +File: id.info, Node: Query examples, Prev: Patterns, Up: Common query arguments + +Query examples +============== + + Here are some examples of the options described in the previous +sections. + + To restrict searches to exact matches, use `^...$'. For example: + + prompt$ gid '^FILE$' + ansi2knr.c:144: { FILE *in, *out; + ansi2knr.c:315: FILE *out; + fid.c:38: FILE *id_FILE; + filenames.c:576: FILE * + ... + + To show identifiers not unique in the first 16 characters: + + prompt$ lid -u16 + RE_CONTEXT_INDEP_ANCHORS regex.c + RE_CONTEXT_INDEP_OPS regex.c + RE_SYNTAX_POSIX_BASIC regex.c + RE_SYNTAX_POSIX_EXTENDED regex.c + ... + + Numbers are searched for numerically rather than textually. For +example: + + prompt$ lid 0xff + 0377 {lid,regex}.c + 0xff {bitops,fid,lid,mkid}.c + 255 regex.c + + On the other hand, you can restrict a numeric search to a particular +radix if you want: + + laurie$ lid -x 0xff + 0xff {bitops,fid,lid,mkid}.c + + Filenames in the output are always adjusted to be correct for the +correct working directory. For example: + + prompt$ lid bdevsw + bdevsw sys/conf.h cf/conf.c io/bio.c os/{fio,main,prf,sys3}.c + prompt$ cd io + prompt$ lid bdevsw + bdevsw ../sys/conf.h ../cf/conf.c bio.c ../os/{fio,main,prf,sys3}.c + + +File: id.info, Node: gid invocation, Next: Looking up identifiers, Prev: Common query arguments, Up: Top + +`gid': Listing matching lines +***************************** + + Synopsis: + + gid [-fFILE] [-uN] [-rDIR] [-doxasc] [PATTERN...] + + `gid' finds the identifiers in the database that match the specified +PATTERNs, then searches for all occurrences of those identifiers, in +only the files containing matches. In a large source tree, this saves +an enormous amount of time (compared to searching every source file). + + With no PATTERN arguments, `gid' prints every line of every source +file. + + The name "gid" stands for "grep for identifiers", `grep' being the +standard utility to search regular files. + + *Note Common query arguments::, for a description of the command-line +options and PATTERN arguments. + + `gid' uses the standard GNU output format for identifying source +lines: + + FILENAME:LINENUM: TEXT + + Here is an example: + + prompt$ gid FILE + ansi2knr.c:144: { FILE *in, *out; + ansi2knr.c:315: FILE *out; + fid.c:38: FILE *id_FILE; + ... + +* Menu: + +* GNU Emacs gid interface:: Using next-error with gid. + + +File: id.info, Node: GNU Emacs gid interface, Up: gid invocation + +GNU Emacs `gid' interface +========================= + + The `mkid' source distribution comes with a file `gid.el', which +defines a GNU Emacs interface to `gid'. To install it, put `gid.el' +somewhere that Emacs will find it (i.e., in your `load-path') and put + + (autoload 'gid "gid" nil t) + +in one of Emacs' initialization files, e.g., `~/.emacs'. You will then +be able to use `M-x gid' to run the command. + + The `gid' function prompts you with the word around point. If you +want to search for something else, simply delete the line and type the +pattern of interest. + + The function then runs the `gid' program in a `*compilation*' +buffer, so the normal `next-error' function can be used to visit all +the places the identifier is found (*note Compilation: +(emacs)Compilation.). + + +File: id.info, Node: Looking up identifiers, Next: pid invocation, Prev: gid invocation, Up: Top + +Looking up identifiers +********************** + + These commands look up identifiers in the ID database and operate on +the files containing matches. + +* Menu: + +* lid invocation:: Matching patterns. +* aid invocation:: Matching strings. +* eid invocation:: Invoking an editor on matches. +* fid invocation:: Listing a file's identifiers. + + +File: id.info, Node: lid invocation, Next: aid invocation, Up: Looking up identifiers + +`lid': Matching patterns +======================== + + Synopsis: + + lid [-fFILE] [-uN] [-rDIR] [-mewdoxaskgnc] PATTERN... + + `lid' searches the database for identifiers matching the given +PATTERN arguments and prints the names of the files that match each +PATTERN. With no PATTERNs, `lid' lists every entry in the database. + + The name "lid" stands for "lookup identifier". + + *Note Common query arguments::, for a description of the command-line +options and PATTERN arguments. + + By default, each line of output consists of an identifier and all the +files containing that identifier. + + Here is an example showing a search for a single identifier (omitting +some output to keep lines short): + + prompt$ lid FILE + FILE extern.h {fid,gets0,getsFF,idx,init,lid,mkid,...}.c + + This example shows a regular expression search: + + prompt$ lid 'FILE$' + AF_FILE mkid.c + AF_IDFILE mkid.c + FILE extern.h {fid,gets0,getsFF,idx,init,lid,mkid,...}.c + IDFILE id.h {fid,lid,mkid}.c + IdFILE {fid,lid}.c + ... + +As you can see, when a regular expression is used, it is possible to +get more than one line of output. To merge multiple lines into one, +use `-m': + + prompt$ lid -m ^get + ^get extern.h {bitsvec,fid,gets0,getsFF,getscan,idx,lid,...}.c + + +File: id.info, Node: aid invocation, Next: eid invocation, Prev: lid invocation, Up: Looking up identifiers + +`aid': Matching strings +======================= + + Synopsis: + + aid [-fFILE] [-uN] [-rDIR] [-mewdoxaskgnc] STRING... + + `aid' searches the database for identifiers containing the given +STRING arguments. The search is case-insensitive. + + The name "aid" stands for "apropos identifier", `apropros' being a +command that does a similar search of the `whatis' database of `man' +descriptions. + + For example, `aid get' matches the identifiers `fgets', `GETLINE', +and `getchar'. + + The default output format is the same as `lid'; see the previous +section. + + *Note Common query arguments::, for a description of the command-line +options and PATTERN arguments. + + +File: id.info, Node: eid invocation, Next: fid invocation, Prev: aid invocation, Up: Looking up identifiers + +`eid': Invoking an editor on matches +==================================== + + Synopsis: + + eid [-fFILE] [-uN] [-rDIR] [-doxasc] [PATTERN]... + + `eid' runs the usual search (*note lid invocation::.) on the given +arguments, shows you the output, and then asks: + + Edit? [y1-9^S/nq] + +You can respond with: + +`y' + Edit all files listed. + +`1...9' + Start editing at the N + 1'st file. + +`/STRING or `CTRL-S'STRING' + Start editing at the first filename containing STRING. + +`n' + Go on to the next PATTERN, i.e., edit nothing for this one. + +`q' + Quit `eid'. + + `eid' invokes the editor defined by the `EDITOR' environment +variable to edit a file. If this editor can accept an initial search +argument on the command line, `eid' can move automatically to the +location of the match, via the environment variables below. + + *Note Common query arguments::, for a description of the command-line +options and PATTERN arguments. + + Here are the environment variables relevant to `eid': + +`EDITOR' + The name of the editor program to invoke. + +`EIDARG' + The argument to pass to the editor to search for the matching + identifier. For `vi', this should be `+/%s/''. + +`EIDLDEL' + A regular expression to force a match at the beginning of a word + ("left delimiter). `eid' inserts this in front of the matching + identifier when composing the search argument. For `vi', this + should be `\<'. + +`EIDRDEL' + The end-of-word regular expression. For `vi', this should be `\>'. + + For Emacs users, the interface in `gid.el' is probably preferable to +`eid'. *Note GNU Emacs gid interface::. + + Here is an example: + + prompt$ eid FILE \^print + FILE {ansi2knr,fid,filenames,idfile,idx,iid,lid,misc,...}.c + Edit? [y1-9^S/nq] n + ^print {ansi2knr,fid,getopt,getopt1,iid,lid,mkid,regex,scanners}.c + Edit? [y1-9^S/nq] 2 + +This will start editing at `getopt'.c. + + +File: id.info, Node: fid invocation, Prev: eid invocation, Up: Looking up identifiers + +`fid': Listing a file's identifiers +=================================== + + `fid' lists the identifiers found in a given file. Synopsis: + + fid [-fDBFILE] FILE1 [FILE2] + +`-fDBFILE' + Read the database from DBFILE instead of `ID'. + +`FILE1' + List all the identifiers contained in FILE1. + +`FILE2' + With a second file argument, list only the identifiers both files + have in common. + + The output is simply one identifier (or number) per line. + + +File: id.info, Node: pid invocation, Next: iid invocation, Prev: Looking up identifiers, Up: Top + +`pid': Looking up filenames +*************************** + + `pid' matches the filenames stored in the ID database, rather than +the identifiers. Synopsis: + + pid [-fDBFILE] [-rDIR] [-ebkgnc] WILDCARD... + + By default, the WILDCARD patterns are treated as shell globbing +patterns, rather than the regular expressions the other utilities +accept. See the section below for details. + + Besides the standard options given in the synopsis (*note Query +options::.), `pid' accepts the following: + +`-e' + Do the usual regular expression matching (*note Patterns::.), + instead of shell wildcard matching. + +`-b' + Match the basenames of the files in the database. For example, + `pid -b foo' will match the stored filename `dir/foo', but not + `foo/file'. + + For example, the command: + + pid \*.c + +lists all the `.c' files in the database. (The `\' here protects the +`*' from being expanded by the shell.) + +* Menu: + +* Wildcard patterns:: Shell-style globbing patterns. + + +File: id.info, Node: Wildcard patterns, Up: pid invocation + +Wildcard patterns +================= + + `pid' does simplified shell wildcard matching (unless the `-e' +option is specified), rather than the regular expression matching done +by the other utilities. Here is a description of wildcard matching, +also called "globbing": + + * `*' matches zero or more characters. + + * `?' matches any single character. + + * `\' forces the next character to be taken literally. + + * `[CHARS]' matches any single character listed in CHARS. + + * `[!CHARS]' matches any character *not* listed in CHARS. + + Most shells treat `/' and leading `.' characters specially. `pid' +does not do this. It simply matches the filename in the database +against the wildcard pattern. + + +File: id.info, Node: iid invocation, Next: Index, Prev: pid invocation, Up: Top + +`iid': Complex interactive queries +********************************** + + `iid' is an interactive query utility for ID databases. It operates +by running another query program (`lid' by default, `aid' if `-a' is +specified) and manipulating the sets of filenames returned by these +queries. + +* Menu: + +* iid command line options:: Command-line options. +* iid query expressions:: Operands to the commands. +* iid commands:: Printing matching filenames, etc. + + +File: id.info, Node: iid command line options, Next: iid query expressions, Up: iid invocation + +`iid' command line options +========================== + + `iid' recognizes the following options (the standard query options +described in *Note Query options:: are inapplicable): + +`-a' + Use `aid' for searches, instead of `lid'. + +`-cCOMMAND' + Execute COMMAND and exit, instead of prompting for interactive + commands. + +`-H' + Print a usage message and exit successfully. The `help' command + inside `iid' gives more information. *Note iid commands::. + + +File: id.info, Node: iid query expressions, Next: iid commands, Prev: iid command line options, Up: iid invocation + +`iid' query expressions +======================= + + An `iid' "query expression" generates a set of filenames or +manipulates existing sets. These expressions are operands to some of +the `iid' commands (see the next section), not commands themselves. + + Here are the possible constructs, highest precedence first: + +`sSET-NUMBER' + Refer to a set previously created by a query operation. During + each `iid' session, every query generates a different set number, + so any previously generated set may be used as part of any new + query by reference to its set number. + +`PATTERN' + `iid' treats any non-keyword input (i.e., anything not in this + table) as an identifier to be searched for in the database. It is + passed to the search program (`lid' by default, `aid' if the `-a' + option was specified). The result of this operation is a set of + filenames, and it is assigned a unique set number. + +`lid IDENTIFIER-LIST' + Invoke the `lid' program on IDENTIFIER-LIST and construct a new + set from the result. + +`aid IDENTIFIER-LIST' + Like `lid', but use the `aid' program. + +`match WILDCARDS' + Invoke the `pid' program on WILDCARDS, therefore matching on the + filenames in the database instead of the identifiers. The + resulting set contains the filenames that match the specified + patterns. *Note pid invocation::. + +`not EXPR' + The result is those filenames in the database that are not in EXPR. + +`EXPR1 and EXPR2' + The result is the intersection of the sets EXPR1 and EXPR2, i.e., + only those filenames contained in both. + +`EXPR1 or EXPR2' + The result is the union of the sets EXPR1 and EXPR2, i.e., all the + filenames contained in either or both. + + Operator names are recognized independent of case, so `AND', `and', +and `aNd' are all the same as far as `iid' is concerned. + + To pass a keyword as an operand, you must enclose it in double +quotes: the command `lid "lid"' generates the set of all filenames +matching the string `lid'. + + Patterns containing shell metacharacters (such as `*' or `?') must +also be properly quoted, since the query commands are run by invoking +them with the shell. + + +File: id.info, Node: iid commands, Prev: iid query expressions, Up: iid invocation + +`iid' commands +============== + + This section describes the interactive commands that `iid' +recognizes. The database query expressions you can pass to the `ss' +and `files' commands are described in the previous section. + + Some commands output a "summary line" for sets. These lines show the +set number, the number of filenames in the set, and the command that +generated it. + +`ss QUERY' + Build the set(s) of filenames resulting from the query expression + QUERY. The output is a summary line for each set. + +`files QUERY' +`f QUERY' + Evaluate the query expression QUERY as in `ss', but output the + full list of matching filenames instead of a summary. + +`sets' + Output a summary line for each extant set. + +`show SET' +`p SET' + Pass the filename in the set number SET to the program named in + the `PAGER' environment variable. Typically, this is a + page-at-a-time display program like `less' or `more'. If you use + Emacs, you might want to set `PAGER' to `emacsclient' (*note Emacs + Server: (emacs)Emacs Server.). + +`anything else' + When `iid' does not recognize the first word on an input line as a + builtin `iid' command, it assumes the input is a shell command + which will write a list of filenames to standard output, which it + gathers into a set as usual. + + Any set numbers that appear in the input are expanded into the + lists of filenames they represent prior to running the command. + +`!SHELL-COMMAND' + Expand set numbers appear in SHELL-COMMAND into the filenames they + represent, and pass the result to `/bin/sh'. The output is not + interpreted. + +`begin DIRECTORY' +`b DIRECTORY' + Begin a new `iid' session in a different directory (which + presumably contains a different database). It deletes all the sets + created so far and switches to the specified directory. It is + equivalent to exiting `iid', changing directories in the shell, and + running `iid' again. + +`help' +`h' +`?' + Display a short help file using the program named in `PAGER'. + +`quit' +`q' +`off' + Quit `iid'. An end-of-file character (usually `CTRL-D') also exits. + + +File: id.info, Node: Index, Prev: iid invocation, Up: Top + +Index +***** + +* Menu: + +* $ in identifiers: C scanner. +* * in globbing: Wildcard patterns. +* *scratch* Emacs buffer: GNU Emacs gid interface. +* -: mkid options. +* -a: iid command line options. +* -a: Query options. +* -aARGFILE: mkid options. +* -b: pid invocation. +* -c: iid command line options. +* -c: Query options. +* -d: Query options. +* -e: pid invocation. +* -e: Query options. +* -F: Query options. +* -fIDFILE: Query options. +* -g: Query options. +* -H: iid command line options. +* -k: Query options. +* -m: Query options. +* -n: Query options. +* -o: Query options. +* -rDIRECTORY: Query options. +* -S scanner option: Scanner option formats. +* -S.: Scanner option formats. +* -S?: Scanner option formats. +* -SSCANARG: mkid options. +* -Sasm+a: Assembler scanner. +* -Sasm+C: Assembler scanner. +* -Sasm+p: Assembler scanner. +* -Sasm+u: Assembler scanner. +* -Sasm-c: Assembler scanner. +* -Sc+u: C scanner. +* -Sc-s: C scanner. +* -Sc-u: C scanner. +* -Stext+a: Plain text scanner. +* -Stext+s: Plain text scanner. +* -Stext-a: Plain text scanner. +* -u: Query options. +* -v: mkid options. +* -w: Query options. +* -x: Query options. +* .default scanner: Scanners. +* .[chly] files, scanning: C scanner. +* ? in globbing: Wildcard patterns. +* aid: aid invocation. +* aid used for iid searches: iid command line options. +* architecture-independence: mkid invocation. +* assembler scanner: Assembler scanner. +* basename match: pid invocation. +* beginning-of-word editor argument: eid invocation. +* Berry, Karl: Past and future. +* brace notation in filename lists: Query options. +* bugs, reporting: Introduction. +* C scanner, predefined: C scanner. +* case-insensitive searching: aid invocation. +* commands for iid: iid commands. +* comments in assembler: Assembler scanner. +* common query arguments: Common query arguments. +* common query options: Query options. +* complex queries: iid invocation. +* compressed files, building ID from: mkid examples. +* conflicting identifiers, finding: Query options. +* constant strings, forcing evaluation as: Query options. +* creating databases: mkid invocation. +* cron: mkid invocation. +* cscope: Past and future. +* database name, specifying: Query options. +* databases, creating: mkid invocation. +* EDITOR: eid invocation. +* eid: eid invocation. +* EIDARG: eid invocation. +* EIDLDEL: eid invocation. +* EIDRDEL: eid invocation. +* Emacs interface to gid: GNU Emacs gid interface. +* emacsclient: iid commands. +* end-of-word editor argument: eid invocation. +* examples of mkid: mkid examples. +* examples, queries: Query examples. +* fid: fid invocation. +* filenames, matching: pid invocation. +* future: Past and future. +* gid Emacs function: GNU Emacs gid interface. +* gid.el interface to Emacs: GNU Emacs gid interface. +* globbing patterns: Wildcard patterns. +* grep: Past and future. +* help for iid: iid command line options. +* history: Past and future. +* Horsley, Tom: Past and future. +* ID database, definition of: Introduction. +* ID file format: mkid invocation. +* identifiers in a file: fid invocation. +* iid: iid invocation. +* iid commands: iid commands. +* iid options: iid command line options. +* iid query expressions: iid query expressions. +* interactive queries: iid invocation. +* introduction: Introduction. +* languages_0: Defining scanners in source code. +* left delimiter editor argument: eid invocation. +* Leonard, Bill: Past and future. +* lid: lid invocation. +* load-path: GNU Emacs gid interface. +* look and mkid 1: Past and future. +* man pages, compressed: mkid examples. +* matching filenames: pid invocation. +* McGary, Greg: Past and future. +* mkid: mkid invocation. +* mkid options: mkid options. +* multiple lines, merging: Query options. +* numbers, in databases: mkid invocation. +* numeric matches, specifying radix of: Query options. +* numeric searches: Query examples. +* options for iid: iid command line options. +* options for mkid: mkid options. +* overview: Introduction. +* PAGER: iid commands. +* parent directories, searched for ID: Query options. +* patterns: Patterns. +* pid: pid invocation. +* plain text scanner: Plain text scanner. +* predefined scanners: Predefined scanners. +* queries for iid: iid query expressions. +* query examples: Query examples. +* query options, common: Query options. +* radix of numeric matches, specifying: Query options. +* regular expression syntax: Patterns. +* regular expressions, forcing evaluation as: Query options. +* right delimiter editor argument: eid invocation. +* scanner options: Scanner option formats. +* scanners: Scanners. +* scanners, adding new: Defining new scanners. +* scanners, defining in source code: Defining scanners in source code. +* scanners, defining with options: Defining scanners with options. +* scanners, predefined: Predefined scanners. +* scanners.c: Defining scanners in source code. +* Scofield, Doug: Past and future. +* search for identifier, initial: eid invocation. +* sharing ID files: mkid invocation. +* shell brace notation in filename lists: Query options. +* shell commands in iid: iid commands. +* shell escape: iid commands. +* shell wildcard patterns: Wildcard patterns. +* single matches, showing: Query options. +* squeezing characters from identifiers: Plain text scanner. +* statistics: mkid options. +* string searching: aid invocation. +* strings, forcing evaluation as: Query options. +* suffixes of filenames: Scanners. +* suffixes_0: Defining scanners in source code. +* suppressing matching identifier: Query options. +* Texinfo, scanning example of: Defining scanners with options. +* whatis: aid invocation. +* wildcard wildcard patterns: Wildcard patterns. +* [!...] in globbing: Wildcard patterns. +* [...] in globbing: Wildcard patterns. +* \ in globbing: Wildcard patterns. + + + +Tag Table: +Node: Top1418 +Node: Introduction2101 +Node: Past and future4406 +Node: mkid invocation6731 +Node: mkid options8295 +Node: Scanners9707 +Node: Scanner option formats11196 +Node: Predefined scanners12366 +Node: C scanner13063 +Node: Plain text scanner13812 +Node: Assembler scanner14717 +Node: Defining new scanners15840 +Node: Defining scanners in source code16457 +Node: Defining scanners with options17296 +Node: idx invocation18744 +Node: mkid examples19304 +Node: Common query arguments21277 +Node: Query options21819 +Node: Patterns25208 +Node: Query examples26542 +Node: gid invocation27924 +Node: GNU Emacs gid interface29080 +Node: Looking up identifiers29938 +Node: lid invocation30428 +Node: aid invocation31856 +Node: eid invocation32636 +Node: fid invocation34674 +Node: pid invocation35226 +Node: Wildcard patterns36327 +Node: iid invocation37091 +Node: iid command line options37642 +Node: iid query expressions38213 +Node: iid commands40515 +Node: Index42745 + +End Tag Table |