1rcs(n)                      RCS low level utilities                     rcs(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       rcs - RCS low level utilities
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require rcs  ?0.1?
14
15       ::rcs::text2dict text
16
17       ::rcs::dict2text dict
18
19       ::rcs::file2dict filename
20
21       ::rcs::dict2file filename dict
22
23       ::rcs::decodeRcsPatch text
24
25       ::rcs::encodeRcsPatch pcmds
26
27       ::rcs::applyRcsPatch text pcmds
28
29______________________________________________________________________________
30

DESCRIPTION

32       The  Revision  Control  System, short RCS, is a set of applications and
33       related data formats which allow a system to  persist  the  history  of
34       changes  to  a  text.  It, and its relative SCCS are the basis for many
35       other such systems, like CVS, etc.
36
37       This package does not implement RCS.
38
39       It only provides a number of low level commands which should be  useful
40       in the implementation of any revision management system, namely:
41
42       [1]    The  conversion of texts into and out of a data structures which
43              allow the easy  modification  of  such  text  by  patches,  i.e.
44              sequences  of  instructions  for  the transformation of one text
45              into an other.
46
47       [2]    And the conversion of one particular format for patches, the so-
48              called  RCS patches, into and out of data structures which allow
49              their easy application to texts.
50

COMMANDS

52       ::rcs::text2dict text
53              Converts the argument text into a dictionary containing and rep‐
54              resenting the same text in an indexed form and returns that dic‐
55              tionary as its result.  More information about the format of the
56              result  can  be  found in section TEXT DICT DATA STRUCTURE. This
57              command returns the canonical representation of the input.
58
59       ::rcs::dict2text dict
60              This   command   provides   the   complementary   operation   to
61              ::rcs::text2dict. It converts a dictionary in the form described
62              in section TEXT DICT DATA STRUCTURE back into a text and returns
63              that  text  as its result. The command does accept non-canonical
64              representations of the text as its input.
65
66       ::rcs::file2dict filename
67              This command is identical to ::rcs::text2dict,  except  that  it
68              reads  the text to convert from the file with path filename. The
69              file has to exist and must be readable as well.
70
71       ::rcs::dict2file filename dict
72              This command is identical to ::rcs::2dict2text, except  that  it
73              stores  the  resulting  text in the file with path filename. The
74              file is created if it did not exist, and must be  writable.  The
75              result of the command is the empty string.
76
77       ::rcs::decodeRcsPatch text
78              Converts  the  text  argument into a patch command list (PCL) as
79              specified in the section RCS PATCH COMMAND LIST and returns this
80              list  as  its  result.   It is assumed that the input text is in
81              diff -n format, also known as RCS patch format, as specified  in
82              the  section  RCS  PATCH  FORMAT.   Please note that the command
83              ignores no-ops in the input, in other words  the  resulting  PCL
84              contains only instructions doing something.
85
86       ::rcs::encodeRcsPatch pcmds
87              This   command   provides   the   complementary   operation   to
88              ::rcs::decodeRcsPatch. It convert a patch comand list (PCL) list
89              as  specified  in the section RCS PATCH COMMAND LIST back into a
90              text in RCS PATCH FORMAT and returns that text as its result.
91
92              Note that this command and ::rcs::decodeRcsPatch are not exactly
93              complementary, as the latter strips no-ops from its input, which
94              the encoder cannot put  back  anymore  into  the  generated  RCS
95              patch.  In  other  words, the result of a decode/encode step may
96              not match the original input at the character level, but it will
97              match it at the functional level.
98
99       ::rcs::applyRcsPatch text pcmds
100              This  operation  applies  a patch in the form of a PCL to a text
101              given in the form of a dictionary and returns the modified text,
102              again as dictionary, as its result.
103
104              To  handle  actual  text  use  the commands ::rcs::text2dict (or
105              equivalent) and ::rcs::decodeRcsPatch to  transform  the  inputs
106              into data structures acceptable to this command. Analogously use
107              the command ::rcs::dict2text (or equivalent)  to  transform  the
108              result of this command into actuall text as required.
109

TEXT DICT DATA STRUCTURE

111       A  text  dictionary  is a dictionary whose keys are integer numbers and
112       text strings as the associated values. The keys represent the line num‐
113       bers  of  a  text  and the values the text of that line.  Note that one
114       text can have many representations as a dictionary, as the index values
115       only have to be properly ordered for reconstruction, their exact values
116       do not matter. Similarly the strings may actually span multiple  physi‐
117       cal lines.
118
119       The text
120
121              Hello World,
122              how are you ?
123              Fine, and you ?
124
125       for example can be represented by
126
127              {{1 {Hello World,}} {2 {how are you ?}} {3 {Fine, and you ?}}}
128
129       or
130
131              {{5 {Hello World,}} {8 {how are you ?}} {9 {Fine, and you ?}}}
132
133       or
134
135              {{-1 {Hello World,
136              how are you ?}} {4 {Fine, and you ?}}}
137
138       The  first dictionary is the canonical representation of the text, with
139       line numbers starting at 1, increasing in steps of 1 and without  gaps,
140       and each value representing exactly one physical line.
141
142       All the commands creating dictionaries from text will return the canon‐
143       ical representation of their input text. The commands taking a  dictio‐
144       nary  and  returning  text  will  generally accept all representations,
145       canonical or not.
146
147       The result of applying a patch to a text  dictionary  will  in  general
148       cause the dictionary to become non-canonical.
149

RCS PATCH FORMAT

151       A  patch  is  in  general  a series of instructions how to transform an
152       input text T into a different text T', and also encoded in text form as
153       well.
154
155       The text format for patches understood by this package is a very simple
156       one, known under the names RCS patch or diff -n format.
157
158       Patches in this format contain only two  different  commands,  for  the
159       deletion of old text, and addition of new text. The replacement of some
160       text by a different text is handled as combination of a  deletion  fol‐
161       lowing by an addition.
162
163       The format is line oriented, with each line containing either a command
164       or text data associated with the preceding command.  The first line  of
165       a RCS patch is always a command line.
166
167       The commands are:
168
169       ""     The empty line is a command which does nothing.
170
171       "astart n"
172              A  line starting with the character a is a command for the addi‐
173              tion of text to the output. It is followed by n  lines  of  text
174              data. When applying the patch the data is added just between the
175              lines start and start+1. The same effect is had by appending the
176              data  to  the  existing  text on line start. A non-existing line
177              start is created.
178
179       "dstart n"
180              A line starting with the character d is a command for the  dele‐
181              tion of text from the output. When applied it deletes n lines of
182              text, and the first line deleted is at index start.
183
184       Note that the line indices start always refer  to  the  text  which  is
185       transformed as it is in its original state, without taking the precend‐
186       ing changes into account.
187
188       Note also that the instruction have to be applied  in  the  order  they
189       occur  in  the  patch, or in a manner which produces the same result as
190       in-order application.
191
192       This is the format of results returned by the command  ::rcs::decodeRc‐
193       sPatch   and   accepted   by  the  commands  ::rcs::encodeRcsPatch  and
194       ::rcs::appplyRcsPatch resp.  Note however that the decoder  will  strip
195       no-op  commands,  and the encoder will not generate no-ops, making them
196       not fully complementary at the textual level, only  at  the  functional
197       level.
198
199       And example of a RCS patch is
200
201              d1 2
202              d4 1
203              a4 2
204              The named is the mother of all things.
205
206              a11 3
207              They both may be called deep and profound.
208              Deeper and more profound,
209              The door of all subtleties!
210

RCS PATCH COMMAND LIST

212       Patch  command lists (sort: PCL's) are the data structures generated by
213       patch decoder command and accepted by the patch encoder and  applicator
214       commands.  They  represent  RCS  patches in the form of Tcl data struc‐
215       tures.
216
217       A PCL is a list where each element represents a single  patch  instruc‐
218       tion,  either  an addition, or a deletion. The elements are lists them‐
219       selves, where the first item specifies the command  and  the  remainder
220       represent the arguments of the command.
221
222       a      This  is  the  instruction  for the addition of text. It has two
223              arguments, the index of the line where to add the text, and  the
224              text to add, in this order.
225
226       d      This  is  the  instruction  for the deletion of text. It has two
227              arguments, the index of the line where to start  deleting  text,
228              and the number of lines to delete, in this order.
229
230       This  is  the format returned by the patch decoder command and accepted
231       as input by the patch encoder and applicator commands.
232
233       An example for a patch command is shown below, it represents the  exam‐
234       ple RCS patch found in section RCS PATCH FORMAT.
235
236              {{d 1 2} {d 4 1} {a 4 {The named is the mother of all things.
237
238              }} {a 11 {They both may be called deep and profound.
239              Deeper and more profound,
240              The door of all subtleties!}}}
241

BUGS, IDEAS, FEEDBACK

243       This  document,  and the package it describes, will undoubtedly contain
244       bugs and other problems.  Please report such in the category rcs of the
245       Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please also
246       report any ideas for enhancements  you  may  have  for  either  package
247       and/or documentation.
248
249       When proposing code changes, please provide unified diffs, i.e the out‐
250       put of diff -u.
251
252       Note further that  attachments  are  strongly  preferred  over  inlined
253       patches.  Attachments  can  be  made  by  going to the Edit form of the
254       ticket immediately after its creation, and  then  using  the  left-most
255       button in the secondary navigation bar.
256

SEE ALSO

258       struct, textutil
259

KEYWORDS

261       CVS,  RCS,  RCS patch, SCCS, diff -n format, patching, text conversion,
262       text differences
263

CATEGORY

265       Text processing
266
268       Copyright (c) 2005, Andreas Kupries <andreas_kupries@users.sourceforge.net>
269       Copyright (c) 2005, Colin McCormack <coldstore@users.sourceforge.net>
270
271
272
273
274tcllib                               2.0.2                              rcs(n)
Impressum