Patch (Stringlist function): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (1 revision)
m (link repair)
 
(17 intermediate revisions by 5 users not shown)
Line 1: Line 1:
{{Template:Stringlist:Patch subtitle}}
{{Template:Stringlist:Patch subtitle}}


This method uses Unix-style <tt>.diff</tt> output to update text lines that are stored in a <var>Stringlist</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, '''patch = diff(base, updated)'''. Depending on which diff utility and command format that creates it, a patch may report the differences between the two files using a line orientation or a character orientation:
This method uses Unix-style [http://en.wikipedia.org/wiki/Diff diff] output to update text lines that are stored in a <var>Stringlist</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, <code><i>patch</i> = diff(<i>base</i>, <i>updated</i>)</code>. Depending on which <tt>diff</tt> utility and command format that creates it, a patch may report the differences between the two files using a line orientation or a character orientation:
<ul>
<ul>
<li>In the line orientation, the diff treats each file as a set of lines, and it reports whole-line differences, specifying changes by line number.
<li>In the line orientation, the <tt>diff</tt> treats each file as a set of lines, and it reports whole-line differences, specifying changes by line number.</li>
<li>In the character orientation, the diff treats each file as a single string of characters, and it reports character differences, specifying changes by character position.
<li>In the character orientation, the <tt>diff</tt> treats each file as a single string of characters, and it reports character differences, specifying changes by character position.</li>
</ul>
</ul>


The Patch method supports only a line-oriented patch. For working with character-oriented <tt>.diff</tt> output, use the [[PatchString (Stringlist function)]]. The Patch method applies a given patch file (converted to a Stringlist) to a base file (also a Stringlist), and it returns a Stringlist that is the base file updated by the differences contained in the patch file. Patch has the same functionality as the [[PatchLines (Stringlist function)]], but its syntax is slightly different: it reverses the method object and first argument of PatchLines (and PatchString). ''The patch file you use is assumed to be in line-oriented <tt>.diff</tt> output format.''  The reference source used for this format is the GNU diff manual, '''Comparing and Merging Files''' (see http://www.gnu.org/software/diffutils/manual/html_mono/diff.html). Only output from a normal <tt>.diff</tt> command or from a <tt>. diff [-u | U <i>n</i>]</tt> command is supported. The Patch method is available as of <var class=product>Sirius Mods</var> Version 7.1.
The <var>Patch</var> method supports only line-oriented differences. For working with character-oriented <tt>diff</tt> output, use <var>[[PatchString (Stringlist function)|PatchString]]</var>.
 
<var>Patch</var> applies a given patch file (converted to a <var>Stringlist</var>) to a base file (also a <var>Stringlist</var>), and it returns an output <var>Stringlist</var> that is the base file updated by the differences contained in the patch file. <var>Patch</var> has the same functionality as the <var>[[PatchLines (Stringlist function)|PatchLines]]</var> method, but its syntax is slightly different: it reverses the method object and first argument of <var>PatchLines</var> and <var>PatchString</var>.
 
<p class="note"><b>Note:</b> The patch file you use is assumed to be in line-oriented <tt>diff</tt> output format. The reference source used for this format is the GNU diff manual, see [http://www.gnu.org/software/diffutils/manual/#Top Comparing and Merging Files].
Only output from a normal <tt>diff</tt> command or from a <code>diff [-u | U <i>n</i>]</code> command is supported.</p>


==Syntax==
==Syntax==
{{Template:Stringlist:Patch syntax}}
{{Template:Stringlist:Patch syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>updSL</th>
<tr><th>%updList</th>
<td>A <var>Stringlist</var> object that reproduces the original updated file, that is, '''%sl''' updated by the '''patchStrL''' updates. </td></tr>
<td>A <var>Stringlist</var> object that reproduces the original updated file, that is, <var class="term">sl</var> updated by the <var class="term">patchList</var> updates. </td></tr>
<tr><th>baseSL</th>
 
<td>A <var>Stringlist</var> object that contains the original base file, each line stored as a '''baseSL''' item. </td></tr>
<tr><th>sl</th>
<tr><th>patchSL</th>
<td>A <var>Stringlist</var> object that contains the original base file, each line stored as a <var class="term">sl</var> item. </td></tr>
<td>A <var>Stringlist</var> object that contains the patch file (one line per '''patchSL''' item). </td></tr>
 
<tr><th>Options='ErrRet'</th>
<tr><th>patchList</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>, Patch method errors return a null '''updSL''' <var>Stringlist</var> 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 canceled.</td></tr>
<td>A <var>Stringlist</var> object that contains the patch file (one line per <var class="term">patchList</var> item). </td></tr>
 
<tr><th><var>Options</var></th>
<td>The optional <var>Options</var> 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>Patch</var> method errors return a null <var class="term">%updList</var> <var>Stringlist</var> 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 canceled.</td></tr>
</table>
</table>


==Usage notes==
==Usage notes==
<ul>
<ul>
<li>The <var>Stringlist</var> returned by the Patch method, '''updSL''', is a Null object if Patch encounters a non-canceling error.
<li>The <var>Stringlist</var> returned by the <var>Patch</var> method, <var class="term">%updList</var>, will be a <var>Null</var> object if <var>Patch</var> encounters a non-canceling error.</li>
<li>The Patch method supports '''normal''' and '''unified''' <tt>.diff</tt> output formats only. A supported unified-format patch may either be:
 
<li><var>Patch</var> supports <b>normal</b> and <b>unified</b> <tt>diff</tt> output formats only. A supported unified-format patch may either be:
<ul>
<ul>
<li>Output from <tt>.diff</tt> <tt>.-u</tt>, which includes the three lines of text immediately before and after a change to the base.
<li>Output from <code>diff -u</code>, which includes the three lines of text immediately before and after a change to the base.
<li>Output from <tt>.diff</tt> <tt>.-U</tt> <tt>.<i>n</i></tt>, where <i>n</i> is 0 or greater, which includes the number of lines of surrounding text you specify with <i>n</i>.
<li>Output from <code>diff -U <i>n</i></code>, where <i>n</i> is 0 or greater, which includes the number of lines of surrounding text you specify with <i>n</i>.
</ul>
</ul>
A patch file in '''context''' format (output from <tt>.diff</tt> <tt>.-c</tt> or from <tt>.diff</tt> <tt>.-C</tt> <tt>.<i>n</i></tt></i> is ''not'' supported. If specified, a Null <var>Stringlist</var> object is returned or the run is canceled. A context-format <tt>.diff</tt> also may include the text immediately before and after a change.
A patch file in <b>context</b> format (output from <code>diff -c</code> or from <code>diff -C <i>n</i></code>) is <b><i>not</i></b> supported. If specified, a <var>Null</var> <var>Stringlist</var> object is returned or the request is canceled. A context-format <tt>diff</tt> also may include the text immediately before and after a change.</li>
<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>If the patch contains an '''incomplete line''' warning like " \ No newline at end of file," which indicates a missing line-end character, the Patch method ignores it.
<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>
 
<li>If the patch contains an <i>incomplete line</i> warning like " \ No newline at end of file," which indicates a missing line-end character, <var>Patch</var> ignores it.</li>
 
<li><var>Patch</var> is available as of <var class="product">Sirius Mods</var> Version 7.1.</li>
</ul>
</ul>


==Examples==
==Examples==
In the following example, a patch file (procedure BASEDIFF) is applied to a base file (procedure BASEFILE) to reproduce the updated version of the base file. BASEDIFF contains the diff output (normal), which was sent to ''Model 204'' after comparing the PC files basefile.txt and basefileUpd.txt. The [[AppendOpenProcedure (Stringlist function)]] converts the procedure text to a <var>Stringlist</var>.
In the following example, a patch file (procedure <code>BASEDIFF</code>) is applied to a base file (procedure <code>BASEFILE</code>) to reproduce the updated version of the base file. <code>BASEDIFF</code> contains the diff output (normal), which was sent to <var class="product">Model 204</var> after comparing the PC files <code>basefile.txt</code> and <code>basefileUpd.txt</code>. The <var>[[AppendOpenProcedure (Stringlist function)|AppendOpenProcedire]]</var> converts the procedure text to <var>Stringlists</var>.


<pre>
<p class="code">Begin
Begin
%base is object stringList
%base is object stringList
%ptch is object stringList
%ptch is object stringList
Line 48: Line 63:
%ptch = new
%ptch = new


* move base file into stringlist
&#42;* move base file into stringlist
%rc = $procopn('BASEFILE', 'JALPROC')
%rc = $procopn('BASEFILE', 'JALPROC')
%base:appendOpenProcedure
%base:appendOpenProcedure
Line 54: Line 69:
%base:Print
%base:Print


* move patch file into stringlist
&#42;* move patch file into stringlist
%rc = $procopn('BASEDIFF', 'JALPROC')
%rc = $procopn('BASEDIFF', 'JALPROC')
%ptch:appendOpenProcedure
%ptch:appendOpenProcedure
Line 60: Line 75:
%ptch:Print
%ptch:Print


* produce updated file from patch
&#42;* produce updated file from patch
%upd = %base:Patch(%ptch)
%upd = %base:Patch(%ptch)
Print '****************Here is updated base:***************'
Print '****************Here is updated base:***************'
Line 66: Line 81:


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:
The program results show the updated version of the base file, preceded by a display of the base file and the patch file:


<pre>
<p class="output">***************Here is base:***************
***************Here is base:***************
ATTORNEY: Doctor, before you performed the autopsy,
ATTORNEY: Doctor, before you performed the autopsy,
did you check for a pulse?
did you check for a pulse?
Line 88: Line 102:
WITNESS: Yes, it is possible that he could have been alive
WITNESS: Yes, it is possible that he could have been alive
and practicing law.
and practicing law.
****************Here is patch:***************
<nowiki>****************Here is patch:***************</nowiki>
1,16c1,9
1,16c1,9
< ATTORNEY: Doctor, before you performed the autopsy,< did you check for a pulse?< WITNESS: No.< ATTORNEY: Did you check for blood pressure?< WITNESS: No.< ATTORNEY: Did you check for breathing?< WITNESS: No.< ATTORNEY: So, then it is possible that the patient was alive< when you began the autopsy?< WITNESS: No.< ATTORNEY: How can you be so sure, Doctor?< WITNESS: Because his brain was sitting on my desk in a jar.< ATTORNEY: I see, but could the patient have still been< alive, nevertheless?< WITNESS: Yes, it is possible that he could have been alive< and practicing law.---
< ATTORNEY: Doctor, before you performed the autopsy,
< did you check for a pulse?
< WITNESS: No.
< ATTORNEY: Did you check for blood pressure?
< WITNESS: No.
< ATTORNEY: Did you check for breathing?
< WITNESS: No.
< ATTORNEY: So, then it is possible that the patient was alive
< when you began the autopsy?
< WITNESS: No.
< ATTORNEY: How can you be so sure, Doctor?
< WITNESS: Because his brain was sitting on my desk in a jar.
< ATTORNEY: I see, but could the patient have still been
< alive, nevertheless?
< WITNESS: Yes, it is possible that he could have been alive
< and practicing law.
---
> ATTORNEY: Is it possible that the patient was alive
> ATTORNEY: Is it possible that the patient was alive
> when you began the autopsy?
> when you began the autopsy?
Line 100: Line 130:
> WITNESS: Yes. It is possible that he could have been alive
> WITNESS: Yes. It is possible that he could have been alive
> and practicing law.
> and practicing law.
****************Here is updated base:***************
<nowiki>****************Here is updated base:***************</nowiki>
ATTORNEY: Is it possible that the patient was alive
ATTORNEY: Is it possible that the patient was alive
when you began the autopsy?
when you began the autopsy?
Line 110: Line 140:
WITNESS: Yes. It is possible that he could have been alive
WITNESS: Yes. It is possible that he could have been alive
and practicing law.
and practicing law.
</pre>
</p>


==See also==
<ul>
<li>[http://en.wikipedia.org/wiki/Diff diff] for creation of the patch file <var>StringList</var>.</li>
<li><var>[[PatchLines (Stringlist function)|PatchLines]]</var> for revised syntax layout.</li>
<li><var>[[PatchString (Stringlist function)|PatchString]]</var> for working with character-oriented <tt>diff</tt> output.</li>
</ul>


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

Latest revision as of 16:06, 26 June 2015

Update base Stringlist with patch Stringlist (Stringlist class)


This method uses Unix-style diff output to update text lines that are stored in a Stringlist.

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 and command format that creates it, a patch may report the differences between the two files using a line orientation or a character orientation:

  • In the line orientation, the diff treats each file as a set of lines, and it reports whole-line differences, specifying changes by line number.
  • In the character orientation, the diff treats each file as a single string of characters, and it reports character differences, specifying changes by character position.

The Patch method supports only line-oriented differences. For working with character-oriented diff output, use PatchString.

Patch applies a given patch file (converted to a Stringlist) to a base file (also a Stringlist), and it returns an output Stringlist that is the base file updated by the differences contained in the patch file. Patch has the same functionality as the PatchLines method, but its syntax is slightly different: it reverses the method object and first argument of PatchLines and PatchString.

Note: The patch file you use is assumed to be in line-oriented diff output format. The reference source used for this format is the GNU diff manual, see Comparing and Merging Files. Only output from a normal diff command or from a diff [-u | U n] command is supported.

Syntax

%updList = sl:Patch( patchList, [Options= string])

Syntax terms

%updList A Stringlist object that reproduces the original updated file, that is, sl updated by the patchList updates.
sl A Stringlist object that contains the original base file, each line stored as a sl item.
patchList A Stringlist object that contains the patch file (one line per patchList item).
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', Patch method errors return a null %updList Stringlist 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 canceled.

Usage notes

  • The Stringlist returned by the Patch method, %updList, will be a Null object if Patch encounters a non-canceling error.
  • Patch supports normal and unified diff output formats only. A supported unified-format patch may either be:
    • Output from diff -u, which includes the three lines of text immediately before and after a change to the base.
    • Output from diff -U n, where n is 0 or greater, which includes the number of lines of surrounding text you specify with n.
    A patch file in context format (output from diff -c or from diff -C n) is not supported. If specified, a Null Stringlist object is returned or the request is canceled. A context-format diff also may include the text immediately before and after a change.
  • 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.
  • If the patch contains an incomplete line warning like " \ No newline at end of file," which indicates a missing line-end character, Patch ignores it.
  • Patch is available as of Sirius Mods Version 7.1.

Examples

In the following example, a patch file (procedure BASEDIFF) is applied to a base file (procedure BASEFILE) to reproduce the updated version of the base file. BASEDIFF contains the diff output (normal), which was sent to Model 204 after comparing the PC files basefile.txt and basefileUpd.txt. The AppendOpenProcedire converts the procedure text to Stringlists.

Begin %base is object stringList %ptch is object stringList %upd is object stringList %rc is float %base = new %ptch = new ** move base file into stringlist %rc = $procopn('BASEFILE', 'JALPROC') %base:appendOpenProcedure Print '***************Here is base:***************' %base:Print ** move patch file into stringlist %rc = $procopn('BASEDIFF', 'JALPROC') %ptch:appendOpenProcedure Print '****************Here is patch:***************' %ptch:Print ** produce updated file from patch %upd = %base:Patch(%ptch) Print '****************Here is updated base:***************' %upd:Print End

The program results show the updated version of the base file, preceded by a display of the base file and the patch file:

***************Here is base:*************** ATTORNEY: Doctor, before you performed the autopsy, did you check for a pulse? WITNESS: No. ATTORNEY: Did you check for blood pressure? WITNESS: No. ATTORNEY: Did you check for breathing? WITNESS: No. ATTORNEY: So, then it is possible that the patient was alive when you began the autopsy? WITNESS: No. ATTORNEY: How can you be so sure, Doctor? WITNESS: Because his brain was sitting on my desk in a jar. ATTORNEY: I see, but could the patient have still been alive, nevertheless? WITNESS: Yes, it is possible that he could have been alive and practicing law. ****************Here is patch:*************** 1,16c1,9 < ATTORNEY: Doctor, before you performed the autopsy, < did you check for a pulse? < WITNESS: No. < ATTORNEY: Did you check for blood pressure? < WITNESS: No. < ATTORNEY: Did you check for breathing? < WITNESS: No. < ATTORNEY: So, then it is possible that the patient was alive < when you began the autopsy? < WITNESS: No. < ATTORNEY: How can you be so sure, Doctor? < WITNESS: Because his brain was sitting on my desk in a jar. < ATTORNEY: I see, but could the patient have still been < alive, nevertheless? < WITNESS: Yes, it is possible that he could have been alive < and practicing law. --- > ATTORNEY: Is it possible that the patient was alive > when you began the autopsy? > WITNESS: No. > ATTORNEY: How can you be so sure, Doctor? > WITNESS: Because his brain was sitting in a jar on my desk. > ATTORNEY: I see. But could the patient have still been > alive, nevertheless? > WITNESS: Yes. It is possible that he could have been alive > and practicing law. ****************Here is updated base:*************** ATTORNEY: Is it possible that the patient was alive when you began the autopsy? WITNESS: No. ATTORNEY: How can you be so sure, Doctor? WITNESS: Because his brain was sitting in a jar on my desk. ATTORNEY: I see. But could the patient have still been alive, nevertheless? WITNESS: Yes. It is possible that he could have been alive and practicing law.

See also

  • diff for creation of the patch file StringList.
  • PatchLines for revised syntax layout.
  • PatchString for working with character-oriented diff output.