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

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

fix make-version args, use correct record tag, add record print example

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