Section Intro: Dates And Times

THE META-HTML LANGUAGE REFERENCE MANUAL

Debugging Commands

[TOC]

Authorization Tags

Section Intro: Dates And Times

Dates And Times

Synopsis:

Meta-HTML provides a number of pre-defined functions for manipulating date and time objects. Along with the primitive builtins of <date> and <time>, there are several functions defined with the prefix of date which can be used to parse dates, convert between time and date formats, format time strings in a variety of ways, and even produce HTML-based calendars and the like.

Commands:

date
date::canonicalize
date::days-in-month
date::format-time
date::is-leap-year?
date::long-month-name
date::month-start-string

date::month-table
date::month-table-centering-around
date::parse-date
date::seconds-in-month
date::seconds-since-epoch
date::seconds-to-human-readable
date::short-month-name

date::skip-days-backward
date::skip-days-forward
date::skip-months-backward
date::skip-months-forward
parse-date-string
time

<date &optional [SECONDS-SINCE-EPOCH] &key [GMT=TRUE] [ZONE=ZONE] Simple

Returns the date as a string of 24 characters.

The output looks like Sun May 26 03:16:56 2013.

Given the optional argument EPOCH-SECONDS, this number is treated as the number of seconds since 12 midnight, December 31st, 1969, and is converted into the current date.

When the keyword argument GMT=TRUE is supplied, returns the date at the meridian (Greenwich Mean Time) in the same format as used by HTTP headers, such as the Expires header.

Examples:

<date>                  ==> Thu Nov 13 10:52:07 1997
<date gmt=true>         ==> Thu, 13 Nov 1997 18:52:07 GMT
<date <add <time> 60>>  ==> Thu Nov 13 10:53:07 1997

Also see the time function.

<date::canonicalize DATE-STRING Simple

Return the canonical version of DATE-STRING, in the format "MM/DD/YY HH:MM:SS".

Example:

 <date::canonicalize <date>>

05/26/13 03:16:56

<date::days-in-month MONTH &key [YEAR] Simple

Return the number of days in MONTH. MONTH is the name of a month, such as "Apr" or "april".

<date::format-time FORMAT-STRING &optional [TIME] &key [ZONE] Simple

Return a string representation of the date from the time in TIME. If TIME is not supplied, it defaults to the current time. The format string consists of any characters you would like, with the following special sets being replaced by their corresponding elements of the date. Please note that case is significant:

YY: Last two digits of the year.
YYYY: Four digits of the year.
MM: Two digits of month, with January as 01.
MON: 3 characters of month, as in Jan.
MONTH: The long name of the month, as in March
DD: Two digits of day, as in 23.
DDD: 3 character day of week, as in Thu.
DAY: Full name of the weekday, as in Tuesday.
hh: Hours, in 24 hour format, as in 17.
mm: Minutes, as in 43.
ss: Seconds, as in 04.

Example:

 <date::format-time "DAY, MONTH DD, YYYY (DD-MM-YY) at hh:mm:ss">

Sunday, May 26, 2013 (26-05-13) at 03:16:56

<date::is-leap-year? YEAR Simple

Returns "true" if YEAR is a leap year.

<date::long-month-name MONTH Simple

Return the canonical long name of MONTH. MONTH is the name of a month, such as "Apr" or "april".

<date::month-start-string TIME Simple

Return a date string represent the first second of the month specified by TIME.

 <set-var now  = <time>>
 <set-var today= <date <get-var-once now>>>
 <set-var mstart = <date::month-start-string <get-var-once now>>>
 <pre>
  Now: <get-var-once today>
 Then: <get-var-once mstart>
 </pre>

  Now: Sun May 26 03:16:56 2013
 Then: Wed May  1 00:00:01 2013

<date::month-table &optional [TIME] &key [HIGHLIGHT-DAYS[]] [LINK-DAYS[]] [HREF] [SHOW-YEAR] [FORMATTER] [DAY-WIDTH] Simple

Create a table representing the month found in TIME.

Keyword argument HIGHLIGHT-DAYS is an array of day numbers that you would like to have highlighted in the month display.

Keyword argument LINK-DAYS is an array of day numbers that should be linked to HREF in the month display.

The arrays may have overlapping members.

The keyword argument HREF is the document to go to when a linked day is clicked on -- it is passed the day, month, and year, as two digit fields in the POSTED package under the variable names DAY, MONTH, and YEAR.

