Konfigurácia možností

Správanie Beancountu sa prispôsobuje pomocou direktív option umiestnených na začiatku vášho hlavného účtovného súboru. Tieto páry kľúč–hodnota riadia názvy vašich koreňových účtov, akú veľkú nevyváženosť môže transakcia niesť a ktoré rozšírenia sa spúšťajú. ⚙️

Každá možnosť na tejto stránke bola načítaná proti Beancount 3.2.3 a každá citovaná chybová správa je tá, ktorú táto verzia vypíše. Beancount odmietne možnosť, ktorú nepozná — option "default_tolerance" "USD:0.01" zlyhá s chybou Invalid option: 'default_tolerance' — takže možnosť skopírovaná zo staršej príručky nezlyhá ticho. Po zmene čohokoľvek tu spustite na svojom súbore bea check.

Základné konfiguračné možnosti​

Tieto možnosti riadia základné nastavenie vašej účtovnej knihy.

Základné nastavenia​

Toto sú niektoré z najčastejších možností, ktoré nastavíte.

option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
option "plugin_processing_mode" "default"

• title: Nastavuje názov pre reporty a webové rozhrania. Predvolená hodnota je Beancount.
• render_commas: Ak je true, čísla v reportoch sú formátované s oddeľovačmi tisícov (napr. 1,000,000.00). Predvolená hodnota je false. Ktorákoľvek z hodnôt 1, TRUE, true alebo yes sa číta ako true; každý iný reťazec sa číta ako false.
• plugin_processing_mode: Buď default (predvolená hodnota) alebo raw. Akákoľvek iná hodnota zlyhá s chybou Error for option 'plugin_processing_mode'.

raw nie je miernejšia verzia default — je to prepínač, ktorý vypína Beancountove vlastné spracovateľské fázy. Pri default Beancount spúšťa beancount.ops.documents pred vašimi pluginmi a beancount.ops.pad a beancount.ops.balance po nich. Pri raw spúšťa iba pluginy, ktoré sami vypíšete, takže direktívy pad sa nikdy neuplatnia a kontroly balance sa nikdy nevykonajú:

; Under "raw" the balance stage never runs, so this obviously
; false assertion is accepted in silence.
option "plugin_processing_mode" "raw"
 
1970-01-01 open Assets:Cash
1970-01-01 open Equity:Opening-Balances
 
1970-01-02 * "Opening balance"
  Assets:Cash                100.00 USD
  Equity:Opening-Balances   -100.00 USD
 
1970-01-03 balance Assets:Cash   999.00 USD

Zmeňte tento riadok na default a rovnaký súbor ohlási Balance failed for 'Assets:Cash': expected 999.00 USD != accumulated 100.00 USD (899.00 too little). Použite raw iba vtedy, keď zámerne reimplementujete tieto fázy sami.

Prispôsobenie názvov účtov​

Môžete premenovať Beancountove päť základných typov účtov. Toto nie je kozmetická zmena. Táto možnosť predefinuje, ktoré koreňové názvy parser akceptuje, takže každý účet vo vašom súbore musí používať nový názov a starý sa stane neplatným.

option "name_assets" "Actifs"
option "name_expenses" "Depenses"
 
2024-01-01 open Actifs:Banque:Courant
2024-01-01 open Depenses:Alimentation
 
2024-01-02 * "Boulangerie" "Pain"
  Depenses:Alimentation      4.20 EUR
  Actifs:Banque:Courant     -4.20 EUR

Nechajte jediný zápis na starom koreni a súbor prestane načítavať s chybou Invalid account name: Assets:Banque:Courant. Päť možností je name_assets, name_liabilities, name_equity, name_income a name_expenses; každá hodnota musí byť jedno veľké slovo bez dvojbodky, inak dostanete Error for option 'name_assets': Invalid root account name. Premenujte korene, keď začínate účtovnú knihu, nie v jej polovici.

Konfigurácia účtov vlastného imania​

Beancount syntetizuje niekoľko účtov vlastného imania, keď sumarizuje obdobie — počiatočné stavy, nerozdelený zisk a konverzie mien. Tieto možnosti ich pomenúvajú.

Každá hodnota je názov listu a Beancount ho pripojí pod name_equity za vás. Napísanie vlastného imania sami vyprodukuje Equity:Equity:Opening-Balances, čo je iný účet, než ste zamýšľali.

option "account_previous_balances" "Opening-Balances"
option "account_previous_earnings" "Earnings:Previous"
option "account_current_earnings" "Earnings:Current"
option "account_previous_conversions" "Conversions:Previous"
option "account_current_conversions" "Conversions:Current"
option "account_rounding" "Equity:Rounding"

