RevBank::Cart::Entry

One line of the current transaction

Synopsis

my $entry = $cart->add(-1.50, "Beer", { plugin => $self->id });
$entry->add_contra("+sales/beer", +1.50, "\$you bought beer", "Beer");

$entry->quantity(3);

for my $contra ($entry->contras) {
    say "$contra->{account}: $contra->{amount}";
}

Description

An entry is created with $cart->add (see RevBank::Cart). Its amount is from the perspective of the account that will check out: negative to pay, positive to receive.

For double-entry bookkeeping, an entry has contras: the other side of the booking, on other accounts. The entry's amount and its contras' amounts must add up to zero, or checkout dies.

Amounts are per unit. The quantity applies to the entry and all of its contras.

From hook_checkout on, entries are sealed: reading works, but anything that would change an entry dies.

Methods

add_contra($account, $amount, $description, $display = undef)

Adds a contra and returns the entry, so calls can be chained.

A hidden account is created if it doesn't exist yet, but a user account must exist. The amount may be a RevBank::Amount or a string that parse_string accepts, and usually has the opposite sign of the entry's.

$description is from the perspective of the contra account, and goes to the log. $you in it is replaced by the name of the account that checks out.

The interactive user sees $display for this contra. Without it, a contra on a hidden account is not shown, and one on a user account is shown as just an arrow and the account name. Give it for either all or none of an entry's contras, except for contras of 0.00.

contras

Returns the contras as a list of hashes with the keys account, amount, description and display. These are copies: changing them does not change the entry.

delete_contras

Removes all contras, e.g. to add different ones.

amount, amount($new)

The amount per unit. Setting it marks the entry as changed, so the cart is redisplayed.

quantity, quantity($new)

The number of units, 1 by default. It can't be negative. Setting it marks the entry as changed.

multiplied

Returns whether the quantity is not 1.

description, description($new, $for_the_record = 0)

The description of the entry, as shown to the user and written to the log. $you in it is replaced like in contra descriptions. Setting it marks the entry as changed, so the cart is redisplayed, unless $for_the_record is true.

attribute($key), attribute($key => $value)

Per-entry storage, like $cart->attribute. The two argument form sets the attribute and returns the new value. Initial attributes can be given to $cart->add.

Some attributes mean something to RevBank or its plugins:

  • refuse_checkout

    The cart can't be checked out while this entry is in it. Used for an entry that is a placeholder for input that is still expected.

  • deduplicate

    Entries with the same value are merged into one, with the quantities added up, by the deduplicate plugin. Use join("/", $self->id, $unique_id), and only for entries that are otherwise identical.

  • no_repeat

    The repeat plugin won't change the quantity of this entry.

has_attribute($key)

Returns whether the attribute exists and is defined.

account

The account that checks out, or undef before checkout. It is set by $cart->checkout before hook_checkout_prepare, or right after it for entries that were added there.

caller

The name of the subroutine that created the entry, for debugging.

as_printable

Returns the lines that $cart->display prints for this entry.

as_loggable

Returns the lines that the log plugin writes for this entry. Only valid once the account is set.

Author

Juerd Waalboer #####@juerd.nl