extract(1int)															     extract(1int)

Name
       extract - interactive string extract and replace

Syntax
       extract [ -i ignorefile ] [ -m prefix ] [ -n ] [ -p patternfile ] [ -s string ]
       [ -u ] source-program...

Description
       The command interactively extracts text strings from source programs.  The command replaces the strings it extracts with calls to the func-
       tion.	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 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 command does not extract
       messages from source programs included using the directive.  Therefore, you might want to name a source program and all the source programs
       it includes on a single command line.

       You  can create a patterns file (as specified by (patternfile) to control how the command extracts and replaces text.  The patterns file is
       divided into several sections, each of which is identified by a keyword.  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 routine. For more information on the patterns file, see the reference page.

       In addition to the patterns file, you can create a file that indicates strings that ignores.  Each line in this ignore file contains a sin-
       gle string to be ignored that follows the syntax of the routine.

       When you invoke the 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 command line.  Otherwise, the command matches all strings and uses a default patterns file.

       When you run 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 command is creating.

       The  third  window contains a list of the commands that are available.  The 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 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 treats the string displayed in the first window:

       EXTRACT	      Extract the string into the catalog file and rewrite the source using the rewrite string in the patterns file.

       DUPLICATE      If the string has been encountered previously, rewrite the source program using the same message number as before.  The com-
		      mand need not add the message to the source message catalog again, so this command saves space in catalogs.

       IGNORE	      Ignore this and all subsequent occurrences of this string during this interactive session.  This command does  not  add  the
		      string to the ignore file.

       PASS	      Pass by (ignore) this occurrence of this particular string.

       ADD	      Ignore  this  and  all  subsequent occurrences of this string during this interactive session.  Add the string to the ignore
		      file.

       COMMENT	      Add the comment you enter to the source message catalog.	The command prompts you to be sure the comment you entered is cor-
		      rect.  You answer the prompt by typing ``y,'' n, or q, without pressing the RETURN key.

       QUIT	      Quit  from  the  interactive  session.   The  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 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.

       HELP	      Display a description of all the commands.

       The  command  creates  to  files  in your current working directory.  The command creates a new version of the source program that contains
       calls to the function, instead of hard-coded messages.  The new version of the source program has the same name as the  input  source  pro-
       gram, with the prefix ``nl_''.  For example, if the input source program is named the output source program is named

       In  addition  to  a new source program, the command creates a source message catalog. The source message catalog contains the text for each
       message extracted from your input source program.  The command names the file by appending ``.msf'' to the name of the  input  source  pro-
       gram.   For example, the source message catalog for the source program is named You can use the source message catalog as input to the com-
       mand.

Options
       -i     Ignore text strings specified in ignorefile .  By default, the command searches for ignorefile in  the  current  working	directory,
	      your home directory, and

	      If you omit the option, recognizes all strings specified in the patterns file.

       -m   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 catalogs that contain message number prefixes using the option.

       -n   Create a new source message catalog for each input source program. By default, if you specify more than one input  source  program	on
	    the command line, the command creates one source message catalog for all the input source programs.

       -p   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 finally

	    If you omit the option, the command uses a default patterns file that is stored in

       -s   Write string at the top of the source message catalog.  If you omit the option, uses the string specified in the section of  the  pat-
	    terns file.

       -u   Use  a file produced by a previous run of This file contains details of all the strings which matched the pattern file along with file
	    offsets and line numbers.  By default is run and its output is used to drive

Restrictions
       Given the current syntax of the patterns file, you cannot cause 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 command does not extract strings from files you include with the directive.	You must run the commands on these files separately.

       Your terminal screen must contain at least 80 columns and 24 lines for to display its three windows.

       The command does not recognize strings that extend beyond one line.

Examples
       The following example shows the commands you issue to run the command, create a message catalog from the source message catalog,  and  com-
       pile the output source program:
       % extract -i newignore -p c_patterns remove.c
       % gencat remove.cat remove.msf
       % vi nl_remove.c
       % cc nl_remove.c

       In  this example, the command uses the file to determine which strings to ignore.  The command uses the file to determines which strings to
       match.  The input source program is named

       In response to this command, creates the source message catalog and the output source program

       You must edit to include the appropriate and function calls.

       The command creates a message catalog and the command creates an executable program.

See Also
       intro(3int), gencat(1int), strextract(1int), strmerge(1int), regex(3), catopen(3int), catgets(3int), patterns(5int)
       Guide to Developing International Software

																     extract(1int)