-------------------------------------------------------------------------------
help for inccat                                                  (Roger Newson)
-------------------------------------------------------------------------------

Concatenate one or more input files to an output file inserting additional inpu > t files

inccat infilename_list , to(outfilename) [ replace prefix(prefix_string) postfix(postfix_string) hmax(#)

where infilename_list is a list of names of existing text files separated by spaces.

Description

inccat ("include and concatenate") takes, as input, a list of one or more input files, and concatenates them to an output file. Optionally, one or more of the input files may contain one or more lines beginning with a user-specified prefix and continuing with a list of valid file names belonging to additional input files, and each such line is replaced in the output file by the contents of these files. These additional input files can contain prefixed lines with lists of further additional input files, which are also included in the same way.

Options

to() specifies an output file, to be created by inccat, containing the concatenation of the input files, including additional input files listed in prefixed lines.

replace specifies that, if a file exists with the name specified by to(), then that file is to be overwritten.

prefix(prefix_string) specifies a prefix string. If prefix() is specified, then lines in the input files beginning with prefix_string will be assumed to contain a list of one or more file names, and the line is replaced in the output file by the contents of these files. The prefix string may contain spaces, but must be at the beginning of a line to be recognised.

postfix(postfix_string) specifies a postfix string. If prefix() and postfix() are both specified, then the postfix string acts as a terminator for file lists in lines beginning with the prefix string. The postfix string must be a valid Stata token, and therefore must be separated from the last file in the list by at least one space, and may not contain spaces, except if it begins and ends with quotes. If prefix() is not specified, then postfix() is ignored.

hmax(#) specifies the maximum height of a family tree where the nodes are input files, the root is one of the original list of input files in infilename_list, and the daughters of any input file are the input files named in prefixed lines in that file. In default, this maximum height is 31. If an input file of generation hmax contains any prefixed lines, then these prefixed lines are copied to the output file, not replaced by the contents of the files listed in these prefixed lines. The option hmax exists to prevent {inccat} from attempting to create infinite files, as might happen if an input file contains a prefixed line listing itself.

Remarks

inccat is an extended version of copy. The file inclusion enabled by prefixed lines is useful if the user wants to create HTML files containing tables with rows created by listtex (downloadable from SSC) and updated from time to time. inccat takes advantage of the fact that the Stata language is recursive (like C or Pascal), so that a program can call itself.

Examples

. inccat myfile1.txt myfile2.txt myfile3.txt myfile4.txt, to(mynewfile1.txt) replace

. inccat myfile1.txt myfile2.txt myfile3.txt myfile4.txt, to(mynewfile2.txt) pre(!include) replace

The following advanced example uses prefixed lines to create an updatable HTML file with a table containing some of the auto data. Suppose the user has a file auto1_r.htm, containing HTML code for the heading (but not the rows) of a simple table, as follows:

<table border="1"> <caption>Weight and mileage in US and non-US cars</caption> <tr><th>Make</th><th>Origin</th><th>Weight (lbs.)</th><th>Mileage (mpg)</th></tr> <!--include rows1.htm --> </table>

Note that the fourth line (<!--include rows1.htm -->) is a comment in HTML. If the user has the listtex package, downloadable from SSC, then s/he might then type, in Stata:

. listtex make foreign weight mpg using rows1.htm, b(<tr><td>) d(</td><td>) e(</td></tr>) replace . inccat auto1_r.htm, to(auto1.htm) prefix(<!--include) postfix(-->) replace

The first line will use listtex to create a text file rows1.htm, containing the table rows. The second line will use inccat to copy auto1_r.htm to auto.htm, replacing the line

<!--include rows1.htm -->

with the table rows in rows1.htm. The file auto1.htm will then contain a simple HTML table giving weight and mileage in US and non-US cars. The user can update the table, if the auto data set is ever updated.

Similar things can be done with stata.toc files in a user's website, if the user wishes to keep the lines beginning with p and listing packages in one file (revised regularly by listtex) and the other lines in another file (revised occasionally). See on-line help for net.

Author

Roger Newson, Imperial College London, UK. Email: r.newson@imperial.ac.uk

Also see

Manual: [R] copy, [R] shell, [R] net On-line: help for copy, shell, net help for listtex if installed