Patch (Stringlist function)

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 a line-oriented patch. For working with character-oriented .diff 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 .diff 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 .diff command or from a . diff [-u | U n] command is supported. The Patch method is available as of Sirius Mods Version 7.1.

Syntax

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

Syntax terms

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

Usage notes

• The Stringlist returned by the Patch method, updSL, is a Null object if Patch encounters a non-canceling error.
• The Patch method 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 run 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, the Patch method ignores it.

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

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:<var>Patch</var>(%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.