* version 1.0 07feb2018 David Fisher
* version 1.1 08nov2018 David Fisher
*! version 1.2 03dec2019 David Fisher
*! (amended to work with -metan- v4.00)
*! based on geo2xy_run.ado by Robert Picard, picard@netbox.com
program define metan_hlp_run
version 11
** Notes on "preserve/restore" behaviour:
// 1. The default (i.e. specifying nothing) is to preserve the data originally in memory (assumed to be the user's own data)
// before reading in the contents of the help file and running it.
// Hence, the resulting example code should be entirely "self-sufficient", loading its own example data if necessary
// and the data orignally in memory will be restored upon completion.
// 2. Specifying -restnot- cancels -preserve- once the contents of the help file have been run.
// 3. Specifying -restpres- preserves the data originally in memory as above,
// but restores and *re-preserves* that data before running the code.
// Hence, the code is intended to apply to the data in memory at the time metan_hlp_run was called.
// 4. Specifying -restpresnot- is equivalent to specifying -restnot- and -restpres- together;
// which leaves behind the data originally in memory, but "damaged" by the contents of the help file.
syntax anything(name=example_name id="example name") using/ ///
, [RESTNOT RESTPRES RESTPRESNOT LIST DEBUG]
quietly {
findfile `"`using'"'
preserve
// read in contents of help file
infix str txt 1-244 using `"`r(fn)'"', clear
replace txt = trim(txt)
// identify example_start and example_end limits
gen long obs = _n
summ obs if strpos(txt, "{* example_start - `example_name'}{...}")
if r(min) == . {
disp as err "example `example_name' not found"
exit 111
}
local pos1 = r(min) + 1
summ obs if strpos(txt, "{* example_end}{...}") & obs > `pos1'
if r(min) == . {
disp as err "example `example_name' incorrectly coded"
exit 111
}
local pos2 = r(min) - 1
keep in `pos1'/`pos2'
replace obs = _n
// In general, do-file command lines should *not* start with "{" or end with "}"
// instead, the characters {} should be identifiers of SMCL.
// Examples of specific patterns of SMCL to identify:
// {* comment} or {* comment}{directive}
// {directive:output} or {directive:output}{directive}
// {directive:output}{* comment} or {directive:output}{* comment}{directive}
// {c output} or {char output}
// Strategy:
// - Identify sets of brackets, i.e. {content}
// - For each set of brackets, isolate content and test for {directive:output} or {* comment};
// if so, keep content; else, drop
// exception is {c output} or {char output}; these need conversion back to their original characters (see below)
// Problem 1: what if SMCL tags {} are used for other purposes, e.g. loops within Stata commands?
// Solution: onus is on help-file authors to replace such characters with {c -(} and {c )-} respectively.
// These can then be converted back to {} before the final do-file is run.
// Problem 2: how to deal with "{* ...}" ?? "..." could be either SMCL or Stata; no way to know in advance.
// Solution: onus is on help-file authors not to use the syntax "{* [SMCL directive]}" within "example limits".
gen str newtxt = ""
gen str txt_noc = ""
gen str content = ""
gen int strpos = .
count if regexm(txt, "{")
while r(N) {
// identify anything before the next {
replace strpos = cond(strpos(txt, "{"), strpos(txt, "{"), .)
replace newtxt = newtxt + substr(txt, 1, strpos-1)
replace txt = substr(txt, cond(strpos, strpos, 1), .) // keep the "{" for matching with "}"
// identify content within the next {}
replace strpos = strpos(txt, "}")
cap assert (strpos>0) == (substr(txt, 1, 1)=="{")
if _rc {
nois disp as err "found unpaired SMCL tags {}"
nois list txt if (strpos>0) != (substr(txt, 1, 1)=="{")
exit 132
}
replace content = trim(substr(txt, 1, strpos)) if substr(txt, 1, 1)=="{"
replace txt = substr(txt, cond(strpos, strpos+1, 1), .) // remaining part of original text
// analyse content; look for {directive:output}
replace newtxt = newtxt + regexs(1) if regexm(trim(content), "^{[a-z0-9_ ]+:(.*)}$")
// analyse content; look for {* comment}
replace newtxt = newtxt + regexs(1) if regexm(trim(content), "^{\*(.*)}$")
// analyse content; look for {c ...} or {char ...}; add these wholesale to newtxt
replace newtxt = newtxt + content if regexm(trim(content), "^{c (.*)}$") | regexm(trim(content), "^{char (.*)}$")
// reset
replace strpos = .
replace content = ""
// check for further tags in original text string;
// if yes, loop again
// otherwise, add anything from the end, then check for *nested* tags in newtxt EXCLUDING {c ...}
// this must finish eventually; and from then on the useful code is stored in txt, not newtxt
// (hence: drop if txt=="" )
count if regexm(txt, "{")
if !r(N) {
replace newtxt = newtxt + txt
drop txt
rename newtxt txt
gen str newtxt = ""
// REMOVE {c -(} and {c )-} BEFORE CHECKING!
replace txt_noc = txt
replace txt_noc = subinstr(txt_noc, "{c -(}", "", .)
replace txt_noc = subinstr(txt_noc, "{c )-}", "", .)
if "`debug'"!="" {
nois list txt_noc if regexm(txt_noc, "{")
}
count if regexm(txt_noc, "{")
}
// display txt and newtxt for debugging, if requested
// (N.B. first time around, this will probably give a list of "{p_end}")
else if "`debug'"!="" {
nois list txt if regexm(txt, "{")
}
}
drop if txt==""
// tidy up:
// - convert SMCL characters to standard characters
// - remove initial periods, if present
replace txt = subinstr(txt, "{c -(}", "{", .)
replace txt = subinstr(txt, "{c )-}", "}", .)
replace txt = subinstr(txt, "{c S|}", "$", .)
replace txt = subinstr(txt, "{c 'g}", "`", .)
replace txt = trim(subinstr(txt, ".", "", 1)) if substr(trim(txt), 1, 1)=="."
} // end quietly
// Optionally list contents of do-file to be run
if `"`list'"'!=`""' {
disp _n _c
format txt %-1s
list txt, clean noheader
}
tempfile f
outfile txt using "`f'", noquote
if `"`restpres'`restpresnot'"'!=`""' {
restore, preserve
}
disp _newline(2) as txt "{hline 27} {it:example do-file content} {hline 27}"
do "`f'"
disp as txt _n "{hline 23} {it:end of example do-file content} {hline 24}" _newline(2)
if `"`restnot'`restpresnot'"'!=`""' {
restore, not
}
end