#lang scribble/doc @; THIS FILE IS GENERATED @(require scribble/manual) @(require (for-label (planet neil/rfc3339:1:1))) @title[#:version "0.3"]{@bold{rfc3339}: RFC3339 Date and Time Format in Scheme} @author{Neil Van Dyke} License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/rfc3339-scheme/" #:underline? #f]{http://www.neilvandyke.org/rfc3339-scheme/} @defmodule[(planet neil/rfc3339:1:1)] @section{Introduction} The @bold{rfc3339} package implements parsing, formatting, and simple validation of @link["ftp://ftp.rfc-editor.org/in-notes/rfc3339.txt"]{RFC3339} date and time format, which is a subset of @link["http://www.iso.ch/iso/en/prods-services/popstds/datesandtime.html"]{ISO 8601}, intended for use in Internet protocols. Note that full Scheme support of ISO 8601 and various time-related computation is a very different project of the author, and not at all the intention of @bold{rfc3339}. @bold{rfc3339} requires R5RS, SRFI-6, SRFI-9, and two particular regular expression functions. Note that the regular expression functions in Pregexp 1e9 will not work, but are expected to work in subsequent versions of Pregexp. Thus far, @bold{rfc3339} has only been tested under PLT Scheme. @section{Record Type} @tt{rfc3339-record} is an abstract data type for the information in an RFC3339 format time and date. (``@tt{rfc3339-string}'' is used in identifiers to denote the RFC3339 format as a Scheme string.) @defproc[(make-rfc3339-record (year any/c) (month any/c) (mday any/c) (hour any/c) (minute any/c) (second any/c) (secfrac any/c) (offsetmin any/c)) any/c]{ Construct an @tt{rfc3339-record} with the given field values. Each of @schemevarfont{year}, @schemevarfont{month}, @schemevarfont{mday}, @schemevarfont{hour}, @schemevarfont{minute}, and @schemevarfont{second} is @tt{#f} or a nonnegative integer. @schemevarfont{secfrac} is @tt{#f} or a real number that is greater than or equal to 0.0 and less than 1.0. @schemevarfont{offsetmin} is @tt{#f} or a nonnegative integer. Note that @schemevarfont{offsetmin} represents both the hour and minute components of an RFC3339 string. } @defproc[(rfc3339-record? (x any/c)) any/c]{ Predicate for @tt{rfc3339-record}. } @defproc[(rfc3339-record:year (rec any/c)) any/c]{} @defproc[(rfc3339-record:month (rec any/c)) any/c]{} @defproc[(rfc3339-record:mday (rec any/c)) any/c]{} @defproc[(rfc3339-record:hour (rec any/c)) any/c]{} @defproc[(rfc3339-record:minute (rec any/c)) any/c]{} @defproc[(rfc3339-record:second (rec any/c)) any/c]{} @defproc[(rfc3339-record:secfrac (rec any/c)) any/c]{} @defproc[(rfc3339-record:offsetmin (rec any/c)) any/c]{ Get the respective field value of @tt{rfc3339-record} @schemevarfont{rec}. } @defproc[(rfc3339-record:set-year! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-month! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-mday! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-hour! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-minute! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-second! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-secfrac! (rec any/c) (val any/c)) any/c]{} @defproc[(rfc3339-record:set-offsetmin! (rec any/c) (val any/c)) any/c]{ Set the respective field value of @tt{rfc3339-record} @schemevarfont{rec} to @schemevarfont{val}. } @defproc[(rfc3339-record->list (rec any/c)) any/c]{ Yields a list of the @tt{rfc3339-record} @schemevarfont{rec} fields, corresponding to the arguments of the @tt{make-rfc3339-record} procedure. @SCHEMEBLOCK[ (rfc3339-record->list (make-rfc3339-record 1985 4 12 23 20 50 0.52 0)) ==> (1985 4 12 23 20 50 0.52 0) ] } @section{Parsing} The parsing procedures are for constructing a @tt{rfc3339-record}s, lists, and vectors from RFC3339 strings. The underlying parser can also apply a user-supplied closure directly. @defproc[(parse-rfc3339-string (str any/c) (constructor any/c)) any/c]{ Parses RFC3339 string @schemevarfont{str} and applies procedure @schemevarfont{constructor} with the parsed values. The arguments of @schemevarfont{constructor} are the same as those of @tt{make-rfc3339-record}. } @defproc[(string->rfc3339-record (str any/c)) any/c]{ Yields an @tt{rfc3339-record} from RFC3339 string @schemevarfont{str}. } @defproc[(rfc3339-string->list (str any/c)) any/c]{} @defproc[(rfc3339-string->vector (str any/c)) any/c]{ Yields a list or vector (respectively) from the parsed values of RFC3339 string @schemevarfont{str}. The list and vector elements correspond to the arguments of @tt{make-rfc3339-record}. @SCHEMEBLOCK[ (rfc3339-string->list "1985-04-12T23:20:69.52+5:0") ==> (1985 4 12 23 20 69 0.52 300) (rfc3339-string->vector "1985-04-12T23:20:69.52+5:0") ==> #(1985 4 12 23 20 69 0.52 300) ] } @section{Formatting} An RFC3339 string format can be obtained from an @tt{rfc3339-record}. @defproc[(write-rfc3339 (rec any/c) (port any/c)) any/c]{ Write an RFC3339 string format of @tt{rfc3339-record} @schemevarfont{rec} to output port @schemevarfont{port}. } @defproc[(rfc3339-record->string (rec any/c)) any/c]{ Yield an RFC3339 string format of @tt{rfc3339-record} @schemevarfont{rec} as a Scheme string. } @section{Validation} A few procedures are provided for validating @tt{rfc3339-record}s. @defproc[(check-rfc3339-record-date (rec any/c) (explain? any/c)) any/c]{} @defproc[(check-rfc3339-record-time (rec any/c) (explain? any/c)) any/c]{} @defproc[(check-rfc3339-record-offset (rec any/c) (explain? any/c)) any/c]{ Check the respective component of @tt{rfc3339-record} @schemevarfont{rec} for completeness and correctness, yielding @tt{#f} iff no problems were detected. If @schemevarfont{explain?} is true, then true values of these procedures are lists that ``explain'' the error detected. For example: @SCHEMEBLOCK[ (check-rfc3339-record-date (string->rfc3339-record "1999-02") #t) ==> (missing mday) (check-rfc3339-record-date (string->rfc3339-record "1999-02-29") #t) ==> (invalid mday 29 (and (integer? mday) (<= 1 mday (month-days year month)))) (check-rfc3339-record-date (string->rfc3339-record "2000-02-29") #t) ==> #f ] Leap years are calculated correctly. Leap seconds (61st seconds in minutes) are tolerated in any date and time. } @defproc[(check-rfc3339-record-full (rec any/c) (explain? any/c)) any/c]{ Checks all three components. See @tt{check-rfc3339-record-date} et al. } @defproc[(valid-full-rfc3339-record? (rec any/c)) any/c]{ Yields a true value iff @tt{check-rfc3339-record-full} yields a false value. } @section{SRFI-19 Interoperability} @bold{rfc3339} has no dependency on SRFI-19, but a procedure is provided for constructing a SRFI-19 @tt{date}. @defproc[(rfc3339-string->srfi19-date/constructor (str any/c) (make-date any/c)) any/c]{ Contruct a SRFI-19 @tt{date} from an RFC3339 string, where @schemevarfont{str} is the string, and @schemevarfont{make-date} is the SRFI-19 @tt{date} constructor. Applications using SRFI-19 may wish to define an @tt{rfc3339-string->date} procedure: @SCHEMEBLOCK[ (define (rfc3339-string->date str) (rfc3339-string->srfi19-date/constructor str make-date)) ] } @section{History} @itemize[ @item{Version 0.3 --- 2009-03-03 --- PLaneT @tt{(1 1)} License is now LGPL 3. Converted to author's new Scheme adminsitration system. Changes for PLT 4.x. } @item{Version 0.2 --- 2005-12-05 --- PLaneT @tt{(1 0)} Release for PLT 299/3xx. Changed portability note in light of Pregexp post-1e9 bug fix. Minor documentation changes. } @item{Version 0.1 --- 2005-01-30 Initial release. } ] @section[#:tag "Legal"]{Legal} Copyright (c) 2005--2009 Neil Van Dyke. This program is Free Software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 3 of the License (LGPL 3), or (at your option) any later version. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See http://www.gnu.org/licenses/ for details. For other licenses and consulting, please contact the author.