1 |
vapier 08/06/01 01:30:32 |
2 |
|
3 |
Modified: versionator.eclass |
4 |
Log: |
5 |
add eclass documentation by mren #210316 |
6 |
|
7 |
Revision Changes Path |
8 |
1.14 eclass/versionator.eclass |
9 |
|
10 |
file : http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/versionator.eclass?rev=1.14&view=markup |
11 |
plain: http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/versionator.eclass?rev=1.14&content-type=text/plain |
12 |
diff : http://sources.gentoo.org/viewcvs.py/gentoo-x86/eclass/versionator.eclass?r1=1.13&r2=1.14 |
13 |
|
14 |
Index: versionator.eclass |
15 |
=================================================================== |
16 |
RCS file: /var/cvsroot/gentoo-x86/eclass/versionator.eclass,v |
17 |
retrieving revision 1.13 |
18 |
retrieving revision 1.14 |
19 |
diff -u -r1.13 -r1.14 |
20 |
--- versionator.eclass 23 Apr 2007 19:35:05 -0000 1.13 |
21 |
+++ versionator.eclass 1 Jun 2008 01:30:31 -0000 1.14 |
22 |
@@ -1,40 +1,29 @@ |
23 |
-# Copyright 1999-2004 Gentoo Foundation |
24 |
+# Copyright 1999-2008 Gentoo Foundation |
25 |
# Distributed under the terms of the GNU General Public License v2 |
26 |
-# $Header: /var/cvsroot/gentoo-x86/eclass/versionator.eclass,v 1.13 2007/04/23 19:35:05 swegener Exp $ |
27 |
-# |
28 |
-# Original Author: Ciaran McCreesh <ciaranm@g.o> |
29 |
-# |
30 |
+# $Header: /var/cvsroot/gentoo-x86/eclass/versionator.eclass,v 1.14 2008/06/01 01:30:31 vapier Exp $ |
31 |
+ |
32 |
+# @ECLASS: versionator.eclass |
33 |
+# @MAINTAINER: |
34 |
+# base-system@g.o |
35 |
+# @BLURB: functions which simplify manipulation of ${PV} and similar version strings |
36 |
+# @DESCRIPTION: |
37 |
# This eclass provides functions which simplify manipulating $PV and similar |
38 |
# variables. Most functions default to working with $PV, although other |
39 |
# values can be used. |
40 |
-# |
41 |
+# @EXAMPLE: |
42 |
# Simple Example 1: $PV is 1.2.3b, we want 1_2.3b: |
43 |
# MY_PV=$(replace_version_separator 1 '_' ) |
44 |
# |
45 |
# Simple Example 2: $PV is 1.4.5, we want 1: |
46 |
# MY_MAJORV=$(get_major_version ) |
47 |
# |
48 |
-# Full list of user usable functions provided by this eclass (see the functions |
49 |
-# themselves for documentation): |
50 |
-# get_all_version_components ver_str |
51 |
-# get_version_components ver_str |
52 |
-# get_major_version ver_str |
53 |
-# get_version_component_range range ver_str |
54 |
-# get_after_major_version ver_str |
55 |
-# replace_version_separator index newvalue ver_str |
56 |
-# replace_all_version_separators newvalue ver_str |
57 |
-# delete_version_separator index ver_str |
58 |
-# delete_all_version_separators ver_str |
59 |
-# get_version_component_count ver_str |
60 |
-# get_last_version_component_index ver_str |
61 |
-# |
62 |
# Rather than being a number, the index parameter can be a separator character |
63 |
# such as '-', '.' or '_'. In this case, the first separator of this kind is |
64 |
# selected. |
65 |
# |
66 |
# There's also: |
67 |
# version_is_at_least want have |
68 |
-# which may be buggy, so use with caution. |
69 |
+# which may be buggy, so use with caution. |
70 |
|
71 |
# Quick function to toggle the shopts required for some functions on and off |
72 |
# Used because we can't set extglob in global scope anymore (QA Violation) |
73 |
@@ -58,6 +47,9 @@ |
74 |
return 0 |
75 |
} |
76 |
|
77 |
+# @FUNCTION: get_all_version_components |
78 |
+# @USAGE: [version] |
79 |
+# @DESCRIPTION: |
80 |
# Split up a version string into its component parts. If no parameter is |
81 |
# supplied, defaults to $PV. |
82 |
# 0.8.3 -> 0 . 8 . 3 |
83 |
@@ -117,6 +109,9 @@ |
84 |
__versionator_shopt_toggle off |
85 |
} |
86 |
|
87 |
+# @FUNCTION: get_version_components |
88 |
+# @USAGE: [version] |
89 |
+# @DESCRIPTION: |
90 |
# Get the important version components, excluding '.', '-' and '_'. Defaults to |
91 |
# $PV if no parameter is supplied. |
92 |
# 0.8.3 -> 0 8 3 |
93 |
@@ -132,6 +127,9 @@ |
94 |
__versionator_shopt_toggle off |
95 |
} |
96 |
|
97 |
+# @FUNCTION: get_major_version |
98 |
+# @USAGE: [version] |
99 |
+# @DESCRIPTION: |
100 |
# Get the major version of a value. Defaults to $PV if no parameter is supplied. |
101 |
# 0.8.3 -> 0 |
102 |
# 7c -> 7 |
103 |
@@ -146,6 +144,9 @@ |
104 |
__versionator_shopt_toggle off |
105 |
} |
106 |
|
107 |
+# @FUNCTION: get_version_component_range |
108 |
+# @USAGE: [version] |
109 |
+# @DESCRIPTION: |
110 |
# Get a particular component or range of components from the version. If no |
111 |
# version parameter is supplied, defaults to $PV. |
112 |
# 1 1.2.3 -> 1 |
113 |
@@ -173,6 +174,9 @@ |
114 |
__versionator_shopt_toggle off |
115 |
} |
116 |
|
117 |
+# @FUNCTION: get_after_major_version |
118 |
+# @USAGE: [version] |
119 |
+# @DESCRIPTION: |
120 |
# Get everything after the major version and its separator (if present) of a |
121 |
# value. Defaults to $PV if no parameter is supplied. |
122 |
# 0.8.3 -> 8.3 |
123 |
@@ -186,6 +190,9 @@ |
124 |
__versionator_shopt_toggle off |
125 |
} |
126 |
|
127 |
+# @FUNCTION: replace_version_sepaator |
128 |
+# @USAGE: <search> <replacement> [subject] |
129 |
+# @DESCRIPTION: |
130 |
# Replace the $1th separator with $2 in $3 (defaults to $PV if $3 is not |
131 |
# supplied). If there are fewer than $1 separators, don't change anything. |
132 |
# 1 '_' 1.2.3 -> 1_2.3 |
133 |
@@ -222,6 +229,9 @@ |
134 |
__versionator_shopt_toggle off |
135 |
} |
136 |
|
137 |
+# @FUNCTION: replace_all_version_separators |
138 |
+# @USAGE: <replacement> [subject] |
139 |
+# @DESCRIPTION: |
140 |
# Replace all version separators in $2 (defaults to $PV) with $1. |
141 |
# '_' 1b.2.3 -> 1b_2_3 |
142 |
replace_all_version_separators() { |
143 |
@@ -233,6 +243,9 @@ |
144 |
__versionator_shopt_toggle off |
145 |
} |
146 |
|
147 |
+# @FUNCTION: delete_version_separator |
148 |
+# @USAGE: <search> [subject] |
149 |
+# @DESCRIPTION: |
150 |
# Delete the $1th separator in $2 (defaults to $PV if $2 is not supplied). If |
151 |
# there are fewer than $1 separators, don't change anything. |
152 |
# 1 1.2.3 -> 12.3 |
153 |
@@ -246,6 +259,9 @@ |
154 |
__versionator_shopt_toggle off |
155 |
} |
156 |
|
157 |
+# @FUNCTION: delete_all_version_separators |
158 |
+# @USAGE: [subject] |
159 |
+# @DESCRIPTION: |
160 |
# Delete all version separators in $1 (defaults to $PV). |
161 |
# 1b.2.3 -> 1b23 |
162 |
delete_all_version_separators() { |
163 |
@@ -254,10 +270,12 @@ |
164 |
__versionator_shopt_toggle off |
165 |
} |
166 |
|
167 |
+# @FUNCTION: get_version_component_count |
168 |
+# @USAGE: [version] |
169 |
+# @DESCRIPTION: |
170 |
# How many version components are there in $1 (defaults to $PV)? |
171 |
# 1.0.1 -> 3 |
172 |
# 3.0c-r1 -> 4 |
173 |
-# |
174 |
get_version_component_count() { |
175 |
__versionator_shopt_toggle on |
176 |
local a |
177 |
@@ -266,20 +284,25 @@ |
178 |
__versionator_shopt_toggle off |
179 |
} |
180 |
|
181 |
+# @FUNCTION: get_last_version_component_index |
182 |
+# @USAGE: [version] |
183 |
+# @DESCRIPTION: |
184 |
# What is the index of the last version component in $1 (defaults to $PV)? |
185 |
# Equivalent to get_version_component_count - 1. |
186 |
# 1.0.1 -> 3 |
187 |
# 3.0c-r1 -> 4 |
188 |
-# |
189 |
get_last_version_component_index() { |
190 |
__versionator_shopt_toggle on |
191 |
echo $(( $(get_version_component_count "${1:-${PV}}" ) - 1 )) |
192 |
__versionator_shopt_toggle off |
193 |
} |
194 |
|
195 |
+# @FUNCTION: version_is_at_least |
196 |
+# @USAGE: <want> [have] |
197 |
+# @DESCRIPTION: |
198 |
# Is $2 (defaults to $PVR) at least version $1? Intended for use in eclasses |
199 |
# only. May not be reliable, be sure to do very careful testing before actually |
200 |
-# using this. Prod ciaranm if you find something it can't handle. |
201 |
+# using this. |
202 |
version_is_at_least() { |
203 |
__versionator_shopt_toggle on |
204 |
local want_s="$1" have_s="${2:-${PVR}}" r |
205 |
@@ -302,8 +325,11 @@ |
206 |
__versionator_shopt_toggle off |
207 |
} |
208 |
|
209 |
-# Takes two parameters (a, b) which are versions. If a is an earlier version |
210 |
-# than b, returns 1. If a is identical to b, return 2. If b is later than a, |
211 |
+# @FUNCTION: version_compare |
212 |
+# @USAGE: <A> <B> |
213 |
+# @DESCRIPTION: |
214 |
+# Takes two parameters (A, B) which are versions. If A is an earlier version |
215 |
+# than B, returns 1. If A is identical to B, return 2. If A is later than B, |
216 |
# return 3. You probably want version_is_at_least rather than this function. |
217 |
# May not be very reliable. Test carefully before using this. |
218 |
version_compare() { |
219 |
@@ -417,6 +443,9 @@ |
220 |
return 2 |
221 |
} |
222 |
|
223 |
+# @FUNCTION: version_sort |
224 |
+# @USAGE: <version> [more versions...] |
225 |
+# @DESCRIPTION: |
226 |
# Returns its parameters sorted, highest version last. We're using a quadratic |
227 |
# algorithm for simplicity, so don't call it with more than a few dozen items. |
228 |
# Uses version_compare, so be careful. |
229 |
@@ -548,4 +577,3 @@ |
230 |
done |
231 |
__versionator_shopt_toggle off |
232 |
} |
233 |
- |
234 |
|
235 |
|
236 |
|
237 |
-- |
238 |
gentoo-commits@l.g.o mailing list |