.TH extract 1int.SH Nameextract \- interactive string extract and replace.SH Syntax.B extract [.B \-i.I ignorefile] [.B \-m .I prefix] [ .B \-n] [.B \-p.I patternfile] [ .B \-s.I string].br[ .B \-u].I source-program....SH Description.NXR "extract utility"The .PN extractcommand interactively extracts text strings from source programs.The.PN extractcommand replaces the strings it extracts with calls to the.PN catgetsfunction.    The command also writes the string it extracts to asource message catalog.You use this command to replace hard-coded messages inyour program source file with calls to the.PN catgetscommand and create a source message catalog.  At run time, the programreads the message text from the message catalog.  By storingmessages in a message catalog, instead of in your program, you allowthe text of messages to be translated to a new language or modifiedwithout the source program beingchanged..PPIn the .I source-programargument, you name one or more source programs from which you wantmessages extracted.  The.PN extractcommand does not extract messages from source programs included usingthe.PN #include directive.  Therefore, you might want to name a source program and allthe source programs it includes on a single .PN extract command line..PPYou can create a patterns file (as specified by (\fIpatternfile\fP) to control how the.PN extractcommand extracts and replaces text.  The patterns file is dividedinto several sections, each of which is identified by a keyword.  Thekeyword must start at the beginning of a new line, and its first charactermust be a dollar sign ($).  Following the identifier, you specify anumber of patterns.  Each pattern begins on a new line and follows theregular expression syntax you use in the  .MS regex 3 routine. For more information on the patterns file, see the.MS patterns 5intreference page..PPIn addition to the patterns file, you can create a file that indicatesstrings that.PN extractignores.  Each line in this ignore file contains a single string to beignored thatfollows the syntax of the .MS regex 3routine..PPWhen you invoke the.PN extractcommand, it reads the patterns file and the file that contains stringsit ignores.  You can specify a patterns file and an ignore file on the.PN extract command line.  Otherwise, the.PN extractcommand matches all strings and uses a default patterns file..PPWhen you run .PN extract ,it displays three windows on your terminal.The first window contains the program source code. The string thatmatches a string in the patterns file is displayed in reverse video..PPThe second window displays the contents of the source message catalog thatthe .PN extractcommand is creating.  .PPThe third window contains a list of the commands that are available.The.PN 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 thecommand name and pressing the RETURN key.  The .PN extract command is notsensitive to the case of letters, so you can use uppercase orlowercase letters to issue commands..PPYou can use the following commands to control how.PN extracttreats the string displayed in the first window:.IP \fBEXTRACT\fR 15Extract the string into the catalog file and rewrite the source using therewritestring in the patternsfile..IP DUPLICATE 15If the string has been encountered previously, rewrite the source programusing the same message number as before.  The.PN extractcommand need not add the message to the source message catalog again,so this command saves space in catalogs..IP IGNORE 15Ignore this and all subsequent occurrences of this string during thisinteractive session.  This command does not add the string to theignore file..IP PASS 15Pass by (ignore) this occurrence of this particular string..IP ADD 15Ignore this and all subsequent occurrences of this string during thisinteractive session.  Add the string to the ignore file..IP COMMENT 15Add the comment you enter to the source message catalog.  The .PN extractcommand prompts you to be sure the comment you entered is correct.You answer the prompt by typing ``y,'' \*Qn,\*U or \*Qq,\*U withoutpressing the RETURN key..IP \fBQUIT\fR 15Quit from the interactive session.  The.PN extract command prompts you to be sure you want to quit.  Answer ``y'' or``n'' to the prompt, without pressing the return key..IPThe output files that .PN extractcreates up to this point are not removed by this command.  However,the files contain only the result of the string extractions thatoccurred before you issued the QUIT command..IP \fBHELP\fR 15Display a description of all the.PN extractcommands..PPThe.PN extractcommand creates to files in your current working directory.  Thecommand creates a new version of the source program that containscalls to the.PN catgetsfunction, instead of hard-coded messages.  The new version of thesource program has the same name as the input source program, with theprefix ``nl_''.  For example, if the input source program is named .PN update.c ,the output source program is named.PN nl_update.c.PPIn addition to a new source program, the.PN extract command creates a source message catalog. The source message catalog contains the text for each message extracted from your input source program.The .PN extractcommand names the file by appending ``.msf'' to the name of theinput source program.  For example, the source message catalog for the.PN update.csource program is named.PN update.msf .You can use the source message catalog as input to the.PN gencatcommand..SH Options.IP \fB-i \fP 5Ignore text strings specified in .I ignorefile .By default, the.PN extractcommand searches for .I ignorefilein the current working directory,your home directory, and.PN /usr/lib/intln ..IPIf you omit the .PN \-i option, .PN extractrecognizes all strings specified in the patterns file..IP \fB-m\fP 5Add .I prefixto message numbers in the output source program and source message catalog. You canuse this prefix as a mnemonic.  You must process source message catalogsthat contain message number prefixes using the .PN gencat .PN \-h option..IP \fB-n\fP 5Create a new source message catalog for each input source program. Bydefault, if you specify more than one input source program on the.PN extractcommand line, the command creates one source message catalog for allthe input source programs..IP \fB-p\fP 5Use .I patternfileto match strings in the input source program.By default, the command searches for the pattern filein the current directory, your home directory and finally.PN /usr/lib/intln ..IPIf you omit the.PN \-poption, the .PN extract command uses a default patterns file that is stored in.PN /usr/lib/intln/patterns ..IP \fB-s\fP 5Write.I stringat the top of the source message catalog.If you omit the.PN \-soption, .PN extractuses the string specified in the.PN $CATHEADsection of the patternsfile..IP \fB-u\fP 5Use a.PN messagefile produced by a previous run of .PN strextract .This file contains details of all the strings which matched the pattern file along with file offsets and line numbers.By default.PN strextract is run and its output is used to drive .PN extract ..SH RestrictionsGiven the current syntax of the patterns file, you cannot cause.PN extractto ignore strings in comments that are longer than one line..PPYou can specify only one rewrite string for all classes of pattern matches..PPThe .PN extractcommand does not extract strings from files you include with the.PN #includedirective.  You must run the.PN extractcommands on these files separately..PPYour terminal screen must contain at least 80 columns and 24 lines for.PN extractto display its three windows..PPThe.PN extract command does not recognize strings that extend beyond one line..SH ExamplesThe following example shows the commands you issue to run the.PN extractcommand, create a message catalog from the source message catalog, and compile the output source program:.EX% extract \-i newignore \-p c_patterns remove.c% gencat remove.cat remove.msf% vi nl_remove.c% cc nl_remove.c.EE.PPIn this example, the.PN extractcommand uses the.PN newignorefile to determine which strings to ignore.  The command uses the.PN c_patterns file to determines which strings to match.  The input source programis named.PN remove.c ..PPIn response to this command, .PN extractcreates the source message catalog .PN remove.msfand the output source program.PN nl_remove.c ..PPYou must edit .PN nl_remove.cto include the appropriate .PN catopenand .PN catclosefunction calls..PPThe .PN gencatcommand creates a message catalog and the.PN cccommand creates an executable program..SH See Alsointro(3int), gencat(1int), strextract(1int), strmerge(1int), regex(3),catopen(3int), catgets(3int), patterns(5int).br\fIGuide to Developing International Software\fP