source: project/wiki/eggref/5/patch @ 38035

Last change on this file since 38035 was 38035, checked in by Ivan Raikov, 2 months ago

patch documentation for c5

File size: 5.2 KB
Line 
1[[tags:egg]]
2
3== patch
4
5[[toc:]]
6
7Simple source patch utility.
8
9
10== Documentation
11
12This is a simple source patch utility to enable production and
13application of patches to source files on any platform that supports
14Chicken.
15
16The procedure {{make-patch}} takes a GNU-style diff file on
17{{(current-input-port)}} and produces a corresponding s-expression
18that can be used by the procedure {{apply-patch}}.
19
20In its turn, the {{apply-patch}} procedure takes a patch definition
21and applies it to the input stream on {{(current-input-port)}},
22writing the result to {{(current-output-port)}}.
23
24The procedure {{reverse-patch}} transforms a patch definition into its
25reverse, so that the original patch can be undone.
26
27It is recommended that make-patch be used to produce patches for
28distribution.  These patches can then be interpreted and applied by
29the apply-patch procedure, which has no machine or system dependencies
30beyond the posix package.  The third example above also illustrates
31operation similar to the Larry Wall/Paul Eggert {{patch}} program,
32accepting as input a patch in the form of raw GNU diff file output.
33
34=== S-expression format
35
36The patch definition is composed of a list of forms of the following
37format:
38
39 ([c|a|d] start-line finish-line new-start-line new-finish-line (lines to be deleted) (lines to be inserted))
40
41The forms {{c}}, {{a}} and {{d}} correspond to the change, append and
42delete commands in default GNU diff output.  Where one of the line
43number parameters is omitted in the diff file, this is translated to
44{{#f}} in the corresponding form in the patch definition.  The lists
45{{lines to be deleted}} and {{lines to be inserted}} are ordered lists
46of strings.
47
48Reversing the patch is a straightforward swap: swap the {{a}} and
49{{d}} commands, swap the {{start-line, finish-line}} pair with
50{{new-start-line}} and {{new-finish-line}}, and swap the {{lines to be
51deleted}} and {{lines to be inserted}} lists.
52
53=== Procedures
54
55<procedure>(make-patch)</procedure>
56
57Read GNU diff output on {{(current-input-port)}} and return a patch definition.
58
59<procedure>(apply-patch PATCH-DEFINITION)</procedure>
60
61Apply a patch definition to the text stream on {{(standard-input-port)}} and write the result to {{(current-output-port)}}.
62
63; {{PATCH-DEFINITION}}: A patch definition produced by {{make-patch}}
64
65<procedure>(reverse-patch PATCH-DEFINITION)</procedure>
66
67Produce a patch definition that undoes the patch definition given.
68
69== Examples
70
71
72 ; To write a patch from GNU diff output on (current-input-port):
73 (use patch)
74 (write (make-patch))(newline)
75 
76 ; To apply a patch in a filename argument to (current-input-port)
77 ; and write the result to (current-output-port):
78 (use patch)
79 (apply-patch (with-input-from-file (cadr (argv)) read))
80 
81 ; To apply a patch in a GNU diff file in a filename argument
82 (use patch)
83 (apply-patch (with-input-from-file (cadr (argv)) make-patch))
84 
85 ; To undo a patch in a filename argument, reading the result of applying
86 ; the patch on (current-input-port) and writing the restored original to
87 ; (current-output-port)
88 (use patch)
89 (apply-patch (reverse-patch (with-input-from-file (cadr (argv)) read)))
90
91== Bugs and limitations
92
93This simple utility cannot handle files that have no line terminator
94at the end of the last line.  {{make-patch}} will barf on the diff input
95in such cases.  It shouldn't be too difficult to write a special case
96for this, but an absent line terminator in a text file is usually an
97error or an oversight, so a conscious decision has been made not to
98cater for it.  Feel free to fix this bug.
99
100No effort has been made to duplicate the extreme versatility of the
101Wall/Eggert patch utility.  In particular, any noise in the raw diff
102input will cause make-patch to barf.
103
104== About this egg
105
106=== Author
107
108[[/users/tony sidaway|Tony Sidaway]]
109
110=== Version history
111
112; 1.15 : Ported to CHICKEN 5 [Ivan Raikov]
113; 1.14 : Fix for botched conversion to regex egg [Ivan Raikov]
114; 1.13 : Added regex as a dependency; ported eggdoc documentation to wiki format [Ivan Raikov]
115; 0.12 : Ported to Chicken 4 [Ivan Raikov]
116; 0.11 : Bug 308: does not require '(needs posix)'
117; 0.1 : Initial release
118
119=== License
120
121 Copyright (c) Tony Sidaway <tonysidaway@gmail.com>
122 
123 Permission is hereby granted, free of charge, to any person obtaining
124 a copy of this software and associated documentation files (the
125 "Software"), to deal in the Software without restriction, including
126 without limitation the rights to use, copy, modify, merge, publish,
127 distribute, sublicense, and/or sell copies of the Software, and to
128 permit persons to whom the Software is furnished to do so, subject to
129 the following conditions:
130 
131 The above copyright notice and this permission notice shall be
132 included in all copies or substantial portions of the Software.
133 
134 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
135 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
136 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
137 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
138 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
139 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
140 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
141 SOFTWARE.
Note: See TracBrowser for help on using the repository browser.