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

Stringlist class	List of Stringlist methods	Stringlist methods syntax
Notation conventions for methods