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