bitlair/revbank
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

v6.0.0: big revbank.products syntax change

Browse source 
Rationale in UPGRADING.md

It's a big change technically, but converting the format won't be hard
for admins.

There's a compatibility mode with loud warnings in case the file isn't
converted.
This commit is contained in:
Juerd Waalboer 2024-01-18 18:15:35 +01:00
parent 6aa33beedb
commit 55a83d9ceb
7 changed files with 249 additions and 117 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

94
UPGRADING.md
View file

@ -1,3 +1,79 @@
# When upgrading, always:
1. Make sure nobody is using RevBank.
2. Make a backup of your RevBank data and code repo(s).
3. Read this file :)
# (2024-01-20) RevBank 6.0.0
Note that the changes to `revbank.products` do NOT apply to `revbank.market`
and other files.
## Update your `revbank.products` file
TL;DR: Product descriptions now need `"quotes"` around them.
This version comes with breaking changes to the `revbank.products` syntax, to
expand the capabilities of the file in a more future-proof way. Bitlair
(Hackerspace Amersfoort) has requested a way to add metadata to products for
automation, which together with recent other additions to the format, made
clear a more structured approach was needed.
The line format for the products file is now like the input format of the
command line interface. This means that if product descriptions contain spaces,
as they typically do, quotes are needed around them. You can pick between
`"double"` and `'single'` quotes. Any backslashes and quotes within the same
kind of quotes need escaping by adding a `\` in front, e.g. `\"` and `\\`.
```
# Old format:
product_id 0.42 Can't think of a good description +addon1 +addon2
# New format, recommended style:
product_id 0.42 "Can't think of a good description" +addon1 +addon2
# Automatically generated? You may wish to quote all fields:
"product_id" "0.42" "Can't think of a good description" "+addon1" "+addon2"
# Escaping also works:
product_id 0.42 Can\'t\ think\ of\ a\ good\ description +addon1 +addon2
```
To convert your `revbank.products` file to the recommended style automatically,
you could use:
```sh
# The following is one command. It was obviously not optimized for readability :)
perl -i.backupv6 -ple'unless (/^\s*#/ or /^\s*$/) {
my ($pre, $desc) = /(^\s*\S+\s+\S+\s*)(.*)/; $pre .= " " if $pre !~ /\s$/;
my @a; unshift @a, $1 while $desc =~ s/\s\+(\S+)$//;
$desc =~ s/([\"\\])/\\$1/g; $_ = "$pre\"$desc\"";
for my $a (@a) { $_ .= " +$a" }
}' revbank.products
```
Note that this will leave commented lines unchanged! If those contain disabled
products, you'll have to add the quotes yourself.
## New feature: hashtags in `revbank.products`
After the description field, you can add hashtag fields. These begin with `#`
and may take the form of a lone `#hashtag`, or they may be used as a
`#key=value` pair. The hashtags can be read by plugins. Out of the box, they
currently do nothing.
```
8711327538481 0.80 "Ola Liuk" #ah=wi162664 #q=8
8712100340666 0.45 "Ola Raket" #ah=wi209562 #q=12
5000112659184,5000112658873 0.95 "Coca-Cola Cola Zero Sugar (33 cl)" #sligro +sb
# equivalent:
"8711327538481" "0.80" "Ola Liuk" "#ah=wi162664" "#q=8"
```
See https://github.com/bitlair/revbank-inflatinator/ for a possible use of adding metadata.
# (2023-12-26) RevBank 5.0.0 # (2023-12-26) RevBank 5.0.0
This version comes with breaking changes to the command line syntax, to shield This version comes with breaking changes to the command line syntax, to shield
@ -231,19 +307,25 @@ list from within RevBank, add `edit` to `revbank.plugins`.
## Check your `revbank.products` ## Check your `revbank.products`
There's new syntax for `revbank.products`: addons. Check that your lines don't > Added 2024-01-20 v6.0.0: if you're upgrading to v6.0.0 from a version before
have `+foo` at the end, where `foo` can be anything. > v3.6, instead of following these instructions, you can just add quotes to the
> descriptions (when using the perl oneliner from the v6.0.0 upgrade
> instructions, check if any `+something` that got placed outside of the quotes
> should have been within the quotes.)
Also check that you don't have any product ids that start with `+`; those can ~~There's new syntax for `revbank.products`: addons. Check that your lines don't
no longer be entered as this syntax now has special semantics. have `+foo` at the end, where `foo` can be anything.~~
So these don't work as before: ~~Also check that you don't have any product ids that start with `+`; those can
no longer be entered as this syntax now has special semantics.~~
~~So these don't work as before:~~
example_id 1.00 Example product +something example_id 1.00 Example product +something
+something 1.00 Product id that starts with plus +something 1.00 Product id that starts with plus
example,+alias 1.00 Alias that starts with plus example,+alias 1.00 Alias that starts with plus
These will keep working as they were: ~~These will keep working as they were:~~
example_id1 1.00 Example product+something example_id1 1.00 Example product+something
example_id2 1.00 Example product + something example_id2 1.00 Example product + something

