The simple-currency Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The simple-currency Reference Manual

This is the simple-currency Reference Manual, version 0.0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 04:34:41 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

This is a simple library for converting between currencies
using the foreign exchange information posted daily by the ECB. You
can find more information on the time of updates etc at:

http://www.ecb.int/stats/exchange/eurofxref/html/index.en.html

The library is so simple that it is easier for a user to just read the
documentation strings and the function definitions themselves, so
please look at simple-currency.lisp if you want more detailed
documentation.

Installation:

This package uses DEXADOR, PLUMP, SIMPLE-DATE, SPLIT-SEQUENCE, and
CL-STORE but if you use quicklisp (http://www.quicklisp.org/beta/),
they will be automatically installed for you.

(ql:quickload :simple-currency)
(CIES:UPDATE-CURRENCIES-HASH) ;;downloads currency info from ecb

If it does not return NIL, you are ready to go

Usage example:

(CIES:CONVERT 100 :USD :GBP)

==> 
861350/13373
#

If you want it to look like a money amount, you can do

(CIES:DISPLAY-CURRENCY (CIES:CONVERT 100 :USD :GBP) :GBP)

==>
"GBP 64.41"

Likewise with checking the interval for unacceptably old quotations -
see documentation for simple-date.

NB: Remember that floats "contaminate" so if you do (CIES:CONVERT
100.25 :eur :usd).  You will get a float back: display-currency calls
a function which expects a rational, so that will signal an error.

Convenience facilities:

There is a macro (CIES:WITH-CURRENCY :xyz ) which can
replace references to (convert  ) in
conversion-form with (DISPLAY-CURRENCY (CONVERT   )
).  I haven't thought very hard about this macro, so it might
hold unintended surprises.

There is a simple database of currency information which can be
accessed with CIES:LOOKUP-CURRENCY, so for example, if you are in the
SIMPLE-CURRENCY package or have USED it:

(ccy-ddigits (lookup-currency :jpy))
==>
"0"

Another example:

(map 'list (lambda (acode)
                   (let ((cd (lookup-currency acode)))
                     (list acode (ccy-country cd) (ccy-name cd))))
           (available-currencies))

==>
(("EUR"
  ("Vatican City State (HOLY SEE)" "SPAIN" "SLOVENIA" "SLOVAKIA" "SAN MARINO"
   "SAINT PIERRE AND MIQUELON" "SAINT MARTIN (FRENCH PART)" "SAINT BARTHELEMY"
   "REUNION" "PORTUGAL" "NETHERLANDS" "MONTENEGRO" "MONACO" "MAYOTTE"
   "MARTINIQUE" "MALTA" "LUXEMBOURG" "ITALY" "IRELAND"
   "HOLY SEE (VATICAN CITY STATE)" "GUADELOUPE" "GREECE" "GERMANY"
   "FRENCH SOUTHERN TERRITORIES" "FRENCH GUIANA" "FRANCE" "FINLAND"
   "EUROPEAN UNION" "ESTONIA" "CYPRUS" "BELGIUM" "AUSTRIA" "ANDORRA"
   "AALAND ISLANDS")
  "Euro")
 ("ZAR" ("SOUTH AFRICA" "NAMIBIA" "LESOTHO") "Rand")
 ("THB" ("THAILAND") "Baht") ("SGD" ("SINGAPORE") "Singapore Dollar")
 ("PHP" ("PHILIPPINES") "Philippine Peso")
 ("NZD" ("TOKELAU" "PITCAIRN" "NIUE" "NEW ZEALAND" "COOK ISLANDS")
  "New Zealand Dollar")
 ("MYR" ("MALAYSIA") "Malaysian Ringgit") ("MXN" ("MEXICO") "Mexican Peso")
 ("KRW" ("KOREA, REPUBLIC OF") "Won") ("INR" ("INDIA" "BHUTAN") "Indian Rupee")
 ("ILS" ("ISRAEL") "New Israeli Sheqel") ("IDR" ("INDONESIA") "Rupiah")
 ("HKD" ("HONG KONG") "Hong Kong Dollar") ("CNY" ("CHINA") "Yuan Renminbi")
 ("CAD" ("CANADA") "Canadian Dollar") ("BRL" ("BRAZIL") "Brazilian Real")
 ("AUD"
  ("TUVALU" "NORFOLK ISLAND" "NAURU" "KIRIBATI"
   "HEARD ISLAND AND McDONALD ISLANDS" "COCOS (KEELING) ISLANDS"
   "CHRISTMAS ISLAND" "AUSTRALIA")
  "Australian Dollar")
 ("TRY" ("TURKEY") "Turkish Lira")
 ("RUB" ("RUSSIAN FEDERATION") "Russian Ruble")
 ("HRK" ("CROATIA") "Croatian Kuna")
 ("NOK" ("SVALBARD AND JAN MAYEN" "NORWAY" "BOUVET ISLAND") "Norwegian Krone")
 ("CHF" ("SWITZERLAND" "LIECHTENSTEIN") "Swiss Franc")
 ("SEK" ("SWEDEN") "Swedish Krona") ("RON" ("ROMANIA") "New Romanian Leu")
 ("PLN" ("POLAND") "Zloty") ("LVL" ("LATVIA") "Latvian Lats")
 ("LTL" ("LITHUANIA") "Lithuanian Litas") ("HUF" ("HUNGARY") "Forint")
 ("GBP" ("UNITED KINGDOM" "JERSEY" "ISLE OF MAN" "GUERNSEY") "Pound Sterling")
 ("DKK" ("GREENLAND" "FAROE ISLANDS" "DENMARK") "Danish Krone")
 ("CZK" ("CZECH REPUBLIC") "Czech Koruna") ("BGN" ("BULGARIA") "Bulgarian Lev")
 ("JPY" ("JAPAN") "Yen")
 ("USD"
  ("VIRGIN ISLANDS (US)" "VIRGIN ISLANDS (BRITISH)"
   "UNITED STATES MINOR OUTLYING ISLANDS" "UNITED STATES"
   "TURKS AND CAICOS ISLANDS" "TIMOR-LESTE" "PUERTO RICO" "PANAMA" "PALAU"
   "NORTHERN MARIANA ISLANDS" "MICRONESIA, FEDERATED STATES OF"
   "MARSHALL ISLANDS" "HAITI" "GUAM" "EL SALVADOR" "ECUADOR"
   "BRITISH INDIAN OCEAN TERRITORY" "BONAIRE, SINT EUSTATIUS AND SABA"
   "AMERICAN SAMOA")
  "US Dollar"))


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 simple-currency

