The rfc3339-timestamp Reference Manual

Table of Contents

The rfc3339-timestamp Reference Manual

This is the rfc3339-timestamp Reference Manual, version 0.1.3, generated automatically by Declt version 3.0 "Montgomery Scott" on Wed Mar 25 19:04:27 2020 GMT+0.

1 Introduction

RFC3339-timestamp is relaxed implementation of RFC3339 timestamps
using cl-yacc for parsing and a very simple timestamp class for
keeping track of fractions of a second and offset if you need it to
survive a decode/encode round trip.

A known limitation is that fractions of a second are limited to 10
digits. The parser implementation is quite relaxed about what it
passes. For instance a single space is allowed in place of a T for
date time seperation. Z or time offset is not needed at all and when
left out the parser will assume the timestamp is UTC+00:00. Fractions
are of course optional although that is also true per the RFC.

Another limitation is that dates prior to 1900-01-01 01:00:00 cannot
be represented because that is when universal time which is used
internally starts.

If you don't care for the relaxed mode of the parser you can make it
stricter by pushing :rfc3339-strict-parser to your *features* and
recompile. This will make the parser only accept true RFC3339
timestamps.

The other kind of timestamp that will be parsed if
:rfc3339-strict-parser is not in *features* is the specific format
used by xml-rpc. Which to my understanding is YYYYMMDDTHH:MM:SS.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 rfc3339-timestamp

Author

Peter Stiernström <peter@stiernstrom.se>

License

BSD

Description

A Common Lisp implementation of timestamps as defined by RFC3339

Version

0.1.3

Dependency

yacc

Source

rfc3339-timestamp.asd (file)

Components

• src/package.lisp (file)
• src/timestamp.lisp (file)
• src/parser.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 rfc3339-timestamp.asd

Location

rfc3339-timestamp.asd

Systems

rfc3339-timestamp (system)

3.1.2 rfc3339-timestamp/src/package.lisp

Parent

rfc3339-timestamp (system)

Location

src/package.lisp

Packages

rfc3339

3.1.3 rfc3339-timestamp/src/timestamp.lisp

Dependency

src/package.lisp (file)

Parent

rfc3339-timestamp (system)

Location

src/timestamp.lisp

Exported Definitions

• *default-offset* (special variable)
• fraction-of (method)
• (setf fraction-of) (method)
• local-date-string (method)
• local-time-of (method)
• local-time-string (method)
• make-timestamp (function)
• offset-of (method)
• (setf offset-of) (method)
• rfc3339-timestamp (method)
• timestamp (class)
• utc-date-string (method)
• utc-time-of (method)
• (setf utc-time-of) (method)
• utc-time-string (method)
• xml-rpc-timestamp (method)

Internal Definitions

• date-string (function)
• time-string (function)

3.1.4 rfc3339-timestamp/src/parser.lisp

Dependency

src/timestamp.lisp (file)

Parent

rfc3339-timestamp (system)

Location

src/parser.lisp

Exported Definitions

• malformed-timestamp (condition)
• parse-string (function)

Internal Definitions

• *rfc3339-parser* (special variable)
• collapse (function)
• collapse-butfirst (function)
• create-timestamp (function)
• fault-string-of (method)
• (setf fault-string-of) (method)
• flatten (function)
• offset-seconds (function)
• rfc3339-lexer (function)
• the-values (function)
• unseparate (function)
• unseparate-butlast (function)

4 Packages

Packages are listed by definition order.

4.1 rfc3339

Source

src/package.lisp (file)

Use List

• yacc
• common-lisp

Exported Definitions