70
plugins/products
View file

@ -13,16 +13,61 @@ sub read_products() {
%products = (); %products = ();
$mtime = -M $filename; $mtime = -M $filename;
my $line = 0; my $linenr = 0;
my $warnings = 0;
for (slurp $filename) { for my $line (slurp $filename) {
$line++; $linenr++;
s/^\s+|\s+$//g; # trim next if $line =~ m[
next if /^#/; ^\s*\# # comment line
next if not length; |
^\s*$ # empty line, or only whitespace
]x;
my @split = RevBank::Prompt::split_input($line);
if (grep /\0SEPARATOR/, @split) {
warn "Invalid character in $filename line $linenr.\n";
next;
}
if (grep /\0/, @split) {
warn "Invalid value in $filename line $linenr.\n";
next;
}
my ($ids, $p, $desc, @extra) = @split;
my @addon_ids;
my %tags;
my $compat = 0;
if (@split == 1 and ref $split[0]) {
$compat = 1;
} else {
for (@extra) {
if (/^\+(.*)/) {
push @addon_ids, $1;
} elsif (/^\#(\w+)(=(.*))/) {
$tags{$1} = $2 ? $3 : 1;
} else {
$compat = 1;
last;
}
}
}
if ($compat) {
$warnings++;
warn "$filename line $linenr: can't parse as new format; assuming old format.\n" if $warnings < 4;
warn "Too many warnings; suppressing the rest. See UPGRADING.md for instructions.\n" if $warnings == 4;
($ids, $p, $desc) = split " ", $line, 3;
@addon_ids = ();
unshift @addon_ids, $1 while $desc =~ s/\s+ \+ (\S+)$//x;
}
my ($ids, $p, $desc) = split " ", $_, 3;
my @ids = split /,/, $ids; my @ids = split /,/, $ids;
$p ||= "invalid"; $p ||= "invalid";
@ -35,21 +80,17 @@ sub read_products() {
if ($percent) { if ($percent) {
if (grep !/^\+/, @ids) { if (grep !/^\+/, @ids) {
warn "Percentage invalid for non-addon at $filename line $line.\n"; warn "Percentage invalid for non-addon at $filename line $linenr.\n";
next; next;
} }
$price = 0 + $price; $price = 0 + $price;
} else { } else {
$price = eval { parse_amount($price) }; $price = eval { parse_amount($price) };
if (not defined $price) { if (not defined $price) {
warn "Invalid price for '$ids[0]' at $filename line $line.\n"; warn "Invalid price for '$ids[0]' at $filename line $linenr.\n";
next; next;
} }
} }
my @addon_ids;
unshift @addon_ids, $1 while $desc =~ s/\s+ \+ (\S+)$//x;
$products{$_} = { $products{$_} = {
id => $ids[0], id => $ids[0],
price => $sign * $price, price => $sign * $price,
@ -57,7 +98,8 @@ sub read_products() {
description => $desc, description => $desc,
contra => $contra || $default_contra, contra => $contra || $default_contra,
_addon_ids => \@addon_ids, _addon_ids => \@addon_ids,
line => $line, line => $linenr,
tags => \%tags,
} for @ids; } for @ids;
} }

65
plugins/products.pod
View file

@ -4,10 +4,14 @@ products - RevBank plugin for selling products
=head1 SYNOPISIS =head1 SYNOPISIS
8710447032756 0.80 Festini Peer # Comments are lines that begin with a # character.
4029764001807,clubmate 1.40 Club-Mate +half +pf # Empty lines are ignored.
pf 0.15@+pfand Pfand NRW-Flasche
+half -50% 50% discount \o/ 8710447032756 0.80 "Festini Peer"
4029764001807,clubmate 1.40 "Club-Mate" +half +pf
pf 0.15@+pfand "Pfand NRW-Flasche"
+half -50% "50% discount \\o/"
123 0.42 "Hashtag example" #tag #tag2=42
=head1 DESCRIPTION =head1 DESCRIPTION
@ -63,9 +67,15 @@ C<revbank.products>. User accounts are liability accounts.)
=head2 Description =head2 Description
The description may contain whitespace. The description, like other columns, may contain whitespace, but to use
whitespace, either the entire field "needs quotes" around it, or the whitespace
can be escaped with backslashes.
=head2 Addons It is suggested to always use quotes around the description.
=head2 Additional fields
=head3 Addons
Addons are products that are added as part of the main product. They are Addons are products that are added as part of the main product. They are
specified after the description, with a C<+> sign that has whitespace before specified after the description, with a C<+> sign that has whitespace before
@ -76,9 +86,9 @@ the product id C<foo> is used instead. The difference is that a product id
C<+foo> can only be used as an addon for another product, while C<foo> can be C<+foo> can only be used as an addon for another product, while C<foo> can be
used either as an addon or a manually entered as a standalone product. used either as an addon or a manually entered as a standalone product.
example_id 2.20 Example product +first +second example_id 2.20 "Example product" +first +second
+first 1.20 First thing +first 1.20 "First thing"
second 0.80 Second thing second 0.80 "Second thing"
In this example, the final price of the example product will be 4.20. It is not In this example, the final price of the example product will be 4.20. It is not
possible to buy the first thing separate, but it is possible to buy the second possible to buy the first thing separate, but it is possible to buy the second
@ -97,7 +107,7 @@ listed as a component named "Product".
A product can have multiple addons. Addon products themselves can also have A product can have multiple addons. Addon products themselves can also have
further addons, but circular recursion is not supported. further addons, but circular recursion is not supported.
=head3 Percentage addons =head4 Percentage addons
As a special case, an addon's price can be a percentage. In this case, the As a special case, an addon's price can be a percentage. In this case, the
price is calculated from the sum of the the product components I<up to that price is calculated from the sum of the the product components I<up to that
@ -105,12 +115,41 @@ point> that have I<the same contra account> as the percentage addon.
So, given the following example, So, given the following example,
example_id 0.90 Example product +some_fee +discount example_id 0.90 "Example product" +some_fee +discount
+some_fee 0.15@+fees Some fee; might be a bottle deposit +some_fee 0.15@+fees "Some fee; might be a bottle deposit"
+discount -50% Special offer discount! +discount -50% "Special offer discount!"
only 0.45 is discounted, because the 0.15 has a different contra account. While only 0.45 is discounted, because the 0.15 has a different contra account. While
complicated, this is probably what you want in most cases. There is currently complicated, this is probably what you want in most cases. There is currently
no way to apply a discount to the product with all of its addons. no way to apply a discount to the product with all of its addons.
A percentage addon must have a product_id that begins with C<+>. A percentage addon must have a product_id that begins with C<+>.
=head3 Tags
Additional metadata can be given in additional fields that begin with C<#> and
the name of the tag, optionally followed by C<=> and a value to turn it into a
key/value pair. If no value is specified, a value of C<1> is used.
The name of a hashtag must contain only C<A-Z a-z 0-9 _> characters. There must
not be whitespace after the C<#> or around the C<=>.
Like all the fields, the field can be quoted to contain whitespace. Note,
however, that the quotes must be placed around the entire field, not just the
value part.
ht1 0.42 "Just one hashtag" #tag
ht2 0.42 "Two hashtags!" #tag #key=value
ht3 0.42 "Surprising syntax" "#x=spaces in value"
Tags can be accessed by custom plugins, but are currently ignored by upstream
RevBank and its plugins.
=head3 Other additional fields
When any field is added after the description, that does not begin with C<+> or
C<#>, RevBank currently assumes it's the old syntax (which is not described in
the current version of this document!), and parses it using the old semantics
while showing a warning.
This compatibility feature will be removed from a future version of RevBank.