If keyword argument SHOW-YEAR is non-empty, the year is displayed next to the month name.

Finally, you can control the formatting of each day by supplying a function which takes day, month, year, and keywords of highlight, and link. You pass the name of this function as the value of the keyword argument FORMATTER, and it is called for each day in the month to display.

Example:

 <date::month-table
    highlight-days="3
8" link-days="18
8" href=<thisdoc>>

May
Su Mo Tu We Th Fr Sa
01 02 03 04
05 06 07 08 09 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31

Example:

 <defun myformat day month year &key highlight link>
   <if <get-var-once link>
       <concat <a href="<get-var-once link><cgi-encode day month year>">
               <get-var-once day>
               </a>>
     <if <get-var-once highlight>
         <prog <b><get-var-once day></b>>
       <get-var-once day>>>
 </defun>
<p>
 <date::month-table
    highlight-days="3" link-days="12" href=<thisdoc> formatter=myformat>

May
Su Mo Tu We Th Fr Sa
01 02 03 04
05 06 07 08 09 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31

<date::month-table-centering-around &optional [TIME] [COUNT] &key [BGCOLOR] [FORMATTER] Simple

Display a table of COUNT months, centered around TIME.

TIME defaults to the current time, while COUNT defaults to 3. Example:

 <date::month-table-centering-around>

April 13
Su Mo Tu We Th Fr Sa
01 02 03 04 05 06
07 08 09 10 11 12 13
14 15 16 17 18 19 20
21 22 23 24 25 26 27
28 29 30

<date::parse-date STRING &optional [PACK] Simple

Populates the package PACK with the result of parsing STRING.

If STRING is passed, that string is used instead of <date>, and should be the date in human readable format, just as date returns.

If no PACK is specified, returns an alist of the values instead.

<date::seconds-in-month MONTH Simple

Return the number of seconds in MONTH. MONTH is the name of a month, such as "Apr" or "april".

<date::seconds-since-epoch DATE-STRING Simple

Return the number of seconds that have transpired between Jan 1, 1970 and DATE-STRING.

This interface is deprecated, and is replaced by the more robust date::date-to-time.

<date::seconds-to-human-readable SECONDS Simple

Display the number of seconds passed in SECONDS as a human readable string of text, representing elapsed time. For example:

 <date::seconds-to-human-readable 8734>

2 hours, 25 minutes and 34 seconds

<date::short-month-name MONTH Simple

Return the canonical short name of MONTH. MONTH is the name of a month, such as "Apr" or "april".

<date::skip-days-backward COUNT &optional [TIME] Simple

Return the seconds since the epoch representing the date which is exactly the first second of the day which is COUNT days before the day represented by TIME.

The epoch is defined as Jan 01, 1970, 00:00:00.

TIME defaults to the current time.

<date::skip-days-forward COUNT &optional [TIME] Simple

Return the seconds since the epoch representing the date which is exactly the first second of the day which is COUNT days after the day represented by TIME.

The epoch is defined as Jan 01, 1970, 00:00:00.

TIME defaults to the current time.

<date::skip-months-backward COUNT &optional [TIME] Simple

Return the seconds since the epoch representing the date which is exactly the first of the month which is COUNT months before the month represented by TIME.

The epoch is defined as Jan 01, 1970, 00:00:00.

TIME defaults to the current time.

<date::skip-months-forward COUNT &optional [TIME] Simple

Return the seconds since the epoch representing the date which is exactly the first of the month which is COUNT months following the month represented by TIME.

The epoch is defined as Jan 01, 1970, 00:00:00.

TIME defaults to the current time.

<parse-date-string STRING Simple

Deprecated. Please use date::parse-date instead. <parse-date-string> is equivalent to <date::parse-date <date> date>

<time &optional [DATE-STRING] &key [ZONE] Simple

Returns the current local time, as measured in seconds since the epoch (the change from 23:59:59, December 31, 1969 to 00:00:00 Jan 1, 1970).

If passed DATE-STRING, <time> calls date::date-to-time on that value instead.

This is often useful as input to the date operator. Here is how one might find out the printable date for the time 10 hours from now.

   <date> ==> Wed Jul  3 17:14:53 1996
   <date <add <time> <mul 60 60 10>>>
          ==> Thu Jul  4 03:14:57 1996

Edit Section
Function Index
Variable Index