PatchString (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (minor cleanup)
 
(19 intermediate revisions by 6 users not shown)
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 [http://en.wikipedia.org/wiki/Diff diff] output to update text lines that are stored in a string. Typically, a <tt>diff</tt> 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:


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


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 <tt>diff</tt> 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 string), returning a string that is the base file updated by the differences contained in the patch file. For working with line-oriented <tt>diff</tt> 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 <code>patch_toText</code> function is supported. Except for being character-oriented, such output looks like unified Gnu <tt>diff</tt> 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==
{{Template:Stringlist:PatchString syntax}}
{{Template:Stringlist:PatchString syntax}}
===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 string to contain the updated version of <var class="term">baseString</var>, the base file. </td></tr>
<tr><th>patchSL</th>
 
<td>A <var>Stringlist</var> object that contains the patch file (each line stored as a '''patchSL''' item). </td></tr>
<tr><th>sl</th>
<tr><th>baseStr</th>
<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>
<td>A Long<var>String</var> that contains the base file. </td></tr>
 
<tr><th>Options='ErrRet'</th>
<tr><th>baseString</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>A string that contains the base file.</td></tr>
 
<tr><th><var>Options</var></th>
<td>The optional Options argument ([[Notation conventions for methods#Named arguments|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 class="term">%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, <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedure]]</var> and <var>[[CreateLines (Stringlist function)|CreateLines]]</var> work well for converting text from a procedure to a <var>Stringlist</var> and then to a string.
<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.
 
<pre>
Begin
%base is <var>Longstring</var>
%baselist is object stringlist
%ptch is object stringList
%upd is <var>Longstring</var>
%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
<p class="code">Begin
%upd = %ptch:Patchstring(%base)
%base is Longstring
Print '***************Here is updated base:***************'
%baselist is object stringlist
Print %upd
%ptch is object stringList
%upd is Longstring
%rc is float
%i is fixed
<nowiki>*</nowiki> 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
<nowiki>*</nowiki> 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 '&#39;'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
<nowiki>*</nowiki> produce updated version of base file
%upd = %ptch:Patchstring(%base)
Print '***************Here is updated base:***************'
Print %upd
End
End
</pre>
</p>


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 <var>Stringlist</var> items that constitute the longstrings.
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 <var>Stringlist</var> items that constitute the strings.


<pre>
<p class="output">***************Here is base:***************
***************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 106: Line 103:
{+golly, it }
{+golly, it }
{ is l}
{ is l}
<nowiki>****************Here is updated base:***************</nowiki>
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>


****************Here is updated base:***************
==See also==
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.#
<ul>
</pre>
<li><var>[[Patch (Stringlist function)|Patch]]</var> for working with line-oriented diff output. </li>
<li><var>[[PatchLines (Stringlist function)|PatchLines]]</var> for revised syntax layout. </li>
</ul>


[[Category:Stringlist methods|PatchString function]]
{{Template:Stringlist:PatchString footer}}

Latest revision as of 17:25, 3 February 2015

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

  • 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=74828"