README.adoc 8.41 KB
Newer Older
1 2
image:https://gitlab.com/e257/accounting/tackler/badges/master/build.svg["Build status", link="https://gitlab.com/e257/accounting/tackler/-/jobs/"]
image:https://gitlab.com/e257/accounting/tackler/badges/master/coverage.svg["Coverage", link="https://gitlab.com/e257/accounting/tackler/-/jobs/"]
35V LG84's avatar
35V LG84 committed
3
image:https://maven-badges.herokuapp.com/maven-central/fi.e257/tackler-core_2.12/badge.svg["Maven Central", link="https://maven-badges.herokuapp.com/maven-central/fi.e257/tackler-core_2.12"]
35V LG84's avatar
35V LG84 committed
4
image:https://javadoc.io/badge/fi.e257/tackler-core_2.12.svg?color=blue["javadoc", link="https://javadoc.io/page/fi.e257/tackler-core_2.12/latest/fi/e257/tackler/index.html"]
35V LG84's avatar
35V LG84 committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157
image:https://www.scala-js.org/assets/badges/scalajs-0.6.17.svg["Scala.js",link="https://www.scala-js.org"]

= Tackler

Tackler Ain't Calculator and Kernel for link:http://ledger-cli.org/[Ledger] Equivalent Records.
Why not?  - Because it uses simplified Ledger syntax.

So in other words, Tackler is accounting engine and reporting tool for link:http://plaintextaccounting.org/[text
based double-entry accounting].


== Features
* Tackler is link:docs/performance.adoc[fast]
* Support for link:docs/commodities.adoc[Commodities] and link:docs/currencies.adoc[Currencies]
* Text and link:docs/json.adoc[JSON] output formats for reports
** link:docs/server-api.adoc[Server API] for embedding Tackler core
** link:docs/client-api.adoc[Client API] for JVM and JS environments
* Integrated support with GIT version control system
** Can use plain filesystem or link:docs/git-storage.adoc[GIT repository] as data storage
** Natively supports splitting journal data to multiple files (shards)
* Clean and simple link:docs/journal.adoc[journal format]
* Strict account name validation with link:./docs/accounts.conf[Chart of Accounts]
* Multiple report and export types:
** link:docs/report-balance.adoc[Balance], link:docs/report-balance-group.adoc[Balance Groups] and link:docs/report-register.adoc[Register] Reports
** link:docs/export-equity.adoc[Equity] and link:docs/export-identity.adoc[Identity] Exports
* Support for link:./docs/txn-filters.adoc[Transaction Filters]
* Supports UTF-8 characters in transaction data (link:tests/parser/ok/par-02.ref.identity.txn[descriptions], link:tests/parser/ok/par-02.ref.reg.txt[comments], link:tests/parser/ok/id-chars-01.ref.identity.txn[account names])
* Supports ISO 8601 timestamps with link:tests/core/ok/time-dst-01.ref.identity.txn[timezones]
  and link:tests/core/ok/time-nano-01.ref.identity.txn[nanosecond] resolution
* Has good performance with link:docs/performance.adoc[large transaction set]
** Tackler is link:perf/results/perf-hw00.adoc[tested up to one million (1E6)] transactions
** Tackler can parse and process link:perf/results/readme.adoc[56000 txn/s] on Quad Core system
* Near 100% test coverage, link:tests/tests.adoc[all features are extensively tested]
* Extensive documentation: link:docs/readme.adoc[Index of Docs]


== Why Tackler?

Tackler's idea is provide *concise*, *minimal* and *reliable*
engine to process text-based human readable accounting records.

_Concise_ means that Tackler's journal format is semantically concise
and easy for humans to *reason about*.

_Minimal_ means that Tackler provides *minimum* set of features which are
needed for its operation.

_Reliable_ means that Tackler's behaviour is well known, tested
and it is *documented*.

All that said, Tackler can be used easily from command line
with normal personal accounting data sets.


=== Tackler Goals

* Minimal feature set, very simple and well defined input format
** *Tackler input journal is supposed to be produced by software and to be audited by human.*
    However, it must be possible to edit the journal by hand.

* Well known and defined behaviour

* Extensive user and developer documentation

* Error free, reliable and resilient
** Near perfect code and permutation test coverage

