PatchString (Stringlist function)

From m204wiki
Revision as of 17:25, 3 February 2015 by JAL (talk | contribs) (minor cleanup)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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.


%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.


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

  • Patch for working with line-oriented diff output.
  • PatchLines for revised syntax layout.