Update of /project/cl-l10n/cvsroot/cl-l10n/doc In directory common-lisp.net:/tmp/cvs-serv7026/doc
Modified Files: cl-l10n.texi Log Message: Changelog 2005-03-31 Date: Thu Mar 31 15:53:47 2005 Author: sross
Index: cl-l10n/doc/cl-l10n.texi diff -u cl-l10n/doc/cl-l10n.texi:1.6 cl-l10n/doc/cl-l10n.texi:1.7 --- cl-l10n/doc/cl-l10n.texi:1.6 Thu Mar 17 12:40:39 2005 +++ cl-l10n/doc/cl-l10n.texi Thu Mar 31 15:53:47 2005 @@ -90,6 +90,7 @@ @item CLISP @item Lispworks @item ECL +@item Allegro CL @end itemize
@@ -239,13 +240,13 @@ @end deffn
@anchor{Function print-time} -@deffn {Function} print-time ut &key show-date show-time (stream *standard-output) (locale *locale) fmt +@deffn {Function} print-time ut &key show-date show-time (stream *standard-output) (locale *locale) fmt time-zone Prints the @code{universal-time} @emph{ut} as a locale specific time to @emph{stream}. -Equivalent to @code{(format-time stream ut show-date show-time locale fmt)}. +Equivalent to @code{(format-time stream ut show-date show-time locale fmt time-zone)}. @end deffn
@anchor{Function format-time} -@deffn {function} format-time stream ut show-date show-time &optional (locale *locale*) fmt +@deffn {function} format-time stream ut show-date show-time &optional (locale *locale*) fmt time-zone Prints the @code{universal-time} @emph{ut} as a locale specific time to @emph{stream}. The format of the time printed is controlled by @emph{show-time} and @emph{show-date}.
@@ -262,10 +263,10 @@ @end table
If @emph{fmt} is not nil then @emph{show-date} and @emph{show-time} are ignored -and @emph{fmt} is used as the format control string. For details of format -directive look at 'man 1 date' although some directives are not supported, namely %U, %V and %W. +and @emph{fmt} is used as the format control string. See the Notes Section for +the defined control characters which can be used.
-Examples (assuming *locale* is ``en_ZA'') +Examples (assuming *locale* is ``en_ZA'' and a CL -2 Time Zone) @verbatim (format t "~:/cl-l10n:format-time/" 3192624000) prints `03/03/01' @@ -281,6 +282,11 @@
(format t "~,v/cl-l10n:format-time/" "%A" 3192624000) prints `Saturday' + +; The Time Zone can be overriden with an extra v argument +(format t "~v,v,v/cl-l10n:format-time/" "en_ZA" "%A" -8 3192624000) + print `Sunday' + @end verbatim @end deffn
@@ -297,7 +303,7 @@ drop in replacements for the ~/cl-l10n:format-?/ calls.
@verbatim -;; These examples assume an en_ZA locale +;; These examples assume an en_ZA locale and a CL -2 Time Zone (in-package :cl-user)
(shadowing-import 'cl-l10n::format) @@ -330,6 +336,30 @@ Parses the string @emph{num-string} into a number using @emph{locale}. @end deffn
+@anchor{Function parse-time} +@deffn {Function} parse-time time-string &key (start 0) (end (length time-string)) (error-on-mismatch nil) (patterns *default-date-time-patterns*) (default-seconds nil) (default-minutes nil) (default-hours nil) (default-day nil) (default-month nil) (default-year nil) (default-zone nil) (default-weekday nil) (locale *locale*) + +Tries very hard to make sense out of the argument time-string using +locale and returns a single integer representing the universal time if +successful. If not, it returns nil. If the :error-on-mismatch +keyword is true, parse-time will signal an error instead of +returning nil. Default values for each part of the time/date +can be specified by the appropriate :default- keyword. These +keywords can be given a numeric value or the keyword :current +to set them to the current value. The default-default values +are 00:00:00 on the current date, current time-zone. + +Example, what date does the string ``02/03/05'' specify? +parse-time will use the current locale or the locale-designator +passed to it to determine the correct format for dates. +In America (en_US) this date is the 3rd of February 2005, with an South African English (en_ZA) +locale this date is the 2nd of March 2005 and with a Swedish locale (sv_SE) it's the 5th of March 2002. + +Note. This is not my work but was done by Jim Healy and is a part of the CMUCL project, + which has been modified to handle differt locales. + +@end deffn +
@section Classes @anchor{Class locale} @@ -348,12 +378,20 @@ @section Conditions @anchor{Condition locale-error} @deftp {Condition} locale-error -Class Precedence: @code{condition} +Class Precedence: @code{error}
Root CL-L10N condition which will be signalled when an exceptional situation occurs. @end deftp
+@anchor{Condition parser-error} +@deftp {Condition} parser-error +Class Precedence: @code{error} +Error which is signalled when an error occurs when parsing numbers +or time strings. +@end deftp + + @node I18N @chapter I18N
@@ -482,17 +520,108 @@ is loaded. If these two have failed then the POSIX locale is loaded as the default.
+@section Time Format Control Characters +The following is a list of each legal control character in a time +format string followed by a description of what is does. +@itemize +@item %% A percentage sign. +@item %a locale's abbreviated weekday name (Sun..Sat) +@item %A locale's full weekday name, variable length (Sunday..Saturday) +@item %b locale's abbreviated month name (Jan..Dec) +@item %B locale's full month name, variable length (January..December) +@item %c locale's date and time (Sat Nov 04 12:02:33 EST 1989) +@item %C century [00-99] +@item %d day of month (01..31) +@item %D date (mm/dd/yy) +@item %e day of month, blank padded ( 1..31) +@item %F same as %Y-%m-%d +@item %g the 2-digit year corresponding to the %V week number +@item %G the 4-digit year corresponding to the %V week number +@item %h same as %b +@item %H hour (00..23) +@item %I hour (01..12) +@item %j day of year (001..366) +@item %k hour ( 0..23) +@item %l hour ( 1..12) +@item %m month (01..12) +@item %M minute (00..59) +@item %n a newline +@item %N nanoseconds (Always 000000000) +@item %p locale's upper case AM or PM indicator (blank in many locales) +@item %P locale's lower case am or pm indicator (blank in many locales) +@item %r time, 12-hour (hh:mm:ss [AP]M) +@item %R time, 24-hour (hh:mm) +@item %s seconds since `00:00:00 1970-01-01 UTC' +@item %S second (00..60) +@item %t a horizontal tab +@item %T time, 24-hour (hh:mm:ss) +@item %u day of week (1..7); 1 represents Monday +@item %U week number of year with Sunday as first day of week (00..53) +@item %V week number of year with Monday as first day of week (01..53) +@item %w day of week (0..6); 0 represents Sunday +@item %W week number of year with Monday as first day of week (00..53) +@item %x locale's date representation (locale-d-fmt) +@item %X locale's time representation (locale-t-fmt) +@item %y last two digits of year (00..99) +@item %Y year (1900...) +@item %z RFC-2822 style numeric timezone (-0500) +@item %Z RFC-2822 style numeric timezone (-0500) +@end itemize + @section Accessors to Locale Values. There are a number of accessor functions to the various locale attributes defined. The functions are named by replacing -underscores with hypens and prepending locale- to the name -For example the attribute int_frac_digits -can be accessed by the function @code{locale-int-frac-digits}. +underscores with hypens and prepending locale- to the name. +The following is each defined accessor function in the format +Category, Keyword and the accessor function for it. +@itemize +@item LC_MONETARY int_curr_symbol @code{locale-int-curr-symbol} +@item LC_MONETARY currency_symbol @code{locale-currency-symbol} +@item LC_MONETARY mon_decimal_point @code{locale-mon-decimal-point} +@item LC_MONETARY mon_thousands_sep @code{locale-mon-thousands-sep} +@item LC_MONETARY mon_grouping @code{locale-mon-grouping} +@item LC_MONETARY positive_sign @code{locale-positive-sign} +@item LC_MONETARY negative_sign @code{locale-negative-sign} +@item LC_MONETARY int_frac_digits @code{locale-int-frac-digits } +@item LC_MONETARY frac_digits @code{locale-frac-digits } +@item LC_MONETARY p_cs_precedes @code{locale-p-cs-precedes } +@item LC_MONETARY p_sep_by_space @code{locale-p-sep-by-space } +@item LC_MONETARY n_cs_precedes @code{locale-n-cs-precedes } +@item LC_MONETARY n_sep_by_space @code{locale-n-sep-by-space } +@item LC_MONETARY p_sign_posn @code{locale-p-sign-posn } +@item LC_MONETARY n_sign_posn @code{locale-n-sign-posn } +@item LC_NUMERIC decimal_point @code{locale-decimal-point} +@item LC_NUMERIC thousands_sep @code{locale-thousands-sep} +@item LC_NUMERIC grouping @code{locale-grouping } +@item LC_TIME abday @code{locale-abday} +@item LC_TIME day @code{locale-day} +@item LC_TIME abmon @code{locale-abmon} +@item LC_TIME mon @code{locale-mon} +@item LC_TIME d_t_fmt @code{locale-d-t-fmt} +@item LC_TIME d_fmt @code{locale-d-fmt} +@item LC_TIME t_fmt @code{locale-t-fmt} +@item LC_TIME am_pm @code{locale-am-pm} +@item LC_TIME t_fmt_ampm @code{locale-t-fmt-ampm} +@item LC_TIME date_fmt @code{locale-date-fmt} +@item LC_MESSAGES yesexpr @code{locale-yesexpr} +@item LC_MESSAGES noexpr @code{locale-noexpr} +@item LC_PAPER height @code{locale-height} +@item LC_PAPER width @code{locale-width} +@item LC_NAME name_fmt @code{locale-name-fmt} +@item LC_NAME name_gen @code{locale-name-gen} +@item LC_NAME name_mr @code{locale-name-mr} +@item LC_NAME name_mrs @code{locale-name-mrs} +@item LC_NAME name_miss @code{locale-name-miss} +@item LC_NAME name_ms @code{locale-name-ms} +@item LC_ADDRESS postal_fmt @code{locale-postal-fmt} +@item LC_TELEPHONE tel_int_fmt @code{locale-tel-int-fmt} +@item LC_MEASUREMENT measurement @code{locale-measurement} +@end itemize
@section Known Issues @itemize @bullet @item LC_COLLATE and LC_CTYPE categories in the locale files are currently ignored. -@item Not all time format directives are supported. +@item Not all time format directives are supported (U, V and W are not implemented). @end itemize