*! version May 1, 2014 @ 09:16:56

Title

splitlog -- marks and numbers commands and results in a Stata log file

Syntax

splitlog
using
filename
[,
options
tag format options
]

saving(filename) file in which to save the split log

replace replace saving file if it exists

cmdonly save only commands (no results)

resonly save only results (no commands)

nonumber squelch numbering of blocks

strip(int) level of stripping on commands

tag format options (nearly) endless list of formatting options for tags

tag format options

tagging commands

commandname(str) name of command environment in split file

commandnumberingname(str) what to call the command numbers

commandbeginprefix(str) prefix of lines marking the start of commands

commandbeginsuffix(str) suffix of lines marking the start of commands

commandendprefix(str) prefix of lines marking the end of commands

commandendsuffix(str) suffix of lines marking the end of commands

tagging results

resultname(str) name of result environment in split file

resultnumberingname(str) what to call the result numbers

resultbeginprefix(str) prefix of lines marking the start of results

resultbeginsuffix(str) suffix of lines marking the start of results

resultendprefix(str) prefix of lines marking the end of results

resultendsuffix(str) suffix of lines marking the end of results

tagging orphans

orphanname(str) name of orphan environment in split file

orphannumberingname(str) what to call the orphan numbers

orphanbeginprefix(str) prefix of lines marking the start of orphans

orphanbeginsuffix(str) suffix of lines marking the start of orphans

orphanendprefix(str) prefix of lines marking the end of orphans

orphanendsuffix(str) suffix of lines marking the end of orphans

Description

splitlog takes logs in SMCL format and puts tags (specially formatted comments) before and after each command and its results (if any).
It also marks orphans, which is the output from a command not in the log file (typically the header resulting from a log command).
splitlog is meant as a programmers' utility that allows processing of the commands and results.
An example of this is smcl2do, which uses splitlog to create do-files from log files.

Options

saving(filename) gives a filename to save the split log file.
If not specified, the name defaults to filename_split.smcl.

replace allows an exising filename to be overwritten.

cmdonly saves only the command blocks. This would rarely be used on its own.

resonly saves only the result blocks. This would rarely be used on its own. Only one of cmdonly or resonly may be specified.

nonumber keeps the command and result blocks from being numbered. This, too, would rarely be used on its own.

strip(int) tells how much should be stripped from the front of commands.
This is meant to help programmers manipulate log files.

0: strips nothing (default)

1: strips continuation characters

2: also strips numbering from lines inside of loops

3: also strips dot and colon prompts

Tag formatting options

splitlog distinguishes among three types of output in the smcl file: commands, results, and orphans.
Each of these output types has five options associated with it, so that formatting of the tags is flexible.

The output from type type starts with a tag built as

typebeginprefix+typename+typenumberingname+#+typebeginsuffix

where # is the command or orphan number (results share their numbers with commands).

Then comes the command/results/orphan itself.

The output from type type then ends with a tag built as

typeendprefix+typename+typenumberingname+#+typeendsuffix

where # is again the command or orphan number.

Here are all the tag options and their default values; note that many of the defaults have leading and/or trailing spaces for aesthetic reasons.

tag option default value

commandname(str) "command "

commandnumberingname(str) " number: "

commandbeginprefix(str) "\*** Begin "

commandbeginsuffix(str) " ***/"

commandendprefix(str) "\*** End "

commandendsuffix(str) the value of commandbeginsuffix(), meaning that only one suffix need be specified if both are the same.

resultname(str) "result "

resultnumberingname(str) " number: "

resultbeginprefix(str) "\***** Begin "

resultbeginsuffix(str) " *****/"

resultendprefix(str) "\***** End "

resultendsuffix(str) the value of resultbeginsuffix(), meaning that only one suffix need be specified if both are the same.

orphanname(str) "orphan "

orphannumberingname(str) " number: "

orphanbeginprefix(str) "\******* Begin "

orphanbeginsuffix(str) " *******/"

orphanendprefix(str) "\******* End "

orphanendsuffix(str) the value of orphanbeginsuffix(), meaning that only one suffix need be specified if both are the same.

The default appearance is in the Remarks below.

Remarks

splitlog takes a SMCL log file and produces another SMCL file where commands, results, and orphaned results are enclosed by special comments. It also tracks the commands which ended in error, so that these could be processed differently by any command consuming the file produced by splitlog.

If the file extensions for the using or saving() filenames are not given, they are assumed to be .smcl.

By default, each command is marked

/*** Begin command number num ***/

some stata command...

/*** End command number num ***/

By default, each result is marked

/***** Begin result number num *****/

some stata output...

/***** End result number num *****/

By default, each orphan is marked

/******* Begin orphan number num *******/

some log header...

/******* End orphan number num *******/

Orphans are results not associated with any command.
These arise from log commands starting log files with a header but without the log command itself.

Everything resulting from a do command is treated as one big result rather than the series of commands it represents.

splitlog is meant as a programmers' tool for going through SMCL code and marking and number the start and end of commands and their results. Once the chunks have been marked, another program can manipulate them.

There are a few known limitations:

splitlog leaves an extra orphan at the bottom of the split file because of the way that log close adds a bunch of smcl which looks like the start of a header of a new log file.

Using do commands within loops causes problems, because the actual do commands do not get echoed.
This result is that splitlog does not know when to go into result mode, and hence thinks the commands echoed in the results are true commands.
You can work around this by always using quietly do in loops.

Using two very specific SMCL directives: {com}. or {com}: will trick splitlog.
In reality, this should never be a problem, as these directives are supposed to be used only in producing a log file, and never in any actual display commands.

Examples

. splitlog using somelog

turns the log file somelog.smcl into the file somelog_split.smcl with commands and results separated by numbered comments.

. splitlog using somelog, saving(justcmds) cmdonly

turns the log file somelog.smcl into the file justcmds.smcl with commands separated by numbered comments.
None of the results from the somelog.smcl appear in justcmds.smcl.

. splitlog using somelog, saving(justresults) resonly

turns the log file somelog.smcl into the file justresults.smcl with results separated by numbered comments.
None of the commands from the somelog.smcl appear in justresults.smcl.

Stored results

splitlog stores the following in r():

Macros

r(errLn) The list of command numbers which ended in errors

r(cmdnum) The number of commands/results marked (which is also the number of the last command)

r(orphannum) The number of orphans

Author

Bill Rising, StataCorp

email: brising@stata.com

web: http://louabill.org/Stata