10
plugins/statiegeld.pod
View file

@ -6,11 +6,11 @@ statiegeld - RevBank plugin for return deposits
revbank.products: revbank.products:
clubmate 1.40 Club-Mate bottle +sb clubmate 1.40 "Club-Mate bottle" +sb
cola 0.90 Cola can +sc cola 0.90 "Cola can" +sc
+sb 0.15@+statiegeld Bottle deposit +sb 0.15@+statiegeld "Bottle deposit"
+sc 0.25@+statiegeld Can deposit +sc 0.25@+statiegeld "Can deposit"
matecrate 1.50@+statiegeld Mate crate (empty) matecrate 1.50@+statiegeld "Mate crate (empty)"
=head1 DESCRIPTION =head1 DESCRIPTION

4
plugins/vat.pod
View file

@ -13,8 +13,8 @@ C<revbank.vat>
C<revbank.products> C<revbank.products>
123123123 1.00 Example product that gets the default contra 123123123 1.00 "Example product that gets the default contra"
42424242 1.00@+sales/products/hoogbtw Example with high VAT rate 42424242 1.00@+sales/products/hoogbtw "Example with high VAT rate"
=head1 DESCRIPTION =head1 DESCRIPTION

2
revbank
View file

@ -18,7 +18,7 @@ use RevBank::Messages;
use RevBank::Cart; use RevBank::Cart;
use RevBank::Prompt; use RevBank::Prompt;
our $VERSION = "5.1.3"; our $VERSION = "6.0.0";
our %HELP1 = ( our %HELP1 = (
"abort" => "Abort the current transaction", "abort" => "Abort the current transaction",
); );