account_rounding je výnimkou v tejto skupine: akceptuje úplný názov účtu a ukladá sa presne tak, ako je napísaný, preto Equity:Rounding vyššie je správne a nie je zdvojenou predponou. Taktiež nie je predvolene nastavená a na Beancounte 3.2.3 jej nastavenie nemá žiadny vplyv na načítavanie — pozri Presnosť a tolerancie pre to, čo sa v skutočnosti stane so zostatkom.

Nastavenia presnosti a tolerancie​

Tieto možnosti riadia, akú veľkú nevyváženosť Beancount akceptuje v transakcii.

Konfigurácia predvolenej tolerancie​

Beancount odvodzuje toleranciu pre každú transakciu z počtu desatinných miest v jej zápisoch. Tieto tri možnosti upravujú toto odvodzovanie.

option "inferred_tolerance_default" "USD:0.01"
option "tolerance_multiplier" "1.2"
option "infer_tolerance_from_cost" "TRUE"

• inferred_tolerance_default: Minimálna hodnota na menu, použitá, keď transakcia nemá desatinné miesta, z ktorých by sa odvodzovala. Syntax je <currency>:<number> a * nastaví všetky meny naraz. Opakujte možnosť pre nastavenie viacerých.
• tolerance_multiplier: Zlomok najmenšej číslice, ktorý sa považuje za tolerovateľný, predvolená hodnota 0.5. Nie je to percentuálne zvýšenie: 1.2 robí každú odvodenú toleranciu 2,4-krát väčšou ako predvolenú.
• infer_tolerance_from_cost: Ak je true, zápisy držané v nákladoch rozširujú toleranciu aj v mene nákladov. Predvolene vypnuté.

Starý názov inferred_tolerance_multiplier stále nastavuje rovnakú hodnotu, ale hlási Renamed to 'tolerance_multiplier'. ako chybu načítania, takže bea check zlyhá na súbore, ktorý ho používa. Premenujte ho.

Metóda účtovania​

Táto možnosť nastavuje predvolené pravidlo pre výber šarže, z ktorej sa odpočítava zníženie. Dajte jednému účtu iné pravidlo na jeho direktíve open.

; The file-wide default. An open directive overrides it per account.
option "booking_method" "STRICT"

Beancount 3.2.3 akceptuje presne sedem názvov: STRICT (predvolená hodnota), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO a AVERAGE. Čokoľvek iné je odmietnuté pri načítaní s chybou Error for option 'booking_method' — vrátane SIMPLE a FULL, ktoré nie sú metódami účtovania a nikdy neboli. AVERAGE je tu akceptovaná, ale nemá žiadnu implementáciu; zníženie pod ňou vyvolá AVERAGE method is not supported. Správa zásob funguje cez všetkých sedem v tej istej účtovnej knihe.

Správa mien​

Správna konfigurácia mien je nevyhnutná pre presné reportovanie.

Prevádzková mena​

Prevádzková mena je mena, v ktorej chcete, aby sa reporty sumarizovali. Opakujte možnosť pre deklarovanie viac ako jednej; hodnoty sa kumulujú, nie nahrádzajú.

option "operating_currency" "USD"
option "operating_currency" "EUR"
option "conversion_currency" "NOTHING"

Deklarovanie prevádzkových mien hovorí reportovacím nástrojom, aby dali každej z nich vlastný stĺpec. conversion_currency pomenúva imaginárnu menu, do ktorej Beancount účtuje konverzie pri nulovom kurze; už predvolene je NOTHING a jediný dôvod na jej nastavenie je vybrať iný zástupný symbol, ktorý vaša účtovná kniha určite nikdy nepoužije ako skutočnú komoditu.

Správa dokumentov​

Beancount môže spájať transakcie s externými súbormi, ako sú účtenky alebo faktúry. Možnosť documents mu dáva priečinok na skenovanie.

option "documents" "/home/user/Documents/beancount"

Cesta v tomto bloku je ilustrácia — pred spustením ju nahraďte vlastnou. Iba prvé pravidlo nižšie je hlásené ako chyba; porušte ktorékoľvek z ostatných a súbor sa jednoducho nikdy nenájde:

• Priečinok musí existovať. Chýbajúci zlyhá pri načítaní s chybou Document root '/no/such/place' does not exist.
• Podpriečinky sú názvy účtov. Doklad pre Assets:US:BofA:Checking patrí do <root>/Assets/US/BofA/Checking/. Súbor voľne ležiaci v koreni sa ignoruje.
• Účet musí byť otvorený. Dokumenty nájdené pod účtom, ktorý vaša účtovná kniha nikdy neotvorí, sú preskočené bez varovania.
• Názvy súborov začínajú dátumom v tvare YYYY-MM-DD.description.ext (napr. 2025-07-28.amazon-order.pdf). Čokoľvek iné v priečinku sa ignoruje.
• Cesty môžu byť absolútne alebo relatívne k hlavnému účtovnému súboru a možnosť môže byť opakovaná pre viacero priečinkov.

Systém pluginov​

Funkcionalita Beancountu sa dá rozšíriť pomocou pluginov.

