PatchString (Stringlist function)
Update base string with patch Stringlist (Stringlist class)
This method uses Unix-style diff output to update text lines that are stored in a string. Typically, a diff utility creates a report (aka a "patch file") of the differences between two "files," a base file and an updated version of the base file: that is,
patch = diff(base, updated)
Depending on which diff utility is used and the command format that creates it, a patch may report the differences between the two files using a line orientation or a character orientation. PatchString supports only a character-oriented patch. PatchString applies a given patch file (converted to a Stringlist) to a base file (converted to a string), returning a string that is the base file updated by the differences contained in the patch file. For working with line-oriented diff output, use the Patch or PatchLines.
The patch file you use is assumed to have the format of a patch from the Google Code "Diff, Match and Patch Library for Plain Text". Only output like that from that API's patch_toText function is supported. Except for being character-oriented, such output looks like unified Gnu diff output format without the two header lines which contain file names and timestamps, and it has context character strings instead of context lines.
Syntax
%updString = sl:PatchString( baseString, [Options= string])
Syntax terms
| updString | A string to contain the updated version of baseString, the base file. |
|---|---|
| sl | A Stringlist object that contains the patch file (each line stored as an individual sl item). |
| baseString | A string that contains the base file. |
| Options | The optional Options argument (name required) is the string value ErrRet, which may be specified in uppercase or lowercase. If you specify Options='ErrRet', PatchString method errors return a null updString string and no error message instead of canceling the request. If you do not specify Options='ErrRet' and a method error occurs, you receive an error message and the request is cancelled. |
Usage notes
- The representation of the patch file data in Stringlist form should match the original patch exactly. For example, it is critical to preserve leading and trailing blanks.
- As shown in the example below, AppendOpenProcedure and CreateLines work well for converting text from a procedure to a Stringlist and then to a string.
- The PatchString method is available as of Sirius Mods Version 7.2.
Examples
In the following example, a patch file (procedure BASEDIFF.STR) is applied to a base file (BASEFILE.STR) to reproduce the updated version of the base file. The contents of BASEDIFF.STR were initially created at a PC. Since simple transfer to a procedure loses some required trailing blanks, the approach used below (explicit specification of Stringlist items) is a workaround to preserve the necessary blanks in the patch file.
Begin %base is Longstring %baselist is object stringlist %ptch is object stringList %upd is Longstring %rc is float %i is fixed * move base file into stringlist then into longstring %baselist = new %rc = $procopn('BASEFILE.STR', 'JALPROC') %baselist:appendOpenProcedure %base=%baselist:CreateLines('#') Print '***************Here is base:***************' Print %base * move patch file into stringlist %ptch = new %rc = $procopn('BASEDIFF.STR', 'JALPROC') %ptch:add('@@ -16,20 +16,28 @@') %ptch:add(' see ') %ptch:add('-yonder cloud') %ptch:add('+the cloud over there') %ptch:add(' tha') %ptch:add('@@ -39,18 +47,19 @@') %ptch:add(' almost ') %ptch:add('-in') %ptch:add('+the') %ptch:add(' shape o') %ptch:add('@@ -77,24 +86,18 @@') %ptch:add(' By ') %ptch:add('-the mass, and ' WITH t') %ptch:add('+golly, it ') %ptch:add(' is l') Print '***************Here is patch:***************' for %i from 1 to %ptch:Count Print 'ptch(' %i ') {' %ptch(%i) '}' end for * produce updated version of base file %upd = %ptch:Patchstring(%base) Print '***************Here is updated base:***************' Print %upd End
The program results show the updated version of the base file, preceded by a display of the base file and the patch file. In the base and updated files, the number signs (#), which are added by the CreateLines method, separate the concatenated Stringlist items that constitute the strings.
***************Here is base:*************** Hamlet: Do you see yonder cloud that's almost in shape of a camel?#Polonius: By the mass, and 'tis like a camel, indeed.# ****************Here is patch:*************** {@@ -16,20 +16,28 @@} { see } {-yonder cloud} {+the cloud over there} { tha} {@@ -39,18 +47,19 @@} { almost } {-in} {+the} { shape o} {@@ -77,24 +86,18 @@} { By } {-the mass, and 't} {+golly, it } { is l} ****************Here is updated base:*************** Hamlet: Do you see the cloud over there that's almost the shape of a camel?#Polonius: By golly, it is like a camel, indeed.#
See also
- diff for creation of the patch file sl
- Patch for working with line-oriented diff output.
- Patchlines for revised syntax layout.