source: project/release/5/semantic-version/trunk/README.svnwiki @ 39858

Last change on this file since 39858 was 39858, checked in by Kon Lovett, 5 weeks ago

use record-variant, rename accessors, make-version/version follow convention, add record printer

File size: 10.3 KB
Line 
1[[tags: egg]]
2
3== semantic-version
4
5[[toc:]]
6
7
8== Documentation
9
10A rather busy Semantic Versioning library.
11
12== Usage
13
14<enscript highlight="scheme">
15(import semantic-version)
16</enscript>
17
18=== version-punctuation
19
20<parameter>(version-punctuation [STR]) -> string</parameter>
21
22Returns the string (set) of punctuation characters. The first is always the
23default.
24
25; STR : {{string}} ; punctuation set, default is "._- +;:,"
26
27=== version-tail-zero
28
29<parameter>(version-tail-zero [IGN?]) -> boolean</parameter>
30
31Returns whether trailing 0's are ignored during comparision.
32
33; IGN? : {{boolean}} ; ignore flag, default is {{#f}}.
34
35=== make-version
36
37<procedure>(make-version VER CNT ELM [CHR]) --> version</procedure>
38
39Returns new version with CNT elements, ELM, and punctuation CHR.
40
41; VER : {{version}} ; version to extend.
42; CNT : {{integer}} ; element count.
43; ELM : {{(or number string symbol)}} ; version element.
44; CHR : {{char}} ; version punctuation, default is as above.
45
46=== version
47
48<procedure>(version ELM...) --> version</procedure>
49
50Returns a new version with the specified elements, ELM..., and the default
51punctuation (see {{version-punctuation}}).
52
53; ELM : {{(or number string symbol)}} ; version element.
54
55'''Note''' that the {{symbol}} printname is used internally.
56Returns whether trailing 0's are ignored during comparision.
57
58=== check-version
59=== error-version
60
61<procedure>(check-version LOC OBJ [NAM]) -> version</procedure>
62<procedure>(error-version LOC OBJ [NAM])</procedure>
63
64Similar to ''check-errors'' procedures.
65
66=== version-copy
67
68<procedure>(version-copy VER) --> version</procedure>
69
70Return a copy of the version, sharing only atoms.
71
72; VER : {{version}} ; version to copy.
73
74=== version?
75
76<procedure>(version? OBJ) --> boolean</procedure>
77
78; OBJ : {{*}} ; object to test.
79
80=== version-depth
81
82<procedure>(version-depth VER) --> integer</procedure>
83
84Return the number of elements in the version.
85
86; VER : {{version}} ; version to query.
87
88=== version-elements
89
90<procedure>(version-elements VER) --> (list-of (or number string))</procedure>
91
92Returns list of version elements.
93
94; VER : {{version}} ; version to query.
95
96=== version-separators
97
98<procedure>(version-separators VER) --> (list-of char)</procedure>
99
100Returns list of separator characters (punctuation).
101
102; VER : {{version}} ; version to query.
103
104=== version->list
105
106<procedure>(version->list VER) --> (list-of (or number string char))</procedure>
107
108Returns an "exploded" form, with version elements interleaved with punctuation
109characeters.
110
111; VER : {{version}} ; version to list.
112
113=== list->version
114
115<procedure>(list->version LIS) --> version</procedure>
116
117Returns a version from an "exploded" form, see {{version->list}}.
118
119; LIS : {{(list-of (or number string symbol char))}} ; list of version components.
120
121=== version-compare
122
123<procedure>(version-compare VER1 VER2 [TAIL-ZERO?]) --> integer</procedure>
124
125Returns a negative, zero, or positive integer representing the relative order
126of VER1 and VER2. Compares {{number}} & {{string}} elements ''natively'', but
127in a comparison between a {{number}} & a {{string}} element, the {{string}}
128always takes precedence. Thus {{"1.a.2" < "a.1.2"}}.
129
130; VER1 : {{version}} ; version 1 to compare.
131; VER2 : {{version}} ; version 2 to compare.
132; TAIL-ZERO? : {{boolean}} ; ignore trailing 0's?
133
134Orders versions in the same manner as the ''chicken-install'' tool.
135
136=== version<?
137=== version=?
138=== version>?
139=== version<=?
140=== version>=?
141
142<procedure>(version<? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
143<procedure>(version=? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
144<procedure>(version>? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
145<procedure>(version<=? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
146<procedure>(version>=? VER1 VER2 [TAIL-ZERO?]) --> boolean</procedure>
147
148See {{version-compare}}.
149
150=== version-hash
151
152<procedure>(version-hash VER [BND RND]) --> integer</procedure>
153
154A SRFI 69 compliant hash function for the {{version}} type.
155
156; VER : {{version}} ; version to hash.
157; BND : {{integer}} ; bounds (limit), see SRFI 69.
158; RND : {{integer}} ; randomization (salt), see SRFI 69.
159
160=== version-comparator
161
162<procedure>(version-comparator) --> comparator</procedure>
163
164Returns a SRFI 128 {{comparator}} for the {{version}} type.
165
166; {{comparator-hash-function}} : {{version-hash}}
167; {{comparator-type-test-predicate}} : {{version?}}
168; {{comparator-equality-predicate comparator}} : {{version=?}}
169; {{comparator-ordering-predicate comparator}} : {{version<?}}
170
171=== string->version
172
173<procedure>(string->version STR) --> version</procedure>
174
175Return the parsed form of the STR. The source separator (punctuation) is
176preserved, and restored by {{version->string}}.
177
178; STR : {{string}} ; string to convert.
179
180=== version->string
181
182<procedure>(version->string VER) --> string</procedure>
183
184Return the string form of the VER.
185
186; VER : {{version}} ; version to convert.
187
188=== version-depth+!
189
190<procedure>(version-depth+! VER CNT ELM [CHR]) -> version</procedure>
191
192Returns VER with more "depth", as ELM, interspersed with CHR.
193
194; VER : {{version}} ; version to extend.
195; CNT : {{integer}} ; element count.
196; ELM : {{(or number string symbol)}} ; version element.
197; CHR : {{char}} ; version punctuation, default is as above.
198
199=== version-depth-!
200
201<procedure>(version-depth-! VER CNT) -> version</procedure>
202
203Returns VER with less "depth", as CNT elements are dropped, along with the
204corresponding punctuation.
205
206; VER : {{version}} ; version to extend.
207; CNT : {{integer}} ; element count.
208
209=== version-depth+
210
211<procedure>(version-depth+ VER CNT ELM [CHR]) --> version</procedure>
212
213Returns a copy of VER with more "depth", as ELM, interspersed with CHR.
214
215; VER : {{version}} ; version to extend.
216; CNT : {{integer}} ; element count.
217; ELM : {{(or number string symbol)}} ; version element.
218; CHR : {{char}} ; version punctuation, default is as above.
219
220=== version-depth-
221
222<procedure>(version-depth- VER CNT) --> version</procedure>
223
224Returns a copy of VER with less "depth", as CNT elements are dropped, along
225with the corresponding punctuation.
226
227; VER : {{version}} ; version to extend.
228; CNT : {{integer}} ; element count.
229
230=== version-extend!
231
232<procedure>(version-extend! VER COMP...) -> version</procedure>
233
234Returns VER with added "depth", in the form of a new "tail", in "exploded"
235form.
236
237; VER : {{version}} ; version to extend.
238; COMP : {{(list-of (or number string symbol char))}} ; version components.
239
240=== version-extend
241
242<procedure>(version-extend VER COMP...) --> version</procedure>
243
244Returns copy of VER with added "depth", in the form of a new "tail", in
245"exploded" form.
246
247; VER : {{version}} ; version to extend.
248; COMP : {{(list-of (or number string symbol char))}} ; version components.
249
250=== version-inc!
251
252<procedure>(version-inc! VER [IDX AMT]) -> version</procedure>
253
254Return VER with IDX element incremented by AMT.
255
256; VER : {{version}} ; version to adjust.
257; IDX : {{integer}} ; which element to adjust.
258; AMT : {{number}} ; amount to adjust.
259
260Currently only {{number}} elements may be targets.
261
262=== version-dec!
263
264<procedure>(version-dec! VER [IDX AMT]) -> version</procedure>
265
266Return VER with IDX element decremented by AMT.
267
268; VER : {{version}} ; version to adjust.
269; IDX : {{integer}} ; which element to adjust.
270; AMT : {{number}} ; amount to adjust.
271
272Currently only {{number}} elements may be targets.
273
274=== version-inc
275
276<procedure>(version-inc VER [IDX AMT]) --> version</procedure>
277
278Return copy of VER with IDX element incremented by AMT.
279
280; VER : {{version}} ; version to adjust.
281; IDX : {{integer}} ; which element to adjust.
282; AMT : {{number}} ; amount to adjust.
283
284Currently only {{number}} elements may be targets.
285
286=== version-dec
287
288<procedure>(version-dec VER [IDX AMT]) --> version</procedure>
289
290Return copy of VER with IDX element decremented by AMT.
291
292; VER : {{version}} ; version to adjust.
293; IDX : {{integer}} ; which element to adjust.
294; AMT : {{number}} ; amount to adjust.
295
296Currently only {{number}} elements may be targets.
297
298
299== Example
300<enscript highlight="scheme">
301(import (chicken base) (chicken file) (chicken pathname) (chicken sort)
302        (srfi 1)
303        semantic-version)
304
305(define (egg-repo-versions repo egg)
306  (map! (o string->version pathname-strip-directory)
307        (glob (make-pathname `(,repo ,egg "tags") "*"))) )
308
309(for-each (o print version->string) (sort (egg-repo-versions REPO "apropos") version<?))
310;=> prints release versions in ascending order
311
312(string=? "a.1,b" ((o version->string string->version) "a.1,b"))
313;=> #t
314; but, assuming baseline `version-punctuation'
315(string=? "a.1.b" (version->string (version 'a 1 'b)))
316;=> #t
317
318(define ver1 (version 'a 1 'b 2))
319((o print version->string) ver1)
320;=> "a.1.b.2"
321(version-inc! ver1)
322((o print version->string) ver1)
323;=> "a.1.b.3"
324(version-dec! ver1 1)
325((o print version->string) ver1)
326;=> "a.0.b.3"
327</enscript>
328
329
330== Requirements
331
332[[srfi-1]]
333[[srfi-69]]
334[[srfi-128]]
335[[utf8]]
336
337[[test]]
338
339
340== Author
341
342[[/users/kon-lovett|Kon Lovett]]
343
344
345== Version history
346
347; 0.0.2 : Use record, {{make-version}} & {{version}} follow convention, rename accessors.
348; 0.0.1 : Release.
349
350
351== License
352
353Copyright (C) 2021 Kon Lovett.  All rights reserved.
354
355Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
356conditions are met:
357
358  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
359    disclaimer.
360  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
361    disclaimer in the documentation and/or other materials provided with the distribution.
362  Neither the name of the author nor the names of its contributors may be used to endorse or promote
363    products derived from this software without specific prior written permission.
364
365THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
366OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
367AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
368CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
369CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
370SERVICESLOSS OF USE, DATA, OR PROFITSOR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
371THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
372OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
373POSSIBILITY OF SUCH DAMAGE.
Note: See TracBrowser for help on using the repository browser.