# nyandere
Finally figure out how much everyone owes each other.
## Installation
If [Rust] is already installed,
just write `cargo install nyandere`!
## Usage
Much like one would write an R, Julia or Python script
to describe the processing some data,
one can write a nyandere script
like a receipt!
A script usually consists of 3 phases:
**creation**,
**transfer** and
**analysis**.
See [`asset/examples/typical.nyan`](./asset/examples/typical.nyan)
for a small typical script.
The syntax is inspired by [SQL].
It is case-sensitive, though.
A rough overview, the exact description is in
[`doc/syntax.abnf`](./doc/syntax.abnf):
- A script consists of any number of statements
delimited by newlines or semicolons.
- Comments are initiated by hashtags (`#`) and last until the next newline.
- Each statement consists of a **command** and **arguments**.
- The **command** consists of one or more identifiers.
- It dictates the required arguments.
- There are *positional*, *named* and *named optional* arguments.
- Positional arguments have their value stated as-is and are "unnamed".
- If there are multiple of them, their order matters.
- Named arguments consist of
- an identifier specifying which argument is completed
- an equals sign (`=`) padded by any number of spaces around it
- a value, specification depends on type
Named optional arguments are shown in (parentheses).
The parameters in the commands below
have the types required by them
shown in PascalCase.
Types can be:
`Name` | `someone` | Arbitrary unicode identifier
`Money` | `3.14€` | Euros. The sign needs to be explicit, also possible are `ct`, `eur`, `EUR`, ...
`Gtin` | `12345678` | Global Trade Item Number. Found on barcodes. See the glossary.
Additionally, there are the types `Entity`, `Concept` and `Object`.
You need to explicitly create them before you can use them
(usually by name),
see the next section.
### Creation
`create entity` | `Name` |
`create concept` | `Name` | `price=Money` `gtin=Gtin`
`create object` | `Name` | `parent=Concept`
The `create` command family registers new **actors**.
An **actor**
is a stateful participant
in an interaction.
They need to be *created*
before they can be used,
this avoids errors due to typos or the works.
An actor is one of the following:
- Entity: Holds a balance to other entities and
can make deliveries.
- Concept: An off-the-shelf somewhat standardized product
with a name, optionally a default price and optionally a [GTIN].
- Object: One physical object, possibly an instance of a concept.
For example,
this would create 2 entities `A`, `B` and
a concept `Multikey`
with the price of 1.70€ and
the GTIN `10000000`,
as well as an object `thing` with `Multikey` as parent concept:
```nyan
create entity A
create entity B
create concept Multikey price=1.70€ gtin=10000000
create object thing parent=Multikey
```
A few more caveats:
- An object inherits its default price from its parent, if any.
- One can refer to a concept by its name or GTIN
iff it's been specified at creation.
- Names and GTINs can be *shadowed*.
- For example, one can create 2 concepts with the name `cotton`
after each other, but only the last created one
is accessible by that name.
- However, the shadowed actors still exist. They aren't replaced.
Existing transfers and parent relationships aren't changed
by shadowing.
- Specifying products by name looks up objects before concepts.
### Transfer
`pay` | `Money` | `from=Entity` `to=Entity`
Transfer value, with
`from` as creditor (who gives it) and
`to` as debitor (who receives it).
### Analysis
`balance` | | `from=Entity` `to=Entity`
How much does `from` owe towards `to`,
all transfers summed up accordingly?
## Glossary
Terms you may stumble across when using this.
These are to the best of my knowledge from what I know and
found on Wikipedia:
- https://en.wikipedia.org/wiki/Debits_and_credits
### Accounting terms
Credit and debit work in tandem:
A giving a credit to B
is equivalent to
B receiving a debit from A.
#### Account
Sequence of **transactions**
forming a **standing value**.
Accounts are called entities in nyandere.
The standing values are not directly implemented:
Instead *relational values* between each entity-pair are kept.
#### Transaction
Moving value from or to an account.
Always involves exactly one **credit** and one **debit**:
The value comes from somewhere and goes somewhere.
##### Credit
*Outgoing* transaction *away from* an account.
`A` having a credit with `B` means that
`A` *trusts* `B` with some value.
Compare with Latin *"credere"* = to trust.
##### Debit
*Incoming* transaction *into* an account.
`A` having a debit from `B` means that
`A` has been *given* some value from `B`.
Compare with Latin *"debere"* = to give.
### [GTIN]
A base10 number
with no leading zeroes
between 8 and 14 digits long,
both inclusive.
Standard-wise they are actually only available in even fewer versions.
Thought for use with a barcode scanner,
there's cheap used ones connectable via USB.
## License
Licensed under either of
- Apache License, Version 2.0
([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license
([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.
**Please do note that
while I do hope this is useful to some,
this is a project
created in my personal free time.
I am not a professional,
nor is this a product I am selling.**
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.
[Rust]: https://www.rust-lang.org/
[SQL]: https://en.wikipedia.org/wiki/SQL
[GTIN]: https://en.wikipedia.org/wiki/Global_Trade_Item_Number
[the latest release]: https://github.com/MultisampledNight/nyandere/releases/latest