Please enable JavaScript to view this site.

A-Shell Development History

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.