{smcl} {hline} help for {cmd:inccat} {right:(Roger Newson)} {hline} {title:Concatenate one or more input files to an output file inserting additional input files} {p 8 15}{cmd:inccat} {it:infilename_list} , {cmdab:t:o}{cmd:(}{it:outfilename}{cmd:)} [ {cmd:replace} {cmdab:pr:efix}{cmd:(}{it:prefix_string}{cmd:)} {cmdab:po:stfix}{cmd:(}{it:postfix_string}{cmd:)} {cmdab:hm:ax}{cmd:(}{it:#}{cmd:)} {p} where {it:infilename_list} is a list of names of existing text files separated by spaces. {title:Description} {p} {cmd:inccat} ("{it:inc}lude and con{it:cat}enate") 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. {title:Options} {p 0 4}{cmd:to()} specifies an output file, to be created by {cmd:inccat}, containing the concatenation of the input files, including additional input files listed in prefixed lines. {p 0 4}{cmd:replace} specifies that, if a file exists with the name specified by {cmd:to()}, then that file is to be overwritten. {p 0 4}{cmd:prefix(}{it:prefix_string}{cmd:)} specifies a prefix string. If {cmd:prefix()} is specified, then lines in the input files beginning with {it: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. {p 0 4}{cmd:postfix(}{it:postfix_string}{cmd:)} specifies a postfix string. If {cmd:prefix()} and {cmd: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 {cmd:prefix()} is not specified, then {cmd:postfix()} is ignored. {p 0 4}{cmd:hmax(}{it:#}{cmd:)} 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 {it: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 {cmd: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 {cmd:hmax} exists to prevent {inccat} from attempting to create infinite files, as might happen if an input file contains a prefixed line listing itself. {title:Remarks} {p} {cmd:inccat} is an extended version of {cmd:copy}. The file inclusion enabled by prefixed lines is useful if the user wants to create HTML files containing tables with rows created by {help listtex} (downloadable from SSC) and updated from time to time. {cmd:inccat} takes advantage of the fact that the Stata language is recursive (like C or Pascal), so that a program can call itself. {title:Examples} {p 16 20}{inp:. inccat myfile1.txt myfile2.txt myfile3.txt myfile4.txt, to(mynewfile1.txt) replace}{p_end} {p 16 20}{inp:. inccat myfile1.txt myfile2.txt myfile3.txt myfile4.txt, to(mynewfile2.txt) pre(!include) replace}{p_end} {p} The following advanced example uses prefixed lines to create an updatable HTML file with a table containing some of the {hi:auto} data. Suppose the user has a file {hi:auto1_r.htm}, containing HTML code for the heading (but not the rows) of a simple table, as follows: {p 16 20}{inp:}{p_end} {p 16 20}{inp:}{p_end} {p 16 20}{inp:}{p_end} {p 16 20}{inp:}{p_end} {p 16 20}{inp:
Weight and mileage in US and non-US cars
MakeOriginWeight (lbs.)Mileage (mpg)
}{p_end} {p} Note that the fourth line ({inp:}) is a comment in HTML. If the user has the {help listtex} package, downloadable from SSC, then s/he might then type, in Stata: {p 16 20}{inp:. listtex make foreign weight mpg using rows1.htm, b() d() e() replace}{p_end} {p 16 20}{inp:. inccat auto1_r.htm, to(auto1.htm) prefix() replace}{p_end} {p} The first line will use {help listtex} to create a text file {hi:rows1.htm}, containing the table rows. The second line will use {cmd:inccat} to copy {hi:auto1_r.htm} to {hi:auto.htm}, replacing the line {p 16 20}{inp:}{p_end} {p} with the table rows in {hi:rows1.htm}. The file {hi: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 {hi:auto} data set is ever updated. {p} Similar things can be done with {hi:stata.toc} files in a user's website, if the user wishes to keep the lines beginning with {hi:p} and listing packages in one file (revised regularly by {cmd:listtex}) and the other lines in another file (revised occasionally). See on-line help for {help net}. {title:Author} {p} Roger Newson, Imperial College London, UK. Email: {browse "mailto:r.newson@imperial.ac.uk":r.newson@imperial.ac.uk} {title:Also see} {p 0 10} {bind: }Manual: {hi:[R] copy}, {hi: [R] shell}, {hi:[R] net} {p_end} {p 0 10} On-line: help for {help copy}, {help shell}, {help net} {break} help for {help listtex} if installed {p_end}