{"size": 5497, "ext": "scrbl", "max_stars_repo_path": "pkgs/racket-doc/version/version.scrbl", "max_stars_repo_name": "lkh01/racket", "max_stars_repo_stars_event_min_datetime": "2018-07-05T21:18:24.000Z", "max_stars_repo_stars_event_max_datetime": "2021-06-04T14:48:37.000Z", "max_issues_repo_path": "pkgs/racket-doc/version/version.scrbl", "max_issues_repo_name": "lkh01/racket", "max_issues_repo_issues_event_min_datetime": "2017-05-10T07:33:20.000Z", "max_issues_repo_issues_event_max_datetime": "2018-07-19T15:49:46.000Z", "max_forks_repo_path": "pkgs/racket-doc/version/version.scrbl", "max_forks_repo_name": "lkh01/racket", "max_forks_repo_forks_event_min_datetime": "2016-04-25T11:47:57.000Z", "max_forks_repo_forks_event_max_datetime": "2017-05-09T14:52:48.000Z"}
{"max_stars_count": 4, "max_issues_count": 9, "max_forks_count": 3, "avg_line_length": 36.4039735099, "max_line_length": 96, "alphanum_fraction": 0.6770965981}
#lang scribble/doc
@(require scribble/manual
          scribble/bnf
          (for-label version/patchlevel
                     version/check
                     version/utils
                     racket/base
                     racket/contract))

@(define (selflink s) (link s (tt s)))

@title{Version: Racket Version Checking}

The @filepath{version} collection contains several version-related
pieces that are used by Racket.  See also @racket[version] from
@racketmodname[racket/base].

@; ----------------------------------------------------------------------

@section{Installed Patch Level}

@defmodule[version/patchlevel]

@defthing[patchlevel exact-nonnegative-integer?]{

Indicates the current installed patch level, which is normally zero,
but may be updated by patches to DrRacket.}

@; ----------------------------------------

@section{Checking Available Versions}

@defmodule[version/check]

@defproc[(check-version) (or/c symbol? list?)]{

Checks the currently available version on the PLT website
(@selflink["http://download.racket-lang.org"]) and returns a value that
indicates the current state of the current installation:

@itemize[

@item{@racket[`ok] --- You're fine.}

@item{@racket[`(ok-but ,_version)] --- You have a fine stable
  version, but note that there is a newer alpha version available
  numbered @racket[_version].}

@item{@racket[`(newer ,_version)] --- You have an old
  version.  Please upgrade to @racket[_version].}

@item{@racket[`(newer ,_version ,_alpha)] --- You have an
  old-but-stable version, please upgrade to @racket[_version]; you
  may consider also the newer alpha version numbered
  @racket[_alpha].}

@item{@racket[`(error ,_message)] --- An error occurred, and
  @racket[_message] is a string that indicates the error.}

@item{@racket[`(error ,_message ,_additional-info)] --- An error
   occurred; @racket[_message] is a string that indicates the
   error, and @racket[_additional-info] is a string containing a
   system error.  The @racket[_additional-info] content is always
   parenthesizes, so @racket[message] is a short error and
   @racket[(string-append message " " additional-info)] is a
   verbose one.}

]}

@; ----------------------------------------------------------------------

@section{Version Utilities}

@defmodule[version/utils]{
  The @racketmodname[version/utils] library provides a few of convenient
  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.

  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.}

@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.}

@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.}

@defproc[(alpha-version? [str valid-version?]) boolean?]{
  Returns @racket[#t] if the version that @racket[str] represents is an
  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
  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 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.}