Konfigurácia pluginov​

Plugin sa načítava samostatnou direktívou plugin, nie pomocou option. option "plugin" "..." zlyhá s chybou Option 'plugin' may not be set.

plugin "beancount.plugins.auto_accounts"
 
2024-03-01 * "Coffee Shop" "Flat white"
  Expenses:Food:Coffee        4.50 USD
  Assets:US:BofA:Checking    -4.50 USD

Tento súbor sa načíta, pretože auto_accounts otvorí oba účty za vás; odstráňte riadok plugin a ohlási Invalid reference to unknown account 'Expenses:Food:Coffee'. Plugin, ktorý prijíma konfiguráciu, ju dostáva ako druhý reťazec, plugin "module" "config". Pluginy sa spúšťajú v poradí, v akom ich napíšete, po Beancountovej vlastnej fáze documents a pred jeho fázami pad a balance — pokiaľ nenastavíte plugin_processing_mode na raw, čo tieto fázy úplne vypustí.

Technické limity a obmedzenia​

Tieto možnosti riadia technické aspekty Beancountovho parsera.

Spracovanie reťazcov​

Môžete nastaviť limit na počet riadkov povolených vo viacriadkovom reťazci, aby sa neukončený úvodzovkový znak nahlásil blízko miesta, kde ste ho napísali, a nie na konci súboru.

option "long_string_maxlines" "64"

Interpolačná presnosť​

Beancount predvolene používa jednu toleranciu na dve rôzne úlohy: doplnenie chýbajúcej sumy a rozhodnutie, či transakcia sedí. Zapnutím tohto sa pre prvú použije najjemnejšia odvodená tolerancia a pre druhú najvoľnejšia, čo zastaví odchyľovanie interpolovaných súm.

option "use_precise_interpolation" "TRUE"

Neexistuje žiadna možnosť pre explicitné tolerancie na zápise. Jediná explicitná tolerančná syntax, ktorú Beancount 3.2.3 má, je vlnovka na direktíve balance — 4.271 ~ 0.01 RGAGX — a nepotrebuje žiadnu možnosť. Vlnovka v rámci zápisu transakcie je syntaktická chyba.

Zastarané a odstránené možnosti​

Tri možnosti, ktoré staršie príručky stále odporúčajú, v Beancounte 3.2.3 neexistujú. Každý riadok v tomto bloku zlyhá pri načítaní:

option "experiment_explicit_tolerances" "True"
option "use_legacy_fixed_tolerances" "True"
option "default_tolerance" "USD:0.001"

• experiment_explicit_tolerances — syntax ~ na úrovni zápisu, ktorú povoľovala, je preč; použite vlnovku direktívy balance.
• use_legacy_fixed_tolerances — pevné tolerancie 0.005/0.015 sú preč; tolerancia sa odvodzuje na transakciu, ladená pomocou tolerance_multiplier a inferred_tolerance_default.
• default_tolerance — nahradená možnosťou inferred_tolerance_default pre vyrovnávanie a display_precision pre zobrazovanie.

Ďalšie tri stále fungujú, ale hlásia chybu zastarania, čo stačí na zlyhanie bea check:

• inferred_tolerance_multiplier — premenovaná na tolerance_multiplier.
• allow_pipe_separator — akceptuje starý | medzi platcom a popisom.
• allow_deprecated_none_for_tags_and_links — akceptuje doslovné None tam, kde patria štítky a odkazy.

Možnosti Fava sú samostatné​

Všetko na tejto stránke číta samotný Beancount. Vlastné nastavenia Fava nie sú vôbec direktívy option — sú to direktívy custom "fava-option" s dátumom a Beancount ich ignoruje. Napísanie nastavenia Fava ako option zlyhá s chybou Invalid option. Pozri Možnosti Fava pre tento zoznam.

Odporúčaná konfigurácia ✅​

Pre väčšinu používateľov poskytuje nasledujúca konfigurácia robustný a rozumný východiskový bod. Je to jeden súbor a načíta sa.

; Reporting
option "title" "Personal Ledger"
option "operating_currency" "USD"
option "render_commas" "TRUE"
 
; Precision: a floor for currencies with no decimals to infer from,
; and the default 0.5 multiplier left alone.
option "inferred_tolerance_default" "USD:0.005"
 
; Booking: identify the lot you are selling, explicitly.
option "booking_method" "STRICT"
 
; Equity account names are leaves under Equity:.
option "account_previous_balances" "Opening-Balances"
option "account_current_earnings" "Earnings:Current"

Komentáre začínajú znakom ;. Komentár // je v Beancounte syntaktická chyba a stiahne so sebou zvyšok súboru.

Toto nastavenie poskytuje pevný základ pre novú Beancount účtovnú knihu, zaisťuje jasné reportovanie, rozumnú kontrolu presnosti a logickú štruktúru účtov vlastného imania.