* Good performance
** Must be able to process hundreds of thousands of records with reasonable processing time and memory footprint
** Must have linear processing time characteristics
** Assumption: All transactions can be held in memory

* Provides backend and core components for text based accounting processing

* JVM and Multi platform support: Linux and Arm-Linux, it should be possible to run it on Windows

* GIT is used for data distribution and storage

Implementation language of Tackler is link:http://scala-lang.org/[Scala] 
and journal parsing is done with link:http://www.antlr.org/[ANTLR4].


== Documentation

User documentation is located under docs:

* link:./docs/readme.adoc[Index of Documentation]
* link:./docs/installation.adoc[Installation Manual]
* link:./docs/journal.adoc[Tackler journal format]
* link:./docs/usage.adoc[Usage Guide]
* link:./docs/configuration.adoc[Configuration Manual]
* link:./docs/tackler.conf[Example of Tackler Conf. (tackler.conf)]
* link:./docs/accounts.conf[Example of Tackler Chart of Accounts (accounts.conf)]
* link:./docs/trimix-filling-station.adoc[Example of Trimix Filling Station Accounting system (for scuba diving)]
* link:./docs/server-api.adoc[Server API documentation]
* link:./docs/client-api.adoc[Client API documentation]
* link:./docs/devel/readme.adoc[Developer's documentation]


== Todo, TEPs and Roadmap

At the moment, current set of active todo items is kept link:./todo[todo files].

There are Tackler Enhancement Proposals for planning and tracking implementation
of major new features. These are listed on link:docs/tep/readme.adoc[TEP index].

=== Roadmap

Extremely loosely defined roadmap is following:

* Reporting Server as separate project 
* Extending support for Units
* Profit and Loss (PnL) tracking
** Automatic conversions between different base units
** Support for unit handling with commodities  
* Extending support for Currencies and Commodities
** Price database

== Releases

For release information and version history details,
see link:./CHANGELOG.adoc[CHANGELOG].

Tackler-core is supposed to be usable as separate component.
Tackler-api is released for JVM and JS environments, and it is intended
to be used on the client side. See link:./docs/server-api.adoc[Server API]
and link:./docs/client-api.adoc[Client API] for additional information.

Dependency settings for SBT are:

    libraryDependencies += "fi.e257" %%  "tackler-core" % "version-number"
    libraryDependencies += "fi.e257" %%% "tackler-api"  % "version-number"

These are released on Maven Central Repository.

Tackler is under development, so if you enjoy calm seas
then it might be better to look
link:http://plaintextaccounting.org/[something else].

However, complex backward non-compatible changes to 
link:./docs/journal.adoc[Journal file format]
should be rare. At the moment Tackler is used in production for
operational data set.

Configuration files, command line interface and Client API (data models)
are more likely to subject of change.


== Contributing to Tackler

Contributions to the project are most welcome. See
link:./CONTRIBUTING.adoc[CONTRIBUTING] how you could help.

35V LG84's avatar
35V LG84 committed
158
Your pull requests and patches can be merged only if you can certify
35V LG84's avatar
35V LG84 committed
159
the link:./DCO[Developer Certificate of Origin (DCO), Version 1.1].
35V LG84's avatar
35V LG84 committed
160 161 162 163 164 165 166

By signing-off your commit you certify DCO and acknowlegde that you have
the rights to submit your pull requsted or patch as an open-source patch,
as stated in link:./DCO[Developer Certificate of Origin].

Certifying DCO is done by adding a `Signed-off-by` line
to **every** git commit message:
35V LG84's avatar
35V LG84 committed
167 168 169

    Signed-off-by: gitlab-account <your.real@email.address>

35V LG84's avatar
35V LG84 committed
170 171 172 173 174
If you set your `user.name` and `user.email` correctly in git config,
then git will automatically include that line for you with `git commit -s`.
You can also create a git `commit.template` with appropriate content. These
settings can be done per repository basis,  so they don't have to be globally
set in your system.
35V LG84's avatar
35V LG84 committed
175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201
 
Please make sure that you sign-off all your PR's commits.


== Credits

See link:./THANKS.adoc[THANKS] for full list of credits.


== License

....
Copyright 2016-2018 E257.FI Contributors

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
....