3. API

3.1 Variables

Variable: *locale*

The default locale which will be used.

Variable: *locale-path*

The default pathname where locale definition files can be found.

Variable: *locales*

A hash table containing loaded locales keyed on locale name.

Variable: *float-digits*

An integer value which determines the number of digits after the decimal point when all said digits are zero. This variable only has an effect when printing numbers as monetary printing gets this value from the locale.

3.2 Functions

Function: locale-name locale

Returns the name of locale.

Function: locale name &key (use-cache t) (errorp t)

Loads the locale designated by the locale-designator name which is expected to be found in *locale-path*. If use-cache is nil the locale will be forcibly reloaded from path otherwise the cached locale will be returned. If the locale cannot be found and errorp is not nil an error of type locale-error will be signalled.

Function: locale-value locale category-name key

Returns the value of key in cagetory category-name found in the locale locale.

Function: load-all-locales &optional (path *locale-path*)

Load all locales found in pathname path.

Function: print-number number &key (stream *standard-output) no-ts no-dp locale *locale*

Prints number using locale locale. If no-ts is not nil no thousand seperators will be used when printing number. If no-dp is not nil the decimal seperator will be suppressed if number is not an integer.

Function: format-number stream arg no-dp no-ts &optional (locale *locale*)

format-number is intended to be used as an argument to the ~/ / format directive. Example (assuming *locale* is en_ZA)

(format t "~:/cl-l10n:format-number/" 1002932) prints `1,002,932`

Function: print-money value &key (stream *standard-output) use-int-sym no-ts (locale *locale*)

Prints value as a monetary value using locale locale. If no-ts is not nil no thousand seperators will be used when printing number. If use-int-sym is not nil locale-int-curr-symbol will be used instead of the default locale-currency-symbol

Function: format-money stream arg use-int-sym no-ts &optional (locale *locale*)

Prints value as a monetary value using locale locale. format-money is intended to be used as the function to the ~/ / format directive Examples.

(format t "~/cl-l10n:format-money/" 188232.2322) prints `R188,232.23` ;; and (format t "~:/cl-l10n:format-money/" 188232.2322) prints `ZAR 188,232.23`

Function: print-time ut &key show-date show-time (stream *standard-output) (locale *locale) fmt time-zone

Prints the universal-time ut as a locale specific time to stream. Equivalent to (format-time stream ut show-date show-time locale fmt time-zone).

function: format-time stream ut show-date show-time &optional (locale *locale*) fmt time-zone

Prints the universal-time ut as a locale specific time to stream. The format of the time printed is controlled by show-time and show-date.

show-time and show-date are not nil

locale-d-t-fmt

show-time and show-date are nil

locale-t-fmt-ampm or locale-t-fmt if locale-t-fmt-ampm has no apparent value.

show-time is not nil and show-date is nil

locale-t-fmt

show-date is not nil and show-time is nil

locale-d-fmt

If fmt is not nil then show-date and show-time are ignored and 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" and a CL -2 Time Zone) @verbatim (format t "~:/cl-l10n:format-time/" 3192624000) prints `03/03/01'

(format t "~@/cl-l10n:format-time/" 3192624000) prints `18:00:00'

(format t "~:@/cl-l10n:format-time/" 3192624000) prints `Sat 03 Mar 2001 18:00:00 +0200'

(format t "~v,v/cl-l10n:format-time/" "fr_FR" "%A" 3192624000) prints `samedi'

(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'

Function: format stream fmt-string &rest args

Format is an unexported symbol in the cl-l10n package. It's use is to make formatting of dates, times, numbers and monetary values simpler. Shadow importing cl-l10::format into your package gives you a few new format directives. The new directives are ~U : Time and Date (universal-time), ~N : Numbers and ~M : Monetary values. All other format directives are unchanged and work as normal. These new directives are drop in replacements for the ~/cl-l10n:format-?/ calls.

@verbatim ;; These examples assume an en_ZA locale and a CL -2 Time Zone (in-package :cl-user)

(shadowing-import 'cl-l10n::format)

(format t "~:U" 3192624000) prints `03/03/2001'

(format t "~,vU" "%A" 3192624000) prints `Saturday'

(format t "~:N" 3192624000) prints `3,192,624,000'

(format t "~:M" 3192624000) prints `ZAR 3,192,624,000.00`

Macro: formatter fmt-string

Formatter is another unexported symbol in the cl-l10n package Shadow importing formatter gives support for the new format control directives.

Function: parse-number num-string &optional (locale *locale*)

Parses the string num-string into a number using locale.

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.

3.3 Classes

Class: locale

Class Precedence: standard-object The class representing a loaded locale.

Class: category

Class Precedence: standard-object The class representing a loaded category within a locale.

3.4 Conditions

Condition: locale-error

Class Precedence: error

Root CL-L10N condition which will be signalled when an exceptional situation occurs.

Condition: parser-error

Class Precedence: error Error which is signalled when an error occurs when parsing numbers or time strings.