PatchString (Stringlist function)

Update base string with patch Stringlist (Stringlist class)

This method uses .diff text output to update text that is stored in a LongString. Typically, a .diff utility creates a report (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. The PatchString method supports only a character-oriented patch. For working with line-oriented diff output, use the Patch (Stringlist method) or the PatchLines (Stringlist method). The PatchString method applies a given patch file (converted to a Stringlist) to a base file (converted to a LongString), and it returns a LongString that is the base file updated by the differences contained in the patch file.

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" (http://code.google.com/p/google-diff-match-patch/). 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.

The PatchString method is available as of Sirius Mods Version 7.2.

PatchString is a member of the Stringlist class.

Syntax

%updString = sl:PatchString( baseString, [Options= string])

Syntax terms

updStr	A LongString to contain the updated version of baseStr, the base file.
patchSL	A Stringlist object that contains the patch file (each line stored as a patchSL item).
baseStr	A LongString that contains the base file.
Options='ErrRet'	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 updStr 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 run 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, the AppendOpenProcedure (Stringlist function) and CreateLines (Stringlist function) work well for converting text from procedure to Stringlist to LongString, but be aware that they do not preserve leading and trailing blanks.

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

***************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.#