• Stars
    star
    151
  • Rank 246,057 (Top 5 %)
  • Language
    Clojure
  • Created over 12 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A Clojure library that deals with monetary values and currencies. Built on top of Joda Money.

ClojureWerkz Money, a Clojure Library to Work With Money

ClojureWerkz Money is a Clojure library that deals with monetary amounts. It is built on top of Joda Money.

Project Goals

  • Expose most or all Joda Money features in an easy to use way
  • Be well documented and well tested
  • Integrate with popular libraries such as Cheshire and Monger
  • Don't introduce any significant amount of performance overhead

Project Maturity

Money is past 1.0 and is considered to be a complete, stable library.

Maven Artifacts

Money artifacts are released to Clojars. If you are using Maven, add the following repository definition to your pom.xml:

<repository>
  <id>clojars.org</id>
  <url>http://clojars.org/repo</url>
</repository>

Most Recent Release

With Leiningen:

[clojurewerkz/money "1.10.0"]

With Maven:

<dependency>
  <groupId>clojurewerkz</groupId>
  <artifactId>money</artifactId>
  <version>1.10.0</version>
</dependency>

Documentation

Monetary Amounts

Monetary amounts are instantiated using clojurewerkz.money.amounts functions. They operate on floating point amounts (doubles) or long values in major units (e.g. dollars) or minor units (e.g. cents).

Note that some currencies do not have minor units (most notably JPY). For those, use clojurewerkz.money.amounts/of-major.