• *default-offset* (special variable)
• fraction-of (generic function)
• fraction-of (method)
• (setf fraction-of) (method)
• (setf fraction-of) (generic function)
• local-date-string (generic function)
• local-date-string (method)
• local-time-of (generic function)
• local-time-of (method)
• local-time-string (generic function)
• local-time-string (method)
• make-timestamp (function)
• malformed-timestamp (condition)
• offset-of (generic function)
• offset-of (method)
• (setf offset-of) (method)
• (setf offset-of) (generic function)
• parse-string (function)
• rfc3339-timestamp (generic function)
• rfc3339-timestamp (method)
• timestamp (class)
• utc-date-string (generic function)
• utc-date-string (method)
• utc-time-of (generic function)
• utc-time-of (method)
• (setf utc-time-of) (method)
• (setf utc-time-of) (generic function)
• utc-time-string (generic function)
• utc-time-string (method)
• xml-rpc-timestamp (generic function)
• xml-rpc-timestamp (method)

Internal Definitions

• *rfc3339-parser* (special variable)
• collapse (function)
• collapse-butfirst (function)
• create-timestamp (function)
• date-string (function)
• fault-string-of (generic function)
• fault-string-of (method)
• (setf fault-string-of) (method)
• (setf fault-string-of) (generic function)
• flatten (function)
• offset-seconds (function)
• rfc3339-lexer (function)
• the-values (function)
• time-string (function)
• unseparate (function)
• unseparate-butlast (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *default-offset*

Package

rfc3339

Source

src/timestamp.lisp (file)

5.1.2 Functions

Function: make-timestamp &key UTC-TIME FRACTION OFFSET

When supplying utc-time you must make sure that you also supply a correct offset. For UTC+00:00 the offset is 0. For UTC-01:00 the offset would be -3600 and for UTC+01:00 the offset would be 3600.

Should you supply an offset or set *default-offset* to a value which does not translates to whole hours and seconds and thus can not be represented using a time offset of just hours and minutes we will break horribly so that you notice it.

Package

rfc3339

Source

src/timestamp.lisp (file)

Function: parse-string STRING

Package

rfc3339

Source

src/parser.lisp (file)

5.1.3 Generic functions

Generic Function: fraction-of OBJECT

Generic Function: (setf fraction-of) NEW-VALUE OBJECT

Package

rfc3339

Methods

Method: fraction-of (TIMESTAMP timestamp)

Method: (setf fraction-of) NEW-VALUE (TIMESTAMP timestamp)

Represents the fractions that can not be represented using whole seconds of universal time.

Source

src/timestamp.lisp (file)

Generic Function: local-date-string TIMESTAMP &optional STREAM

Package

rfc3339

Methods

Method: local-date-string (TIMESTAMP timestamp) &optional STREAM

Source

src/timestamp.lisp (file)

Generic Function: local-time-of TIMESTAMP

Package

rfc3339

Methods

Method: local-time-of (TIMESTAMP timestamp)

Source

src/timestamp.lisp (file)

Generic Function: local-time-string TIMESTAMP &optional STREAM

Package

rfc3339

Methods

Method: local-time-string (TIMESTAMP timestamp) &optional STREAM

Source

src/timestamp.lisp (file)

Generic Function: offset-of OBJECT

Generic Function: (setf offset-of) NEW-VALUE OBJECT

Package

rfc3339

Methods

Method: offset-of (TIMESTAMP timestamp)

Method: (setf offset-of) NEW-VALUE (TIMESTAMP timestamp)

Represent the offset in seconds relative to UTC. UTC+1 should be an offset of -3600

Source

src/timestamp.lisp (file)

Generic Function: rfc3339-timestamp TIMESTAMP &optional STREAM

Package

rfc3339

Methods

Method: rfc3339-timestamp (TIMESTAMP timestamp) &optional STREAM

This is the timestamp such as it should look according to
RFC3339. Unfortunately it doesn’t work for xml-rpc which uses someones ugly arbitrary idea of iso8601 and thus doesn’t allow for fractions or timezones.

Source

src/timestamp.lisp (file)

Generic Function: utc-date-string TIMESTAMP &optional STREAM

Package

rfc3339

Methods

Method: utc-date-string (TIMESTAMP timestamp) &optional STREAM

Source

src/timestamp.lisp (file)

Generic Function: utc-time-of OBJECT

Generic Function: (setf utc-time-of) NEW-VALUE OBJECT

Package

rfc3339

Methods

Method: utc-time-of (TIMESTAMP timestamp)

Method: (setf utc-time-of) NEW-VALUE (TIMESTAMP timestamp)

The timestamp as a universal time value with the
accuracy of on second. This should be in UTC and the offset should go in the offset slot.

Source

src/timestamp.lisp (file)

Generic Function: utc-time-string TIMESTAMP &optional STREAM

Package

rfc3339

Methods

Method: utc-time-string (TIMESTAMP timestamp) &optional STREAM

Source

src/timestamp.lisp (file)

Generic Function: xml-rpc-timestamp TIMESTAMP &optional STREAM

Package

rfc3339

Methods

Method: xml-rpc-timestamp (TIMESTAMP timestamp) &optional STREAM

This is the version of iso8601 that is used at xmlrpc.com/spec and that ruby seems to like. We use local-time because when using xml-rpc the time zone should be part of the api documentation rather than the timestamp which is a bit limiting...

Source

src/timestamp.lisp (file)

5.1.4 Conditions

Condition: malformed-timestamp ()

Package

rfc3339

Source

src/parser.lisp (file)

Direct superclasses

condition (condition)

Direct methods

• fault-string-of (method)
• fault-string-of (method)

Direct slots

Slot: fault-string

Initargs

:fault-string

Readers

fault-string-of (generic function)

Writers

(setf fault-string-of) (generic function)

5.1.5 Classes

Class: timestamp ()

Package

rfc3339

Source

src/timestamp.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• print-object (method)
• xml-rpc-timestamp (method)
• rfc3339-timestamp (method)
• local-time-string (method)
• local-date-string (method)
• utc-time-string (method)
• utc-date-string (method)
• local-time-of (method)
• offset-of (method)
• offset-of (method)
• fraction-of (method)
• fraction-of (method)
• utc-time-of (method)
• utc-time-of (method)

Direct slots

Slot: utc-time

The timestamp as a universal time value with the
accuracy of on second. This should be in UTC and the offset should go in the offset slot.

Initargs

:utc-time

Readers

utc-time-of (generic function)

Writers

(setf utc-time-of) (generic function)

Slot: fraction

Represents the fractions that can not be represented using whole seconds of universal time.

Initargs

:fraction

Initform

0

Readers

fraction-of (generic function)

Writers

(setf fraction-of) (generic function)

Slot: offset

Represent the offset in seconds relative to UTC. UTC+1 should be an offset of -3600

Initargs

:offset

Readers

offset-of (generic function)

Writers

(setf offset-of) (generic function)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *rfc3339-parser*

Package

rfc3339

Source

src/parser.lisp (file)

5.2.2 Functions

Function: collapse &rest YS

Package

rfc3339

Source

src/parser.lisp (file)

Function: collapse-butfirst &rest PARTS

Package

rfc3339

Source

src/parser.lisp (file)

Function: create-timestamp &rest PARTS

Package

rfc3339

Source

src/parser.lisp (file)

Function: date-string TIME &optional STREAM

Package

rfc3339

Source

src/timestamp.lisp (file)

Function: flatten TREE

Package

rfc3339

Source

src/parser.lisp (file)

Function: offset-seconds &rest VALUES

Package

rfc3339

Source

src/parser.lisp (file)

Function: rfc3339-lexer STRING

Package

rfc3339

Source

src/parser.lisp (file)

Function: the-values &rest VALUES

Package

rfc3339

Source

src/parser.lisp (file)

Function: time-string TIME &optional STREAM

Package

rfc3339

Source

src/timestamp.lisp (file)

Function: unseparate &rest VALUES

Package

rfc3339

Source

src/parser.lisp (file)

Function: unseparate-butlast &rest VALUES

Package

rfc3339

Source

src/parser.lisp (file)

5.2.3 Generic functions

Generic Function: fault-string-of CONDITION

Generic Function: (setf fault-string-of) NEW-VALUE CONDITION

Package

rfc3339

Methods

Method: fault-string-of (CONDITION malformed-timestamp)

Method: (setf fault-string-of) NEW-VALUE (CONDITION malformed-timestamp)

Source

src/parser.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types