Next: , Previous: mkid invocation, Up: Top

5 lid: Querying an ID Database by Token

The lid program accepts patterns on the command line which it matches against the tokens stored in an ID database. The interpretation of a pattern is determined by the makeup of the pattern string itself, or can be overridden by command-line options. If a pattern contains regular expression meta-characters, it is used to perform a regular-expression substring search. If no such meta-characters are present, pattern is used to perform a literal word search. (By default, all searches are sensitive to alphabetic case.) If no pattern is supplied on the command line, lid lists every entry in the ID database.

lid reads the ID database, therefore it accepts the `--file' option, and consults the `IDPATH' environment variable, as described in Reading options. lid lists file names, therefore it accepts the `--separator' option, as described in File listing options.

In addition, lid accepts the following command-line options:

`-i'
`--ignore-case'
Ignoring differences in alphabetic case between the pattern and the tokens in the ID database.
`-l'
`--literal'
Match pattern as a literal string. Use this option if pattern contains regular-expression meta-characters, but you don't wish to perform a regular-expression search.
`-r'
`--regexp'
Match pattern as an extended regular expression1. Use this option if no regular-expression expression meta-characters are present in pattern, but you wish to force a regular-expression search (note: in this case, a literal substring search might be faster).
`-w'
`--word'
Match pattern using a word-delimited (non substring) search. This is the default for literal searches.
`-s'
`--substring'
Match pattern using a substring (non word-delimited) search. This is the default for regular expression searches.
`-k style'
`--key=style'
Style can be one of `token', `pattern' or `none'. This option controls how the subject of the query is presented. This is best illustrated by example: 
          $ lid --key=token '^dest.'
          destaddr       libsys/memcpy.c
          destination    libsys/regex.c
          destlst        libsys/rx.c
          destpos        libsys/rx.c
          destset        libsys/rx.h libsys/rx.c
          
          $ lid --key=pattern '^dest.'
          ^dest.         libsys/rx.h libsys/{memcpy,regex,rx}.c
          
          $ lid --key=none '^dest.'
          libsys/rx.h libsys/{memcpy,regex,rx}.c

When `--key' is either `token' or `pattern', the first column of output is a token or pattern, respectively. When `--key' is `none', neither of these is printed, and the file name list begins immediately. The default is `token'.

`-R style'
`--result=style'
Style can be one of `filenames', `grep', `edit' or `none'. This option controls how the value associated with the query's key presented. When style is `filenames', a list of file names is printed (this is the default). When style is `grep', the lines that match pattern are printed in the same format as `egrep -n'. When style is `edit', the file names are passed to an editor, and if possible pattern is passed as an initial search string (see eid invocation). When style is `none', the file names are not processed in any way. This can be useful if you wish to see what tokens match a pattern, but don't care about where they reside.
`-d'
`-o'
`-x'
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. Any combination of these options may be used. The default is to match all three radixes.
`-F range'
`--frequency=range'
Match tokens whose occurrence count falls in range. Range may be expressed as a single number n, or as a range n..m. Either limit of the range may be omitted (e.g., ..m, or n....). If the lower limit n is omitted, it defaults to 1. If the upper limit is omitted, it defaults in the present implementation to 65535, the maximum value of an unsigned 16-bit integer.

Particularly useful queries are `lid -F1', which helps locate identifiers that are defined but never used, or are used but never defined. Similarly, lid -F2 can help find functions that possess a prototype declaration and a definition, but are never called.

`-a number'
`--ambiguous=number'
List identifiers (not numbers) that are ambiguous for the first number characters. This feature might be in useful when porting programs to ancient pea-brained compilers that don't support long identifier names. However, the best long-term option is to set such systems on fire.

Footnotes

[1] Extended regular expressions are the same as those accepted by egrep.