This new MIAMEX function copies a file to another, applying a series of regular expression pattern match / replacement translations.
xcall MIAMEX, MX_TRANSCOPY, op, srcfile, dstfile, tcffile, section, status{, flags, maxlen, errmsg}
Parameters
op (Num) [in]
must be set to 1
srcfile (String) [in]
source filespec
dstfile (String) [in]
destination filespec; replaced if already exists
tcffile (String) [in]
configuration filespec; see TCF specification below
section (String) [in]
optional section name within tcffile
status (Signed Int) [out]
on success, # of modified lines; see below for errors
flags (Int) [in]
optional REGEX.SBR flags; combined with any set in the TCF file, plus:
maxlen (Int) [in]
optional max length of source lines to support; default 16Kconfiguration filespec; see TCF specification below
errmsg (String) [out]
status < 0)
PCREX_ASB_SOURCE (&h20000000) - treat srcfile as A-Shell Basic, merging continuation lines into one, which may affect the pattern matching which is otherwise limited to one source line at a time.
TCF Specification
The Transcopy Configuration File contains the search and replace patterns and other options to apply to the transcopy operation. The structure is based on standard INI files, with Item=Value elements grouped beneath [Section] headers. Optionally the top section of the file may contain global items (without a [Section] header). The section names are entirely arbitrary, intended for your convenience in grouping related sets of translations without a single TCF file.
The defined item=value pairs (not case sensitive) are:
s{#}=value
Search pattern {optional # in 1-127 range}. If # is used, the following replacement item must use the same #. Value is a regex pattern, possibly containing up to 99 submatch references.
r{#}=value
Replacement pattern associated with the prior search pattern. If a number is specified, it must match the prior search pattern number.) References to submatches in the search pattern must use \# syntax, where the # is the submatch number (not to be confused with the overall search pattern number.
flags=value
Optional REGEX flags. Same as for REGEX.SBR.
Blank lines, and those beginning with !, ;, or # are treated as comments.
For example, this TCF file...
[cust]
; set PCRE_UNGREEDY...
flags=&h0200
s=([^\w])(orderNo|custName)([^\w])
r=\1wo.\2\3
... contains a single section, setting the Regex flags to &0200 (PCRE_UNGREEDY), and defining a single pair of search/replace patterns (with three submatch expressions). This would translate all word-delimited occurrences of "orderNo" to "wo.OrderNo" and "custName" to "wo.custName".
Limitations
| • | Maximum number of s#/r# pairs per section: 127. If you need more, split them into separate sections and execute the operation multiple times, once per section. |
| • | Maximum number of sub-match replacements in a single s# pattern: 99 |
Errors (status parameter)
Value |
Description |
|---|---|
-2 to -25 |
matching errors (same as REGEX.SBR) |
-101 to -199 |
pattern compiliation errors (same as REGEX.SBR) |
-93 to -99 |
misc errors (same as REGEX.SBR) |
-92 |
unable to allocate sufficient memory |
-91 |
input file error |
-90 |
output file error |
-89 |
invalid item or syntax error in TCF |
-88 |
too many s#/r# pairs in TCF |
-87 |
TCF maximum line length exceeded |
-86 |
unable to open TCF |
-85 |
TCF section not found |
-84 |
Unable to load REGEX library (PCRE) |
Comments
This function (Op 1) is essentially equivalent to the compiler 'transclude' mechanism (++include with integrated transcopy) and may be used to debug your ++include TCF files. But it is also useful for general purpose file translations.
History
2023 June, A-Shell 6.5.1732: Function added to A-Shell.
