suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

improve docs on version numbers

Browse Source 
Closes #2309
This commit is contained in:
Matthew Flatt 2018-10-11 09:17:15 -06:00
parent 9f839c1161
commit 959b8778d3
2 changed files with 58 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
pkgs/racket-doc/pkg/scribblings/pkg.scrbl
View File

@ -70,9 +70,15 @@ Each @tech{package} has associated @deftech{package metadata}:
@item{a @deftech{version} --- a string of the form @nonterm{maj}@litchar{.}@nonterm{min},
@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}, or
@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel},
@margin-note*{The constraints on version numbers are consistent with @racketmodname[version/utils]
and force version numbers to be in a canonical form. For example, a would-be version
string @racket["4.3.0"] must be written instead as @racket["4.3"], @racket["4.3.1.0"]
must be written instead as @racket["4.3.1"], and @racket["4"] must be written as @racket["4.0"].}
where @nonterm{maj}, @nonterm{min}, @nonterm{sub}, and @nonterm{rel} are
all canonical decimal representations of natural numbers, @nonterm{min} has no more
than two digits, and @nonterm{sub} and @nonterm{rel} has no more than
all canonical decimal representations of natural numbers, @nonterm{rel} is not @litchar{0},
@nonterm{sub} is not @litchar{0} unless
@nonterm{rel} is supplied, @nonterm{min} has no more
than two digits, and @nonterm{sub} and @nonterm{rel} have no more than
three digits. A version is intended to reflect available features of
a package, and should not be confused with different releases of
a package as indicated by the @tech{checksum}.}

62
pkgs/racket-doc/version/version.scrbl
View File

@ -73,40 +73,78 @@ indicates the current state of the current installation:
@defmodule[version/utils]{
The @racketmodname[version/utils] library provides a few of convenient
utilities for dealing with version strings. Unless explicitly noted,
these functions do not handle legacy versions of Racket.}
utilities for dealing with version strings.}
@defproc[(valid-version? [v any/c]) boolean?]{
Returns @racket[#t] if @racket[v] is a valid Racket version
string, @racket[#f] otherwise.}
string, @racket[#f] otherwise.
A valid version has one of the following forms:
@itemlist[
@item{@nonterm{maj}@litchar{.}@nonterm{min}}
@item{@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}}
@item{@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel}}
]
subject to the following constraints:
@itemlist[
@item{@nonterm{maj}, @nonterm{min}, @nonterm{sub}, and
@nonterm{rel} are all canonical decimal representations of
natural numbers (i.e., decimal digits with no leading
@litchar{0} unless the number is exactly @litchar{0})}
@item{@nonterm{rel} is not @litchar{0}}
@item{@nonterm{sub} is not @litchar{0} unless @nonterm{rel} is included}
@item{@nonterm{min} has no more than two digits}
@item{@nonterm{sub} and @nonterm{rel} have no more than three digits}
]
The constraints force version numbers to be in a canonical form. For
example, a would-be version string @racket["4.3.0"] must be written
instead as @racket["4.3"], @racket["4.3.1.0"] must be written
instead as @racket["4.3.1"], and @racket["4"] must be written as
@racket["4.0"].}
@defproc[(version->list [str valid-version?])
(list/c integer? integer? integer? integer?)]{
Returns a list of four numbers that the given version string
represent. @racket[str] is assumed to be a valid version.}
represent.}
@defproc[(version<? [str1 valid-version?] [str2 valid-version?]) boolean?]{
Returns @racket[#t] if @racket[str1] represents a version that is
strictly smaller than @racket[str2], @racket[#f] otherwise.
@racket[str1] and @racket[str2] are assumed to be valid versions.}
strictly smaller than @racket[str2], @racket[#f] otherwise.}
@defproc[(version<=? [str1 valid-version?] [str2 valid-version?]) boolean?]{
Returns @racket[#t] if @racket[str1] represents a version that is
smaller than or equal to @racket[str2], @racket[#f] otherwise.
@racket[str1] and @racket[str2] are assumed to be valid versions.}
smaller than or equal to @racket[str2], @racket[#f] otherwise.}
@defproc[(alpha-version? [str valid-version?]) boolean?]{
Returns @racket[#t] if the version that @racket[str] represents is an
alpha version. @racket[str] is assumed to be a valid version.}
alpha version.
A version number of the form @nonterm{maj}@litchar{.}@nonterm{min},
@nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub},
or @nonterm{maj}@litchar{.}@nonterm{min}@litchar{.}@nonterm{sub}@litchar{.}@nonterm{rel}
is an alpha version if @nonterm{min} is @litchar{90} or more,
@nonterm{sub} is @litchar{900} or more, or @nonterm{rel} is
@litchar{900} or more.}
@defproc[(version->integer [str string?]) (or/c integer? #f)]{
Converts the version string into an integer. For version
@racket["X.YY.ZZZ.WWW"], the result will be @racketvalfont{XYYZZZWWW}.
This function works also for legacy Racket versions, by
This function works also for legacy Racket versions by
translating @racket["XYY.ZZZ"] to @racketvalfont{XYYZZZ000}. The
resulting integer can thefore be used to conveniently compare any two
(valid) version strings. If the version string is invalid the
resulting value is @racket[#f].
(valid) version strings. If the version string is invalid as either a
regular version string or a legacy version string, the resulting
value is @racket[#f].
Note that this is the only function that deals with legacy version
strings.}