#MoonMoney

$ moon run cmd/main -- tax 10000 USD 19%
  net:   $100.00
  rate:  19%
  tax:   $19.00
  gross: $119.00

$ moon run cmd/main -- split 10000 USD 3
  1: $33.34
  2: $33.33
  3: $33.33
  total: $100.00

$ moon run cmd/main -- parse "CA$12.34"
CAD 12.34
  minor units: 1234
  currency:    CAD (Canadian Dollar)

#Why

#Requirements

• The MoonBit toolchain, moonc 0.10.14 or newer — the floor the OSC acceptance rules set. This repository is developed, formatted and verified with moon 0.1.20261012 / moonc v0.10.15, which is the release continuous integration installs as well, so moon fmt and moon info reproduce the committed files byte for byte.
• Nothing outside moonbitlang/core is needed to build, test or run the library, on wasm, wasm-gc and js.
• A C toolchain for --target native: the toolchain's Windows native backend wants MSVC Build Tools (cl.exe or clang-cl.exe), so a Windows machine with only mingw cannot build that one target. CI covers all four targets on Linux.
• Node.js only if you want to regenerate the currency table.

#Quick start

# use it from another project
moon add haol-05/moonmoney

# work on this repository
moon check --deny-warn --target all
moon build --target all
moon test --deny-warn --target all
moon run examples/demo                  # a self-contained tour, no arguments
moon run cmd/main -- parse "USD 1,234.56"

#What it does

#Using it

// A net invoice line and its tax. Every call that can fail says so in its type.
fn invoice_line(net_minor : Int64, rate_text : String) -> String raise @moonmoney.MoneyError {
  let usd = @moonmoney.Currency::find("USD").unwrap()
  let net = @moonmoney.Money::of_minor(net_minor, usd)
  let rate = @moonmoney.Percent::parse(rate_text)
  let gross = net.with_tax(rate)
  "\{@format.format(net)} + \{rate.text()} = \{@format.format(gross)}"
}

// Splitting a bill without losing a cent.
let total = @moonmoney.Money::of_minor(10000L, usd)   // USD 100.00
let shares = total.allocate(3)                        // [33.34, 33.33, 33.33]
let weighted = total.allocate_ratios([3L, 2L, 1L])    // [50.00, 33.33, 16.67]

// Reading amounts that were written the way people write them.
let a = @parse.amount("USD 1,234.56")     // USD 1234.56
let b = @parse.amount("1.234,56 €")       // EUR 1234.56, the continental reading
let c = @parse.amount("CA$12.34")         // CAD 12.34
let d = @parse.amount_in("(5.00)", usd)   // -USD 5.00, accounting negative

#Reading an amount

• The currency has to be known. Either the text names it (USD 12.34, CA$12.34, €12.34) or the caller supplies it with amount_in. A symbol is only matched as a whole token and the symbols are the disambiguated CLDR ones, so A$ is the Australian dollar, CA$ the Canadian one and a bare $ is the US dollar — the only currency CLDR gives that symbol. Total: 12.34 is reported as unknown rather than parsed as if Total: were a currency.
• The decimal mark is found by rule. One to exponent digits after the last mark make it the decimal mark, so 1,234.56 and 1.234,56 both read as one thousand two hundred thirty four point five six. More than that is still a decimal mark unless exactly three digits follow, because three is a grouping group: 1,235 is 1235, while 1.2345 is a fraction of four places. Grouping that is not in threes is refused.
• Precision that does not fit is refused. amount_in("USD 1.2345") reports an error. amount_in_rounded rounds once under a mode you name instead.

#Writing an amount

@format.format(money)                                  // $1,234.56
@format.format(money, style=@format.MoneyStyle::code_first())   // USD 1,234.56
@format.format(money, style=@format.MoneyStyle::plain())        // 1234.56
@format.format(money, style=@format.MoneyStyle::accounting())   // ($1,234.56) when negative
@format.MoneyStyle::for_locale("de-DE")                // 1.234,56 $
@format.MoneyStyle::for_locale("en-IN")                // ₹1,23,456.78

#Honest limits

• No exchange rates are fetched. Conversion needs a rate you supply, which keeps the result deterministic and the library offline. There is no rate feed, no historical rate and no triangulation.
• No decimal arithmetic. The library is fixed point. Amounts are bounded by Int64 minor units; a result that does not fit is reported as an overflow rather than promoted to a bigger type or a float.
• No locale database. Twenty layouts ship in the source. An unknown tag returns None rather than a guess.
• Nothing is validated against a payment network. The ISO 4217 table is reference data, not a statement about what a bank will accept.
• One provenance point needs a reviewer's eye. The ISO 4217 compilation MoonMoney reads is under ODC-PDDL-1.0, but the SIX Group lists underneath it state no licence. SOURCES.md records this and the one-constant change that swaps in the official list instead.

#Reproducing the currency table

node tools/generate_currency_table.mjs

#Layout

moonmoney/            the core: Currency and its table, Money, rounding,
                      percentages, allocation, tax, exchange
parse/                text to Money
format/               Money to text, with the locale presets
cmd/main/             the command line
examples/demo/        a runnable tour
tools/                the table generator

#Licence