PatchString (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (syntax digram, tags and links)
Line 1: Line 1:
{{Template:Stringlist:PatchString subtitle}}
{{Template:Stringlist:PatchString subtitle}}


This method uses <tt>.diff</tt> text output to update text that is stored in a Long<var>String</var>. Typically, a <tt>.diff</tt> 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,
This method uses Unix-style <var class="term">[http://en.wikipedia.org/wiki/Diff diff]</var> output to update text lines that are stored in a <var>LongString</var>. Typically, a <var class="term">[http://en.wikipedia.org/wiki/Diff diff]</var> 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,


<p class="code">patch = diff(base, updated)
<p class="code">patch = diff(base, updated)
</p>
</p>


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 <var>PatchString</var> 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 <var>PatchString</var> method applies a given patch file (converted to a <var>Stringlist</var>) to a base file (converted to a Long<var>String</var>), and it returns a Long<var>String</var> that is the base file updated by the differences contained in the patch file.
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. <var>PatchString</var> supports only a character-oriented patch. <var>PatchString</var> applies a given patch file (converted to a <var>Stringlist</var>) to a base file (converted to a <var>LongString</var>), returning a <var>LongString</var> that is the base file updated by the differences contained in the patch file. For working with line-oriented diff output, use the <var>[[Patch (Stringlist function)|Patch]]</var> or <var>[[PatchLines (Stringlist function)|PatchLines]]</var>.


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 patch file you use is assumed to have the format of a patch from the Google Code <var class="term">[http://code.google.com/p/google-diff-match-patch/ "Diff, Match and Patch Library for Plain Text"]</var>. 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 <b><i>without the two header lines</i></b> which contain file names and timestamps, and it has context character strings instead of context lines.
 
The <var>PatchString</var> method is available as of <var class=product>Sirius Mods</var> Version 7.2.
 
<var>PatchString</var> is a member of the [[Stringlist class]].


==Syntax==
==Syntax==
Line 18: Line 14:
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>updStr</th>
<tr><th>updString</th>
<td>A Long<var>String</var> to contain the updated version of '''baseStr''', the base file. </td></tr>
<td>A <var>LongString</var> to contain the updated version of <var class="term">baseString</var>, the base file. </td></tr>
<tr><th>patchSL</th>
<tr><th>sl</th>
<td>A <var>Stringlist</var> object that contains the patch file (each line stored as a '''patchSL''' item). </td></tr>
<td>A <var>Stringlist</var> object that contains the patch file (each line stored as an individual <var class="term">sl</var> item). </td></tr>
<tr><th>baseStr</th>
<tr><th>baseString</th>
<td>A Long<var>String</var> that contains the base file. </td></tr>
<td>A <var>LongString</var> that contains the base file.</td></tr>
<tr><th>Options='ErrRet'</th>
<tr><th>Options</th>
<td>The optional Options argument (name required) is the string value <tt>.ErrRet</tt>, which may be specified in uppercase or lowercase. If you specify <tt>.Options='ErrRet'</tt>, <var>PatchString</var> method errors return a null '''updStr''' string and no error message instead of canceling the request. If you do not specify <tt>.Options='ErrRet'</tt> and a method error occurs, you receive an error message and the run is cancelled.</td></tr>
<td>The optional Options argument (name required) is the string value <code>ErrRet</code>, which may be specified in uppercase or lowercase. If you specify <code>Options='ErrRet'</code>, <var>PatchString</var> method errors return a null <var>updString</var> string and no error message instead of canceling the request. If you do not specify <code>Options='ErrRet'</code> and a method error occurs, you receive an error message and the request is cancelled.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The representation of the patch file data in <var>Stringlist</var> form should match the original patch exactly. For example, it is critical to preserve leading and trailing blanks.<li>As shown in the example below, the [[AppendOpenProcedure (Stringlist function)]] and [[CreateLines (Stringlist function)]] work well for converting text from procedure to <var>Stringlist</var> to Long<var>String</var>, but be aware that they do not preserve leading and trailing blanks.
<li>The representation of the patch file data in <var>Stringlist</var> form should match the original patch exactly. For example, it is critical to preserve leading and trailing blanks.<li>As shown in the example below, the <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> and <var>[[CreateLines (Stringlist function)|CreateLines]]</var> work well for converting text from procedure to <var>Stringlist</var> to <var>LongString</var>; but, be aware, that they do not preserve leading and trailing blanks.
<li>The <var>PatchString</var> method is available as of <var class="product">Sirius Mods</var> Version 7.2.
</ul>
</ul>


==Examples==
==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 <var>Stringlist</var> items) is a workaround to preserve the necessary blanks in the patch file.
In the following example, a patch file (procedure <code>BASEDIFF.STR</code>) is applied to a base file (<code>BASEFILE.STR</code>) to reproduce the updated version of the base file. The contents of <code>BASEDIFF.STR</code> were initially created at a PC. Since simple transfer to a procedure loses some required trailing blanks, the approach used below (explicit specification of <var>Stringlist</var> items) is a workaround to preserve the necessary blanks in the patch file.


<p class="code">Begin
<p class="code">Begin
%base is <var>Longstring</var>
  %base is Longstring
%baselist is object stringlist
  %baselist is object stringlist
%ptch is object stringList
  %ptch is object stringList
%upd is <var>Longstring</var>
  %upd is Longstring
%rc is float
  %rc is float
%i is fixed
  %i is fixed


* move base file into stringlist then into longstring
  <nowiki>*</nowiki> move base file into stringlist then into longstring
%baselist = new
  %baselist = new
%rc = $procopn('BASEFILE.STR', 'JALPROC')
  %rc = $procopn('BASEFILE.STR', 'JALPROC')
%baselist:appendOpenProcedure
  %baselist:appendOpenProcedure
%base=%baselist:CreateLines('#')
  %base=%baselist:CreateLines('#')
Print '***************Here is base:***************'
  Print '***************Here is base:***************'
Print %base
  Print %base


* move patch file into stringlist
  <nowiki>*</nowiki> move patch file into stringlist
%ptch = new
  %ptch = new
%rc = $procopn('BASEDIFF.STR', 'JALPROC')
  %rc = $procopn('BASEDIFF.STR', 'JALPROC')
%ptch:add('@@ -16,20 +16,28 @@')
  %ptch:add('@@ -16,20 +16,28 @@')
%ptch:add(' see ')
  %ptch:add(' see ')
%ptch:add('-yonder cloud')
  %ptch:add('-yonder cloud')
%ptch:add('+the cloud over there')
  %ptch:add('+the cloud over there')
%ptch:add(' tha')
  %ptch:add(' tha')
%ptch:add('@@ -39,18 +47,19 @@')
  %ptch:add('@@ -39,18 +47,19 @@')
%ptch:add(' almost ')
  %ptch:add(' almost ')
%ptch:add('-in')
  %ptch:add('-in')
%ptch:add('+the')
  %ptch:add('+the')
%ptch:add(' shape o')
  %ptch:add(' shape o')
%ptch:add('@@ -77,24 +86,18 @@')
  %ptch:add('@@ -77,24 +86,18 @@')
%ptch:add(' By ')
  %ptch:add(' By ')
%ptch:add('-the mass, and ' WITH '''t')
  %ptch:add('-the mass, and ' WITH '''t')
%ptch:add('+golly, it ')
  %ptch:add('+golly, it ')
%ptch:add(' is l')
  %ptch:add(' is l')
Print '***************Here is patch:***************'
  Print '***************Here is patch:***************'
for %i from 1 to %ptch:Count
  for %i from 1 to %ptch:Count
Print 'ptch(' %i ') {' %ptch(%i) '}'
      Print 'ptch(' %i ') {' %ptch(%i) '}'
end for
  end for


* produce updated version of base file
  <nowiki>*</nowiki> produce updated version of base file
%upd = %ptch:Patchstring(%base)
  %upd = %ptch:Patchstring(%base)
Print '***************Here is updated base:***************'
  Print '***************Here is updated base:***************'
Print %upd
  Print %upd
End
End
</p>
</p>
Line 86: Line 83:
<p class="code">***************Here is base:***************
<p class="code">***************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.#
Hamlet: Do you see yonder cloud that's almost in shape of a camel?#Polonius: By the mass, and 'tis like a camel, indeed.#
 
<nowiki>****************Here is patch:***************</nowiki>
****************Here is patch:***************
{@@ -16,20 +16,28 @@}
{@@ -16,20 +16,28 @@}
{ see }
{ see }
Line 103: Line 99:
{+golly, it }
{+golly, it }
{ is l}
{ is l}
 
<nowiki>****************Here is updated base:***************</nowiki>
****************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.#
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.#
</p>
</p>


==See also==
==See also==
<ul><li><var class="term">[http://en.wikipedia.org/wiki/Diff diff]</var> for creation of the patch file <var class="term">sl</var><li><var>[[Patch (Stringlist function)|Patch]]</var> for working with line-oriented diff output.<li><var>[[Patchlines (Stringlist function)|Patchlines]]</var> for revised syntax layout.</ul>
{{Template:Stringlist:PatchString footer}}
{{Template:Stringlist:PatchString footer}}

Revision as of 05:08, 27 January 2011

Update base string with patch Stringlist (Stringlist class)


This method uses Unix-style diff output to update text lines that are stored in a LongString. 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 LongString), returning a LongString 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 LongString 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 LongString 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, the AppendOpenProcedure and CreateLines work well for converting text from procedure to Stringlist to LongString; but, be aware, that they do not preserve leading and trailing blanks.
  • 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 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.#

See also

  • diff for creation of the patch file sl
  • Patch for working with line-oriented diff output.
  • Patchlines for revised syntax layout.
Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=PatchString_(Stringlist_function)&oldid=8706"