Author

Peter Wood, email: pete_wood at runbox.com

License

BSD, 2 clause.

Description

SIMPLE-CURRENCY provides conversions between
currencies using data published daily by the European Central Bank, no guarantees about the accuracy of the data are given or even implied. For details of the ECB FX rates see:

http://www.ecb.int/stats/exchange/eurofxref/html/index.en.html

Version

0.0.1

Dependencies
Source

simple-currency.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

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


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 simple-currency.asd

Location

simple-currency.asd

Systems

simple-currency (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 simple-currency/package.lisp

Parent

simple-currency (system)

Location

package.lisp

Packages

simple-currency


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 simple-currency/simple-currency.lisp

Dependency

package.lisp (file)

Parent

simple-currency (system)

Location

simple-currency.lisp

Exported Definitions
Internal Definitions

Previous: , Up: Lisp files   [Contents][Index]

3.1.4 simple-currency/currency-info.lisp

Dependency

simple-currency.lisp (file)

Parent

simple-currency (system)

Location

currency-info.lisp

Exported Definitions
Internal Definitions

*currency-data* (special variable)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 simple-currency

Source

package.lisp (file)

Nickname

cies

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Special variables

Special Variable: *stored-currency-hash*
Package

simple-currency

Source

simple-currency.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.2 Macros

Macro: with-currency CURRENCY CONVERSION-FORM
Package

simple-currency

Source

simple-currency.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.3 Functions

Function: 2dd-round RAT
Package

simple-currency

Source

simple-currency.lisp (file)

Function: available-currencies ()
Package

simple-currency

Source

simple-currency.lisp (file)

Function: ccydb-date ()
Package

simple-currency

Source

simple-currency.lisp (file)

Function: display-currency AMOUNT &optional CCODE
Package

simple-currency

Source

simple-currency.lisp (file)

Function: interval-since-update DATE
Package

simple-currency

Source

simple-currency.lisp (file)

Function: update-currency-hash ()

Returns the updated hash table stored in global variable *CURRENCIES* if the update is believed to be successful, or restores the old stored hash table if the call to ECB failed and returns the old table, or NIL if both options failed for any reason.

Package

simple-currency

Source

simple-currency.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

5.1.4 Generic functions

Generic Function: ccy-acode OBJECT
Package

simple-currency

Methods
Method: ccy-acode (CURRENCY-DATA currency-data)

automatically generated reader method

Source

currency-info.lisp (file)

Generic Function: ccy-country OBJECT
Package

simple-currency

Methods
Method: ccy-country (CURRENCY-DATA currency-data)

automatically generated reader method

Source

currency-info.lisp (file)

Generic Function: ccy-ddigits OBJECT
Package

simple-currency

Methods
Method: ccy-ddigits (CURRENCY-DATA currency-data)

automatically generated reader method

Source

currency-info.lisp (file)

Generic Function: ccy-name OBJECT
Package

simple-currency

Methods
Method: ccy-name (CURRENCY-DATA currency-data)

automatically generated reader method

Source

currency-info.lisp (file)

Generic Function: ccy-ncode OBJECT
Package

simple-currency

Methods
Method: ccy-ncode (CURRENCY-DATA currency-data)

automatically generated reader method

Source

currency-info.lisp (file)

Generic Function: convert AMOUNT FROM TO

Converts AMOUNT between currencies FROM and TO,
which should be keywords designating 3 letter currency codes. Returns 2 values: a rational number representing the converted amount in TO currency, and a SIMPLE-DATE:INTERVAL representing the interval since the currency hash was last updated. For a list of available currency codes call (AVAILABLE-CURRENCIES).

Package

simple-currency

Source

simple-currency.lisp (file)

Methods
Method: convert (AMOUNT number) FROM (TO (eql eur))
Method: convert (AMOUNT number) (FROM (eql eur)) TO
Method: convert (AMOUNT number) FROM TO
Generic Function: currency-data CCY QUERY
Package

simple-currency

Source

currency-info.lisp (file)

Methods
Method: currency-data CCY (QUERY (eql ncode))
Method: currency-data CCY (QUERY (eql name))
Method: currency-data CCY (QUERY (eql country))
Method: currency-data CCY (QUERY (eql ddigits))
Generic Function: get-quote AMOUNT FROM TO

Return 3 values: 1) The conversion as a rational,
2) the rate for converting from FROM to TO as a rational, and 3) a SIMPLE-DATE:INTERVAL representing the interval since the currency hash was last updated.

