extract(1)extract(1)NAMEextract - interactive string extract and replace
SYNOPSISextract [-i ignorefile] [-m prefix] [-n] [-p patternfile] [-s string]
[-u] source-program...
OPTIONS
Ignore text strings specified in ignorefile. By default, the extract
command searches for ignorefile in the current working directory, your
home directory, and /usr/lib/nls.
If you omit the -i option, extract recognizes all strings speci‐
fied in the patterns file. Add prefix to message numbers in the
output source program and source message catalog. You can use
this prefix as a mnemonic. You must process source message cat‐
alogs that contain message number prefixes using the mkcatdefs
command. Create a new source message catalog for each input
source program. By default, if you specify more than one input
source program on the extract command line, the command creates
one source message catalog for all the input source programs.
Use patternfile to match strings in the input source program.
By default, the command searches for the pattern file in the
current directory, your home directory, and /usr/lib/nls.
If you omit the -p option, the extract command uses a default
patterns file that is stored in /usr/lib/nls/patterns. Write
string at the top of the source message catalog. If you omit
the -s option, extract uses the string specified in the $CATHEAD
section of the patterns file. Use 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 off‐
sets and line numbers. By default strextract is run and its
output is used to drive extract.
DESCRIPTION
The extract command interactively extracts text strings from source
programs. The extract command replaces the strings it extracts with
calls to the catgets function. The command also writes the string it
extracts to a source message catalog. You use this command to replace
hard-coded messages in your program source file with calls to the cat‐
gets command and create a source message catalog. At run time, the
program reads the message text from the message catalog. By storing
messages in a message catalog, instead of in your program, you allow
the text of messages to be translated to a new language or modified
without the source program being changed.
In the source-program argument, you name one or more source programs
from which you want messages extracted. The extract command does not
extract messages from source programs included using the #include
directive. Therefore, you might want to name a source program and all
the source programs it includes on a single extract command line.
You can create a patterns file (as specified by patternfile) to control
how the extract command extracts and replaces text. The patterns file
is divided into several sections, each of which is identified by a key‐
word. The keyword must start at the beginning of a new line, and its
first character must be a dollar sign ($). Following the identifier,
you specify a number of patterns. Each pattern begins on a new line
and follows the regular expression syntax you use in the regexp rou‐
tine. For more information on the patterns file, see patterns(4)and
for more information on the regexp routine, see regexp(3).
In addition to the patterns file, you can create a file that indicates
strings that extract ignores. Each line in this ignore file contains a
single string to be ignored that follows the syntax of the regexp rou‐
tine.
When you invoke the extract command, it reads the patterns file and the
file that contains strings it ignores. You can specify a patterns file
and an ignore file on the extract command line. Otherwise, the extract
command matches all strings and uses a default patterns file.
When you run extract, it displays three windows on your terminal. The
first window contains the program source code. The string that matches
a string in the patterns file is displayed in reverse video.
The second window displays the contents of the source message catalog
that the extract command is creating.
The third window contains a list of the commands that are available.
The extract command displays the current command in reverse video. You
can execute the current command by pressing the RETURN key. Select
another command by typing the first letter in the command name and
pressing the RETURN key. The extract command is not sensitive to the
case of letters, so you can use uppercase or lowercase letters to issue
commands.
You can use the following commands to control how extract treats the
string displayed in the first window: Extract the string into the cata‐
log file and rewrite the source using the rewrite string in the pat‐
terns file. If the string has been encountered previously, rewrite the
source program using the same message number as before. The extract
command need not add the message to the source message catalog again,
so this command saves space in catalogs. Ignore this and all subse‐
quent occurrences of this string during this interactive session. This
command does not add the string to the ignore file. Pass by (ignore)
this occurrence of this particular string. Ignore this and all subse‐
quent occurrences of this string during this interactive session. Add
the string to the ignore file. Add the comment you enter to the source
message catalog. The extract command prompts you to be sure the com‐
ment you entered is correct. You answer the prompt by typing “y,” “n,”
or “q,” without pressing the RETURN key. Quit from the interactive
session. The extract command prompts you to be sure you want to quit.
Answer “y” or “n” to the prompt, without pressing the return key.
The output files that extract creates up to this point are not
removed by this command. However, the files contain only the
result of the string extractions that occurred before you issued
the QUIT command. Display a description of all the extract com‐
mands.
The extract command creates two files in your current working direc‐
tory. The command creates a new version of the source program that
contains calls to the catgets function, instead of hard-coded messages.
The new version of the source program has the same name as the input
source program, with the prefix nl_. For example, if the input source
program is named update.c, the output source program is named
nl_update.c.
In addition to a new source program, the extract command creates a
source message catalog. The source message catalog contains the text
for each message extracted from your input source program. The extract
command names the file by appending to the name of the input source
program. For example, the source message catalog for the update.c
source program is named update.msg. You can use the source message
catalog as input to the gencat command.
RESTRICTIONS
Given the current syntax of the patterns file, you cannot cause extract
to ignore strings in comments that are longer than one line.
You can specify only one rewrite string for all classes of pattern
matches.
The extract command does not extract strings from files you include
with the #include directive. You must run the extract commands on
these files separately.
Your terminal screen must contain at least 80 columns and 24 lines for
extract to display its three windows.
The extract command does not recognize strings that extend beyond one
line.
EXAMPLES
The following example shows the commands you issue to run the extract
command, create a message catalog from the source message catalog, and
compile the output source program:
% extract-i newignore -p c_patterns remove.c % gencat remove.cat
remove.msg % vi nl_remove.c % cc nl_remove.c
In this example, the extract command uses the newignore file to deter‐
mine which strings to ignore. The command uses the c_patterns file to
determines which strings to match. The input source program is named
remove.c.
In response to this command, extract creates the source message catalog
remove.msg and the output source program nl_remove.c.
You must edit nl_remove.c to include the appropriate catopen and cat‐
close function calls.
The gencat command creates a message catalog and the cc command creates
an executable program.
SEE ALSOgencat(1), mkcatdefs(1), strextract(1), strmerge(1), catopen(3), cat‐
gets(3), regexp(3), patterns(4)
Writing Software for the International Market
extract(1)