* Instead of writing specific currency amounts, you write simple expressions to calculate amounts.

    Income:Patreon  -{amount}

    Accrued:Accounts Receivable:Patreon  {amount}

The next two lines split the money across accounts.  They follow almost the same format as they do in Ledger: there's an account named, followed by a tab or two or more spaces, and then an expression.  Each time import2ledger generates an entry, it will evaluate this expression using the data it imported to calculate the actual currency amount to write.  Your expression can use numbers, basic arithmetic operators (including parentheses for grouping), and imported data referred to as ``{variable_name}``.

import2ledger uses decimal math to calculate each amount, and rounds to the number of digits appropriate for that currency.  If the amount of currency being imported doesn't split evenly, spare change will be allocated to the last split to keep the entry balanced on both sides.

import2ledger templates have access to a few variables for each transaction that can be included anywhere in the entry, not just amount expressions.  In other parts of the entry, they're treated as strings, and you can control their formatting using `Python's format string syntax <https://docs.python.org/3/library/string.html#formatstrings>`_.  For example, this template sets different payees for each side of the transaction::

    Income:Patreon  -{amount}

    Accrued:Accounts Receivable:Patreon  {amount}

Every template can use the following variables:

Specific importers and hooks may provide additional variables.

Supported templates

~~~~~~~~~~~~~~~~~~~

You can define the following templates.

Patreon

^^^^^^^

``template patreon income``

  Imports one transaction per patron per month.  Generated from Patreon's monthly patron report CSVs.

``template patreon cardfees``

  Imports one expense transaction per month for that month's credit card fees.  Generated from Patreon's earnings report CSV.

``template patreon svcfees``

  Imports one expense transaction per month for that month's Patreon service fees.  Generated from Patreon's earnings report CSV.

``template patreon vat``

  Imports one transaction per country per month each time Patreon withheld VAT.  Generated from Patreon's VAT report CSV.

  This template can use these variables:

  ============== ============================================================

  Name           Contents

  ============== ============================================================

  country_name   The full name of the country VAT was withheld for

  -------------- ------------------------------------------------------------

  country_code   The two-letter ISO country code of the country VAT was

                 withheld for

  ============== ============================================================

(``%`` is a special character in the configuration file syntax.  ``%%`` represents a literal percent sign.)

            template_name=config_key,

import functools

import io

import operator

import re

import tokenize

from . import errors

class TokenTransformer:

    def __init__(self, source):

        try:

            source = source.readline

        except AttributeError:

            pass

        self.in_tokens = tokenize.tokenize(source)

    @classmethod

    def from_bytes(cls, b):

        return cls(io.BytesIO(b).readline)

    @classmethod

    def from_str(cls, s, encoding='utf-8'):

        return cls.from_bytes(s.encode(encoding))

    def __iter__(self):

        for ttype, tvalue, _, _, _ in self.in_tokens:

            try:

                transformer = getattr(self, 'transform_' + tokenize.tok_name[ttype])

            except AttributeError:

                raise ValueError("{} token {!r} not supported".format(ttype, tvalue))

            yield from transformer(ttype, tvalue)

    def _noop_transformer(self, ttype, tvalue):

        yield (ttype, tvalue)

    transform_ENDMARKER = _noop_transformer

    def transform_ENCODING(self, ttype, tvalue):

        self.in_encoding = tvalue

        return self._noop_transformer(ttype, tvalue)

    def transform(self):

        out_bytes = tokenize.untokenize(self)

        return out_bytes.decode(self.in_encoding)

class AmountTokenTransformer(TokenTransformer):

    SUPPORTED_OPS = frozenset('+-*/()')

    transform_NAME = TokenTransformer._noop_transformer

    def transform_NUMBER(self, ttype, tvalue):

        yield (tokenize.NAME, 'Decimal')

        yield (tokenize.OP, '(')

        yield (tokenize.STRING, repr(tvalue))

        yield (tokenize.OP, ')')

    def transform_OP(self, ttype, tvalue):

        if tvalue == '{':

            try:

                name_type, name_value, _, _, _ = next(self.in_tokens)

                close_type, close_value, _, _, _ = next(self.in_tokens)

                if (name_type != tokenize.NAME

                    or close_type != tokenize.OP

                    or close_value != '}'):

                    raise ValueError()

            except (StopIteration, ValueError):

                raise ValueError("opening { does not name variable")

            yield (tokenize.NAME, name_value)

        elif tvalue in self.SUPPORTED_OPS:

            yield from self._noop_transformer(ttype, tvalue)

        else:

            raise ValueError("unsupported operator {!r}".format(tvalue))