Package

simple-currency

Source

simple-currency.lisp (file)

Methods
Method: get-quote (AMOUNT number) FROM (TO (eql eur))
Method: get-quote (AMOUNT number) (FROM (eql eur)) TO
Method: get-quote (AMOUNT number) FROM TO
Generic Function: lookup-currency CCY
Package

simple-currency

Source

currency-info.lisp (file)

Methods
Method: lookup-currency (CCY symbol)
Method: lookup-currency (CCY string)

Previous: , Up: Exported definitions   [Contents][Index]

5.1.5 Classes

Class: currency-data ()
Package

simple-currency

Source

currency-info.lisp (file)

Direct superclasses

standard-object (class)

Direct methods
Direct slots
Slot: country
Initargs

:country

Readers

ccy-country (generic function)

Slot: name
Type

(quote string)

Initargs

:name

Readers

ccy-name (generic function)

Slot: acode
Type

(quote string)

Initargs

:acode

Readers

ccy-acode (generic function)

Slot: ncode
Type

(quote string)

Initargs

:ncode

Readers

ccy-ncode (generic function)

Slot: ddigits
Type

(quote string)

Initargs

:ddigits

Readers

ccy-ddigits (generic function)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *currencies*
Package

simple-currency

Source

simple-currency.lisp (file)

Special Variable: *currency-data*
Package

simple-currency

Source

currency-info.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: getbase CURR
Package

simple-currency

Source

simple-currency.lisp (file)

Function: make-date STRING
Package

simple-currency

Source

simple-currency.lisp (file)

Function: normalize-currency-designator KW
Package

simple-currency

Source

simple-currency.lisp (file)

Function: parse-rational STRING
Package

simple-currency

Source

simple-currency.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, simple-currency.asd: The simple-currency<dot>asd file
File, Lisp, simple-currency/currency-info.lisp: The simple-currency/currency-info<dot>lisp file
File, Lisp, simple-currency/package.lisp: The simple-currency/package<dot>lisp file
File, Lisp, simple-currency/simple-currency.lisp: The simple-currency/simple-currency<dot>lisp file

L
Lisp File, simple-currency.asd: The simple-currency<dot>asd file
Lisp File, simple-currency/currency-info.lisp: The simple-currency/currency-info<dot>lisp file
Lisp File, simple-currency/package.lisp: The simple-currency/package<dot>lisp file
Lisp File, simple-currency/simple-currency.lisp: The simple-currency/simple-currency<dot>lisp file