(require '[clojurewerkz.money.amounts :as ma])
(require '[clojurewerkz.money.currencies :as mc])

;; USD 10.50
(ma/amount-of mc/USD 10.5)
;; USD 10
(ma/of-major mc/USD 10)
;; USD 10.50
(ma/of-minor mc/USD 1050)

;; JPY 1000
(ma/of-major mc/JPY 1000)

Note that not all currencies have minor units (most notably JPY does not).

It is possible to parse a string in the standard format [currency unit] [amount], e.g. JPY 1000:

(require '[clojurewerkz.money.amounts :as ma])

(ma/parse "JPY 1000")
;= org.joda.money.Money instance for JPY 1000

Monetary amounts can be added, substracted and so on using clojurewerkz.money.amounts/plus, clojurewerkz.money.amounts/minus, clojurewerkz.money.amounts/multiply, and clojurewerkz.money.amounts/divide functions:

(require '[clojurewerkz.money.amounts    :as ma])
(require '[clojurewerkz.money.currencies :as mc])

(ma/plus (ma/amount-of mc/USD 10) (ma/amount-of mc/USD 100))
;= USD 110

(ma/minus (ma/amount-of mc/USD 100) (ma/amount-of mc/USD 10))
;= USD 90

(ma/multiply (ma/amount-of mc/USD 100) 10)
;= USD 1000

;; :floor for flooring round mode
(ma/divide (ma/amount-of mc/USD 100.1) 10 :floor)
;= USD 10

It is possible to add up all monies in a collection or sequence using clojurewerkz.money.amounts/total:

(require '[clojurewerkz.money.amounts    :as ma])
(require '[clojurewerkz.money.currencies :as mc])

(ma/total [(ma/amount-of mc/USD 10) (ma/amount-of mc/USD 100)])
;= USD 110

It is possible to compare monetary amounts using >, >=, < and <=.

(require '[clojurewerkz.money.amounts    :as ma])
(require '[clojurewerkz.money.currencies :as mc])

(ma/< (ma/amount-of mc/USD 100) (ma/amount-of mc/USD 100))
;= false

(ma/<= (ma/amount-of mc/USD 100) (ma/amount-of mc/USD 100) (ma/amount-of mc/USD 120))
;= true

(ma/>= (ma/amount-of mc/USD 100) (ma/amount-of mc/USD 100) (ma/amount-of mc/USD 120))
;= false

(ma/> (ma/amount-of mc/USD 200) (ma/amount-of mc/USD 100))
;= true

Rounding

clojurewerkz.money.amounts/round is a function that performs rounding of monetary values using one of the rounding modes:

(require '[clojurewerkz.money.amounts :as ams])

(ams/round (ams/amount-of cu/USD 40.01) -1 :floor)
;= USD 40

(ams/round (ams/amount-of cu/USD 40.01) -1 :up)
;= USD 50

(ams/round (ams/amount-of cu/USD 45.24) 0 :floor)
;= USD 45

(ams/round (ams/amount-of cu/USD 45.24) 0 :up)
;= USD 46

(ams/round (ams/amount-of cu/USD 45.24) 1 :floor)
;= USD 45.20

(ams/round (ams/amount-of cu/USD 45.24) 1 :up)
;= USD 45.30

Currencies

Currency units use their ISO-4217 codes and represented by org.joda.money.CurrencyUnit instances. Usually the easiest way to use currency units is via clojurewerkz.money.currencies aliases:

(require '[clojurewerkz.money.currencies :as mc])

mc/USD ;= USD currency unit
mc/CAD ;= CAD currency unit
mc/GBP ;= GBP currency unit
mc/RUB ;= RUB currency unit

clojurewerkz.money.currencies/for-code and clojurewerkz.money.currencies/of-country can be used to get currency units by their ISO-4217 code strings and country abbreviations:

(require '[clojurewerkz.money.currencies :as mc])

(mc/for-code "CHF")   ;= CHF currency unit
(mc/for-country "CH") ;= CHF currency unit

clojurewerkz.money.currencies/pseudo-currency? is a predicate function that takes a currency unit and returns true if it is a pseudo-currency (e.g. Bitcoin or IMF Special Drawing Rights).

Currency Conversion

clojurewerkz.money.amounts/convert-to converts a monetary value in one currency to another using provided exchange rate and rounding mode:

(require '[clojurewerkz.money.amounts :as ams])

(ams/convert-to (ams/amount-of cu/GBP 65.65) cu/USD 1.523 :down)
;= USD 99.98

Formatting

Money supports formatting of monetary amounts with the clojurewerkz.money.format/format function which takes an amount and (optionally) a locale and a formatter:

(require '[clojurewerkz.money.currencies :as cu])
(require '[clojurewerkz.money.amounts :refer [amount-of]])
(require '[clojurewerkz.money.format :refer :all])

(import java.util.Locale)

;; format using default system locale
(format (amount-of cu/GBP 20.0)) ;= GBP20,00
;; format using UK locale
(format (amount-of cu/GBP 20.0) Locale/UK) ;= £20.00

;; format using Brazilian locale
(format (amount-of cu/BRL 20.0) (Locale. "pt" "BR")) ;= R$20,00

Default formatter uses localized currency symbol and amount and default locale which JVM infers from environment settings.

Cheshire Integration

clojurewerkz.money.json, when loaded, registers serializers for org.joda.money.Money and org.joda.money.CurrencyUnit with Cheshire. Serialization conventions used are straightforward and produce human readable values:

  • (clojurewerkz.money.currencies/USD) => "USD"
  • (clojurewerkz.money.amounts/amount-of (clojurewerkz.money.currencies/USD) 20.5) => "USD20.50" (will use system locale by default)

To use it, simply require the namespace and then use Cheshire generation functions as usual.

This extension requires Cheshire 5.0.x or later. clojure.data.json is not supported.

Monger Integration

clojurewerkz.money.monger, when loaded, registers BSON serializers for org.joda.money.Money and org.joda.money.CurrencyUnit. Serialization conventions used are straightforward and produce human readable values:

  • (clojurewerkz.money.currencies/USD) => "USD"
  • (clojurewerkz.money.amounts/amount-of (clojurewerkz.money.currencies/USD) 20.5) => {"currency-unit" "USD" "amount-in-minor-units" 2050}

Note that serialization is one-way: loaded documents are returned as maps because there is no way to tell them from regular BSON documents. clojurewerkz.money.monger/from-stored-map can be used to produce Money instances from maps following the serialization convention described above.

Hiccup Integration

clojurewerkz.money.hiccup, when loaded, extends Hiccup HTML rendering protocol to render monetary amounts and currency units. Rendering conventions used are straightforward and produce human readable values:

  • (clojurewerkz.money.currencies/USD) => "USD"
  • (clojurewerkz.money.amounts/amount-of (clojurewerkz.money.currencies/USD) 20.5) => "USD20.50" (will use system locale by default)

To use it, simply require the namespace and then use Hiccup as usual.

Community

ClojureWerkz Money has a mailing list. Feel free to join it and ask any questions you may have.

To subscribe for announcements of releases, important changes and so on, please follow @ClojureWerkz on Twitter.

Supported Clojure Versions

ClojureWerkz Money is built from the ground up for Clojure 1.4 and up. The most recent release is always recommended.

Continuous Integration

Continuous Integration status

CI is hosted by travis-ci.org

Development

Money uses Leiningen 2. Make sure you have it installed and then run tests against all supported Clojure versions using

lein all test

Then create a branch and make your changes on it. Once you are done with your changes and all tests pass, submit a pull request on GitHub.

License

Copyright © 2012-2022 Michael S. Klishin, Alex Petrov, and the ClojureWerkz team.

Double licensed under the Eclipse Public License (the same as Clojure) or the Apache Public License 2.0.

More Repositories

1

elastisch

A minimalistic Clojure client for ElasticSearch, supports both HTTP and native transports
Clojure
386
star
2

meltdown

Clojure interface to Reactor, an event-driven programming and stream processing toolkit for the JVM
Clojure
208
star
3

buffy

Buffy The ByteBuffer Slayer, Clojure library for working with binary data.
Clojure
194
star
4

eep

Embedded Event Processing in Clojure
Clojure
140
star
5

ogre

Clojure library for querying Apache TinkerPop graphs
Clojure
126
star
6

cassaforte

Modern, high-level Clojure driver (client) for Cassandra build around CQL 3
Clojure
123
star
7

balagan

Clojure data structure manipulation and querying library
Clojure
119
star
8

titanium

Clojure graph library built on top of Titan
Clojure
106
star
9

mailer

An ActionMailer-inspired mailer library. Combines Postal, Clostache, some conventions and support for multiple delivery modes
Clojure
105
star
10

route-one

Tiny Clojure library that generates HTTP resource routes (as in Ruby on Rails, Jersey, Django, Sinatra, Flask and similar)
Clojure
94
star
11

scrypt

A Clojure library for the scrypt key derivation function. Use it to encrypt passwords and other sensitive data.
Clojure
85
star
12

envision

Clojure Data Visualisation library, based on Statistiker and D3
Clojure
78
star
13

machine_head

Clojure MQTT client
Clojure
71
star
14

spyglass

A Clojure Memcached client (also: Couchbase, Kestrel). Built on top of SpyMemcached, supports ASCII and binary protocols, strives to be 100% feature complete.
Clojure
67
star
15

statistiker

Minimalistic statistics library for Clojure
Clojure
63
star
16

gizmo

Gizmo is an effortless way to create web applications in Clojure
Clojure
41
star
17

elephant

Modern Clojure client for the Stripe API
Clojure
38
star
18

archimedes

Clojure library for Blueprints (part of the Tinkerpop graph stack).
Clojure
38
star
19

docslate

Base repository for the ClojureWerkz project documentation guides
CSS
35
star
20

serialism

A tiny Clojure library that serializes and deserializes values into popular formats based on provided content type
Clojure
31
star
21

persephone

Clojure DSL that generates [Neo4J] Cypher queries
Clojure
15
star
22

monger.docs

Documentation site for Monger
JavaScript
14
star
23

romulan

LMAX Disruptor in Clojure embrace
Clojure
14
star
24

support

A support library ClojureWerkz projects (Langohr, Monger, Neocons, Elastisch, Quartzite, Welle, and others) can rely on
Clojure
14
star
25

streampunk

Clojure library for stream summarization, cardinality estimation, all that jazz
Clojure
11
star
26

ssese

Clojure Server-Sent Events (SSE) client built with Netty 5.
Clojure
9
star
27

elastisch.docs

Documentation site for Elastisch
HTML
8
star
28

triennium

Small efficient MQTT topic routing library
Clojure
6
star
29

lein-template

A Leiningen 2.0 project template for all new ClojureWerkz libraries
Clojure
6
star
30

legacy-blog

blog.clojurewerkz.org
JavaScript
5
star
31

vat

Minimalistic client for vatapi.com
Clojure
5
star
32

quartzite.docs

Documentation site for Quartzite, a powerful Clojure scheduling library built on top of Quartz
CSS
5
star
33

neocons.docs

Documentation guides for Neocons
HTML
4
star
34

langohr.examples

Code examples used in Langohr documentation guides
Clojure
4
star
35

titanium.docs

Documentation site for Titanium, see http://titanium.clojurewerkz.org
CSS
4
star
36

machine_head.examples

Code examples for Machine Head, a Clojure MQTT client
Clojure
3
star
37

validateur.docs

Documentation site for Validateur
Sass
2
star
38

welle.docs

Documentation site for Welle, an expressive Clojure client for Riak
CSS
2
star
39

clojurewerkz.org

clojurewerkz.org website
HTML
2
star
40

gizmo.docs

Docs for Gizmo, Clojurewerkz web library
Ruby
1
star
41

spyglass.docs

Spyglass documentation site
Sass
1
star
42

ogre.docs

Documentation site for Ogre, see http://ogre.clojurewerkz.org
CSS
1
star
43

archimedes.docs

Documentation site for Archimedes
CSS
1
star
44

mold

Clojure client for CloudFoundry (primarily UAA and Cloud Controller)
Clojure
1
star
45

elastisch.shield

Elastic Shield support for Elastisch
Clojure
1
star
46

machine_head.docs

Machine Head documentation site
HTML
1
star