class AccountSplitter:

    def __init__(self, signed_currencies, signed_currency_fmt, unsigned_currency_fmt,

                 template_name):

        self.splits = collections.OrderedDict()

        self.template_name = template_name

        self._last_template_vars = object()

    def add(self, account, amount_expr):

            clean_expr = AmountTokenTransformer.from_str(amount_expr).transform()

        except ValueError as error:

            raise errors.UserInputConfigurationError(error.args[0], amount_expr)

        self.splits[account] = compile(clean_expr, self.template_name, 'eval')

    def _currency_decimal(self, amount, currency):

        return decimal.Decimal(babel.numbers.format_currency(amount, currency, '###0.###'))

    def _balance_amounts(self, amounts, to_amount):

        cmp_func = operator.lt if to_amount > 0 else operator.gt

        should_balance = functools.partial(cmp_func, 0)

        remainder = to_amount

        to_account = None

        for account, amount in amounts.items():

            if should_balance(amount):

                remainder -= amount

                to_account = account

        if to_account is None:

            pass

        elif (abs(remainder) / abs(to_amount)) >= decimal.Decimal('.1'):

            raise errors.UserInputConfigurationError(

                "template can't balance amounts to {}".format(to_amount),

                self.template_name,

            )

            amounts[to_account] += remainder

    def _build_amounts(self, template_vars):

        amount_vars = {k: v for k, v in template_vars.items() if isinstance(v, decimal.Decimal)}

        amount_vars['Decimal'] = decimal.Decimal

        amounts = collections.OrderedDict(

            (account, self._currency_decimal(eval(amount_expr, amount_vars),

                                             template_vars['currency']))

            for account, amount_expr in self.splits.items()

        )

        self._balance_amounts(amounts, template_vars['amount'])

        self._balance_amounts(amounts, -template_vars['amount'])

        return amounts

    def _iter_splits(self, template_vars):

        amounts = self._build_amounts(template_vars)

        if template_vars['currency'] in self.signed_currencies:

            amt_fmt = self.signed_currency_fmt

        else:

            amt_fmt = self.unsigned_currency_fmt

        for account, amount in amounts.items():

            amt_s = babel.numbers.format_currency(amount, template_vars['currency'], amt_fmt)

            yield '    {:45}  {:>19}\n'.format(account, amt_s)

    def render_next(self, template_vars):

        if template_vars is not self._last_template_vars:

            self._split_iter = self._iter_splits(template_vars)

            self._last_template_vars = template_vars

        return next(self._split_iter)

    ACCOUNT_SPLIT_RE = re.compile(r'(?:\t|  )\s*')

                 unsigned_currency_fmt=UNSIGNED_CURRENCY_FMT,

                 template_name='<template>'):

        self.splitter = AccountSplitter(

            signed_currencies, signed_currency_fmt, unsigned_currency_fmt, template_name)

                line = line.strip()

                match = self.ACCOUNT_SPLIT_RE.search(line)

                if match is None:

                    raise errors.UserInputError("no amount expression found", line)

                account = line[:match.start()]

                amount_expr = line[match.end():]

                self.splitter.add(account, amount_expr)

                self.format_funcs.append(self.splitter.render_next)

 Accrued:Accounts Receivable  {amount}

 Income:Donations  -{amount}

 Accrued:Accounts Receivable  {amount}

 Income:Donations  -.5 * {amount}

 Income:Sales  -.5*{amount}

 Accrued:Accounts Receivable  {amount}

 Income:Donations:Specific    -.955*  {amount}

 Income:Donations:General     -.045  * {amount}

[Multivalue]

template =

 Expenses:Taxes  {tax}

 Accrued:Accounts Receivable  {amount} - {tax}

 Income:RBI         -.1*{amount}

 Income:Donations   -.9*{amount}

 Accrued:Accounts Receivable  {amount}

 Income:Donations  -{amount}

 Income:Donations  -{amount}

 Expenses:Fundraising  .05 * {amount}

 Accrued:Accounts Receivable  .95 * {amount}

 Accrued:Accounts Receivable  -{amount}

 Expenses:Fees:Credit Card  {amount}

 Accrued:Accounts Receivable  -{amount}

 Expenses:Fundraising  {amount}

    assert "\nIncome:Donations  -{amount}\n" in tmpl_s

def test_multivalue():

    tmpl = template_from('Multivalue')

    rendered = tmpl.render('DD', decimal.Decimal('150.00'), 'USD', DATE,

                           tax=decimal.Decimal('12.50'))

    lines = [normalize_whitespace(s) for s in rendered.splitlines()]

    assert lines == [

        "",

        "2015/03/14 DD",

        "  Expenses:Taxes  12.50 USD",

        "  Accrued:Accounts Receivable  137.50 USD",

        "  Income:RBI  -15.00 USD",

        "  Income:Donations  -135.00 USD",

    ]