S
simple-currency.asd: The simple-currency<dot>asd file
simple-currency/currency-info.lisp: The simple-currency/currency-info<dot>lisp file
simple-currency/package.lisp: The simple-currency/package<dot>lisp file
simple-currency/simple-currency.lisp: The simple-currency/simple-currency<dot>lisp file

Jump to:   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   2  
A   C   D   F   G   I   L   M   N   P   U   W  
Index Entry  Section

2
2dd-round: Exported functions

A
available-currencies: Exported functions

C
ccy-acode: Exported generic functions
ccy-acode: Exported generic functions
ccy-country: Exported generic functions
ccy-country: Exported generic functions
ccy-ddigits: Exported generic functions
ccy-ddigits: Exported generic functions
ccy-name: Exported generic functions
ccy-name: Exported generic functions
ccy-ncode: Exported generic functions
ccy-ncode: Exported generic functions
ccydb-date: Exported functions
convert: Exported generic functions
convert: Exported generic functions
convert: Exported generic functions
convert: Exported generic functions
currency-data: Exported generic functions
currency-data: Exported generic functions
currency-data: Exported generic functions
currency-data: Exported generic functions
currency-data: Exported generic functions

D
display-currency: Exported functions

F
Function, 2dd-round: Exported functions
Function, available-currencies: Exported functions
Function, ccydb-date: Exported functions
Function, display-currency: Exported functions
Function, getbase: Internal functions
Function, interval-since-update: Exported functions
Function, make-date: Internal functions
Function, normalize-currency-designator: Internal functions
Function, parse-rational: Internal functions
Function, update-currency-hash: Exported functions

G
Generic Function, ccy-acode: Exported generic functions
Generic Function, ccy-country: Exported generic functions
Generic Function, ccy-ddigits: Exported generic functions
Generic Function, ccy-name: Exported generic functions
Generic Function, ccy-ncode: Exported generic functions
Generic Function, convert: Exported generic functions
Generic Function, currency-data: Exported generic functions
Generic Function, get-quote: Exported generic functions
Generic Function, lookup-currency: Exported generic functions
get-quote: Exported generic functions
get-quote: Exported generic functions
get-quote: Exported generic functions
get-quote: Exported generic functions
getbase: Internal functions

I
interval-since-update: Exported functions

L
lookup-currency: Exported generic functions
lookup-currency: Exported generic functions
lookup-currency: Exported generic functions

M
Macro, with-currency: Exported macros
make-date: Internal functions
Method, ccy-acode: Exported generic functions
Method, ccy-country: Exported generic functions
Method, ccy-ddigits: Exported generic functions
Method, ccy-name: Exported generic functions
Method, ccy-ncode: Exported generic functions
Method, convert: Exported generic functions
Method, convert: Exported generic functions
Method, convert: Exported generic functions
Method, currency-data: Exported generic functions
Method, currency-data: Exported generic functions
Method, currency-data: Exported generic functions
Method, currency-data: Exported generic functions
Method, get-quote: Exported generic functions
Method, get-quote: Exported generic functions
Method, get-quote: Exported generic functions
Method, lookup-currency: Exported generic functions
Method, lookup-currency: Exported generic functions

N
normalize-currency-designator: Internal functions

P
parse-rational: Internal functions

U
update-currency-hash: Exported functions

W
with-currency: Exported macros

Jump to:   2  
A   C   D   F   G   I   L   M   N   P   U   W  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
A   C   D   N   S  
Index Entry  Section

*
*currencies*: Internal special variables
*currency-data*: Internal special variables
*stored-currency-hash*: Exported special variables

A
acode: Exported classes

C
country: Exported classes

D
ddigits: Exported classes

N
name: Exported classes
ncode: Exported classes

S
Slot, acode: Exported classes
Slot, country: Exported classes
Slot, ddigits: Exported classes
Slot, name: Exported classes
Slot, ncode: Exported classes
Special Variable, *currencies*: Internal special variables
Special Variable, *currency-data*: Internal special variables
Special Variable, *stored-currency-hash*: Exported special variables

Jump to:   *  
A   C   D   N   S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
Class, currency-data: Exported classes
currency-data: Exported classes

P
Package, simple-currency: The simple-currency package

S
simple-currency: The simple-currency system
simple-currency: The simple-currency package
System, simple-currency: The simple-currency system

Jump to:   C   P   S