121
revbank.products
View file

@ -1,83 +1,52 @@
### THIS IS THE EXAMPLE FILE; DON'T ADD PRODUCTS, BUT MAKE A NEW FILE ### ### THIS IS THE EXAMPLE FILE; DON'T ADD PRODUCTS, BUT MAKE A NEW FILE ###
# Deze in principe niet veranderen want dat heeft invloed op producten # Documentation: perldoc plugins/products.pod
# die al eerder verkocht zijn. Omschrijving aanpassen kan geen kwaad. # or https://github.com/revspace/revbank/blob/master/plugins/products.pod
+sb 0.15@+statiegeld Statiegeld blikje
+sf 0.15@+statiegeld Statiegeld plastic flesje
+sm 0.15@+statiegeld Statiegeld Mehrwegflasche
matekrat 1.50@+statiegeld Statiegeld matekrat excl. inhoud
# Let op: als een product een statiegeld addon (bijv. +sb) heeft, dat niet # Not using statiegeld? Just leave off the +sb etc!
# meer veranderen, want dan kan het product niet meer worden ingeleverd.
5000112658873 0.90 "Coca Cola Zero, can 33 cl" +sb
8712800196440 1.10 "Chocomel, can 25 cl" +sb
4337182201458 0.75 "Spuitwater, bottle 50 cl" +sf
4337182093381 0.75 "Plat water, bottle 50 cl" +sf
5000112646719 3.00 "Coca-Cola Zero, bottle 150 cl" +sF
4029764001883 1.15 "Club-Mate Cola, bottle 33 cl" +sm
4029764001401 1.40 "Club-Mate Granat, bottle 50 cl" +sm
4029764001869 1.40 "Club-Mate Winter-Edition, bottle 50cl" +sm
4029764001906 1.40 "Club-Mate Zero, bottle 50cl" +sm
4029764001807 1.40 "Club-Mate, bottle 50 cl" +sm
5000112545326 0.90 "Coca-Cola, can 33 cl (no deposit)"
5740700988349 0.90 "Coca-Cola, can 33 cl (no deposit)"
8710615077206 0.50 "Daelmans Stroopwafel" +THT
8716100202337 0.70 "Katja Apekoppen"
40084077 0.40 "Kinder Maxi"
4001724046196 5.50 "Oetker Ristorante Pizza Wuerstel & Patatine"
4009233016846 5.00 "Wagner Sensazione Pizza Mozzarella"
8710401024605 0.75 "Titan (Raket)"
8718964162758 1.50 "Crappy fietslampje is beter dan niks"
mdf3mm-wit 3.00 "MDF 600x400x3 wit gelakt "
mdf4mm 1.50 "MDF 600x400x4"
populier5mm 3.15 "Populier-timmerplaat 600x400x5"
hardboard3mm 0.65 "Hardboard 600x400x3"
# Aliases:
8710447032756,Perenijsje 0.80 "Ola Perenijsje"
8712100340666,Raket 0.55 "Raket"
8722700627821,Splitijsje 0.80 "Split"
# Empty lines and lines beginning with # are ignored. # Special "products"
BOUNTY1 -10.00@-expenses/bounties "Thanks for vacuuming!"
# All other lines should have three fields, whitespace separated. The first two BOUNTY3 -25.00@-expenses/bounties "Thanks for mopping!"
# fields are barcode/productID and price, the third field is the description. +THT -50.00% "Discount (best-before date expired)"
# Only the last field may have whitespace. ibutton 15.00@+ibuttonborg "Deposit for new iButton"
ibutton-terug -15.00@+ibuttonborg "Deposit returned for iButton"
# Free stuff contributie 30.00@+sales/contributie "Membership 1 month"
649241869825 0.00 Free disgusting stuff (LS)
57063003 0.00 Free Stimorol
# Water
5400151013112 0.50 Carbonated mineral water
5400155056542 0.50 Mineral water
# Soda
5449000014535 0.70 Sprite
5449000000996 0.70 Coca-Cola
# Chips
05414359710322 0.50 Chips
05414359710315 0.50 Chips
zakjechips 0.50 Chips
clubmate,4029764001807 1.40 Club-Mate +sm
87124385 1.10 Chocomel
8710447032756 0.80 Festini peer
tostikaas 1.15 Tosti kaas
4001724035848 5.10 Pizza Veggie Mix
cola,5000112638745 0.90 Coca-Cola Zero, blik 33 cl +korting +sb
pizza 4.50 Pizza +sgo
+korting -50% Yay korting
dinges 0.00 Dingeskitje +aa +pcb +koppla +j +korting
aa 0.20@+sales/batt Batterij
pcb 0.80 pcb
koppla 5.00 Koppla
j 0.10@juerd Gratis geld voor juerd
#moo 2,151 bla
#meh 1.00 blaaat +mekker
bla -5
#aap 1.00 ding +noot
#noot 9.99 dinges deze niet
#+noot 2.00 dinges +mies
#mies 3.00 donges +aap
sgo 0.80@+stroomgebruik Stroomgebruik oven
nietsb -0.15@+statiegeld WHoaaa
korting -0.10@-korting Korting \o/
BOUNTY1 -10.00@-expenses/bounties Bedankt voor dingen!! +j
BOUNTY2 -5.00@-expenses/bounties Bedankt en zo
example_id 1.00 Example product +something
+something 1.00 Product that has an id that starts with plus
example,+alias 1.00 Product that has an alias that starts with plus
example_id1 1.00 Example product+something
example_id2 1.00 Example product + something
more_stuff 1.00 Example product with +something but not at the end
bbq 1.00 3+ pieces of meat
# For use with the statiegeld plugin:
# (Nothing but descriptions should be changed after using these addons.)
+sb 0.15@+statiegeld "Deposit can"
+sf 0.15@+statiegeld "Deposit bottle"
+sF 0.25@+statiegeld "Deposit large bottle"
+sm 0.15@+statiegeld "Deposit Mehrwegpfand"
#+se 0.25@+statiegeld "Statiegeld Einwegpfand"
+smk,matekrat 1.50@+statiegeld "Deposit crate w/o bottles"