(*
 * Calendar library
 * Copyright (C) 2003 Julien SIGNOLES
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License version 2, as published by the Free Software Foundation.
 * 
 * This library 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 the GNU Library General Public License version 2 for more details
 *)

(*i $Id: printer.mli,v 1.6 2003/09/18 16:07:58 signoles Exp $ i*)

(*S Introduction. 

  In the following, an "event" is either a date or a time or a calendar.
  
  This module implements three printers: one for each kind of events.
  The three printers have the same signature: 
  they mainly implement a [fprint : string -> formatter -> t -> unit] function
  and a [from_fstring : string -> string -> t] function.
  The first one prints an event according to a format string 
  (see below for a description of such a format). 
  The second one converts a string to an event according to a format string.

  A format string follows the unix date utility (with few modifications). 
  It is a string which contains two types of objects: plain characters and 
  conversion specifications. Those specifications are introduced by 
  a [%] character and their meanings are:
  
  \begin{tabular}{l@{\hspace{5mm}}l}
  [%%] & a literal [%]\\
  [%a] & short day name (by using a short version of [day_name])\\
  [%A] & day name (by using [day_name])\\
  [%b] & short month name (by using a short version of [month_name])\\
  [%B] & month name (by using [month_name])\\
  [%c] & shortcut for [%a %b %d %H:%M:%S %Y]\\
  [%d] & day of month (01..31)\\
  [%D] & shortcut for [%m/%d/%y]\\
  [%e] & same as [%_d]\\
  [%h] & same as [%b]\\
  [%H] & hour (00..23)\\
  [%I] & hour (01..12)\\
  [%j] & day of year (001..366)\\
  [%k] & same as [%_H]\\
  [%l] & same as [%_I]\\
  [%m] & month (01..12)\\
  [%M] & minute (00..59)\\
  [%n] & a newline (same as [\n])\\
  [%p] & AM or PM\\
  [%r] & shortcut for [%I:%M:%S %p]\\
  [%S] & second (00..60)\\
  [%t] & a horizontal tab (same as [\t])\\
  [%T] & shortcut for [%H:%M:%S]\\
  [%V] & week number of year (01..53)\\
  [%w] & day of week (1..7)\\
  [%W] & same as [%V]\\
  [%y] & last two digits of year (00..99)\\
  [%Y] & year (four digits)
  \end{tabular}
     
  By default, date pads numeric fields with zeroes. Two special modifiers 
  between [`%'] and a numeric directive are recognized:
     
  \begin{tabular}{l@{\hspace{5mm}}l}
  ['-' (hyphen)] & do not pad the field\\
  ['_' (underscore)] & pad the field with spaces
  \end{tabular}
     
  For example:\\
  a possible output of [%D] is [01/06/03];\\
  a possible output of [the date is %B, the %-dth] is 
  [the date is January, the 6th] is matched by ;\\
  a possible output of [%c] is [Thu Sep 18 14:10:51 2003]. *)

(*S Internationalization. 

  You can manage the string representations of days and months.
  By default, the English names are used but you can change their by
  setting the references [day_name] and [month_name].

  For example,\\
  [day_name := function Date.Mon -> "lundi" | Date.Tue -> "mardi" | 
     Date.Wed -> "mercredi" | Date.Thu -> "jeudi" | Date.Fri -> "vendredi" |
     Date.Sat -> "samedi" | Date.Sun -> "dimanche"]\\
  sets the names of the days to the French names.\\ *)

(* String representation of a day. *)
val day_name : (Date.day -> string) ref

(* [name_of_day d] is equivalent to [!day_name d]. 
   Used by the specification [%A]. *)
val name_of_day : Date.day -> string

(* [short_name_of_day d] returns the 3 first characters of [name_of_day d]. 
   Used by the specification [%a]. *)
val short_name_of_day : Date.day -> string

(* String representation of a month. *)
val month_name : (Date.month -> string) ref

(* [name_of_month m] is equivalent to [!day_month m]. 
   Used by the specification [%B]. *)
val name_of_month : Date.month -> string

(* [short_name_of_month d] returns the 3 first characters of 
   [name_of_month d]. 
   Used by the specification [%b]. *)
val short_name_of_month : Date.month -> string

(*S Generic signature of a printer. *)

module type S = sig
  type t (*r Generic type of a printer. *)

  (* [fprint format formatter x] outputs [x] on [formatter] according to
     the specified [format]. Raise [Invalid_argument] if the format is 
     incorrect. *)
  val fprint : string -> Format.formatter -> t -> unit
    
  (* [print format] is equivalent to [fprint format Format.std_formatter] *)
  val print : string -> t -> unit

  (* Same as [print d] where [d] is the default format 
     (see the printer implementations). *)
  val dprint : t -> unit

  (* [sprint format date] converts [date] to a string according to [format]. *)
  val sprint : string -> t -> string
    
  (* Same as [sprint d] where [d] is the default format
     (see the printer implementations). *)
  val to_string : t -> string

  (* [from_fstring format s] converts [s] to a date according to [format].
     Only the specifications [%%], [%d], [%D], [%m], [%M], [%S], [%T], [%y] 
     and [%Y] are available.
     When the format has only two digits for the year number, 1900 are added
     to this number (see the example).
     
     Raise [Invalid_argument] if either the format is incorrect 
     or the string does not match the format
     or the event cannot be created (e.g. if you do not specify a year for
     a date).

     For example [from_fstring "the date is %D" "the date is 01/06/03"] returns
     a date equivalent to [Date.make 1903 1 6]. *)
  val from_fstring : string -> string -> t

  (* Same as [from_fstring d] where [d] is the default format. *)
  val from_string : string -> t
end

(*S Printer implementations. *)

(* Date printer.

   The specifications which use time functionalities are not available 
   on this printer.

   The default format is [%D]. *)
module DatePrinter : S with type t = Date.t

(* Time printer.

   The specifications which use date functionalities are not available 
   on this printer.

   The default format is [%T]. *)
module TimePrinter : S with type t = Time.t

(* Calendar printer.

   The default format is [%D; %T]. *)
module CalendarPrinter : S with type t = Calendar.t

This document was generated using caml2html