NAME

extract − interactive string extract and replace

SYNTAX

extract [ −i ignorefile ] [ −m prefix ] [ −n ] [ −p patternfile ] [ −s string ]
[ −u ] filelist

DESCRIPTION

The extract function is used to extract text strings from programs interactively. The text strings are replaced with calls to a function that retrieves localized strings from a message catalog. The extraction process is driven by a pattern file.  This file contains details of the patterns to match in the source file and how they are to be rewritten. 

A new version of the source file is produced with the prefix nl_. The extract function also produces a message catalog file with the suffix .msf, which can be used as input to gencat or can be translated before being passed to gencat.

The pattern file is split into several sections, each identified by a keyword introduced by a $ character at the start of the line.  The syntax of the patterns is identical to the regular expression syntax used in ed. For more information, see patterns(.).

The ignore file contains details of strings to be ignored if they are found in the source.  This file, if present, is read at startup and provides a convenient mechanism for ignoring specific text strings.  During a run, strings can be added to this file using the ADD command. This file can also be maintained using an ordinary text editor. Each line contains a single string which is compared against a string from a pattern match.

When you run extract, three windows are displayed on the terminal. The first window contains the source code with the string to be extracted in standout mode. The second window contains a list of recently extracted strings, and the final window contains the available commands.

The following is the list of available commands:

EXTRACTExtract the string into the catalog file and rewrite the source using the REWRITE string in the pattern file.

DUPLICATEIf the string has already been seen, this option rewrites the source using the same message number as the one previously seen.  This can be used to save space in catalogs. 

IGNOREIgnore this and all subsequent occurrences of this string during this run. 

PASSPass by (ignore) this occurrence of this particular string. 

ADDAs IGNORE but also add this string to the ignore file.

QUITExit this program, with verification.  The output files are not removed by this command (they only contain the result of the string extraction up to the point of quitting). 

HELPDisplay the extract command summary.

The current command is displayed in standout mode and is executed if you press the <RETURN> key.  Select a new command by entering the first character of its name.  For example, the uppercase I or lowercase i selects the IGNORE command.

OPTIONS

−iSpecifies a new ignore file to be used to instruct extract to ignore specific text strings. The default is to search for the file ignore in the current directory, the home directory and finally /usr/lib/intln.

−mSpecifies a prefix to message numbers in the nl_ file and in the .msf file. This prefix can act as a mnemonic and must be processed using the −h flag of gencat.

−nCreate a new message source file for each input file. 

−pSpecifies a new pattern file to be used.  This file instructs extract which patterns are to be matched or ignored within the source file. The syntax is described below. The default is to search for the file pattern in the current directory, the home directory and finally /usr/lib/intln.

−sSpecifies a string to be output at the start of the .msf file. The default string is obtained from the $CATHEAD section of the pattern file. 

−uUse a message file produced by a previous run of strextract. This file contains details of all the strings which matched the pattern file along with file offsets and line numbers. By default strextract is run and its output is used to drive extract.

EXAMPLES

extract −i newignore −p c_patterns file1.c
gencat file1.cat file1.msf
cc nl_file1.c

RESTRICTIONS

With the current syntax of the pattern file, it is not possible to ignore strings in multi-line comments. 

Only one rewrite string can be specified for all classes of pattern matches. 

The program does not recurse through include files, these have to be worked on separately. 

The multiple window screen that is used must have an area of at least 80 characters by 24 lines. 

Multi-line strings are not recognized. 

SEE ALSO

ed(1), gencat(1int), strextract(1int), strmerge(1int), patterns(5int)