hledger підручник (1.51) - hledger

НАЗВА

hledger - надійна, дружня до користувача програма для обліку грошей у форматі простого тексту (інтерфейс командного рядка).

СИНТАКСИС

hledger
або
hledger КОМАНДА [ОПЦІЇ] [АРГУМЕНТИ]

ОПИС

hledger - це надійна, зручна для користувача, багатоплатформова сукупність програм для відстеження грошей, часу або будь-якого іншого товару, за допомогою подвійного бухгалтерського обліку та простого, редагованого файлового формату. hledger навіяний та переважно сумісний з ledger(1), і переважно взаємоперетворюваний з beancount(1).

Цей підручник призначений для інтерфейсу командного рядка hledger, версії 1.51.2. Він також описує загальні опції, формати файлів та концепції, що використовуються всіма програмами hledger. Він може випадково навчити вас трохи бухгалтерії/рахівництва, хоча вам не потрібно знати все це, щоб продуктивно використовувати hledger, але коли у вас виникне питання про функціональність, цей документ має відповісти на нього. Це детальний документ, тож прокручуйте або читайте скорочено, коли потрібно. Ви можете читати його на hledger.org, або як інформаційний посібник або довідкову сторінку у вашій системі. Ви також можете відкрити вбудовану копію, у точці інтересу, запустивши:

hledger --man [КОМАНДА]
hledger --info [КОМАНДА]
hledger help [ТЕМА]

(А для короткої довідки спробуйте hledger --tldr [КОМАНДА].)

Основна функція CLI hledger полягає в тому, щоб читати файли простого тексту, що описують фінансові операції, рахувати числа та друкувати корисний звіт у терміналі (або зберігати як HTML, CSV, JSON або SQL). Доступно багато звітів як підкоманд. hledger також виявляє інші виконувані файли hledger-* як додаткові підкоманди.

hledger зазвичай читає з (та додає до) файлу журналу, вказаного змінною середовища LEDGER_FILE (за замовчуванням $HOME/.hledger.journal); або ви можете вказати файли за допомогою опцій -f. Він також може читати файли timeclock, timedot або будь-який CSV/SSV/TSV файл з полем дати.

Ось невеликий файл журналу, що описує одну операцію:

2015-10-16 bought food
  expenses:food          $10
  assets:cash

Операції - це датовані рухи грошей (тощо) між двома або більше рахунками: банківськими рахунками, вашим гаманцем, категоріями доходів/витрат, людьми тощо. Ви можете вибрати будь-які назви рахунків, використовуючи : для позначення підрозділів. Має бути принаймні два пробіли між назвою рахунку та сумою. Позитивні суми - це приплив до цього рахунку (дебет), негативні - відплив з нього (кредит). (Деякі звіти показують баланси рахунків доходів, зобов'язків та капіталу як негативні числа - це нормально.)

Команда hledger add може допомогти вам додати операції, або ви можете встановити інші інтерфейси введення даних, як hledger-web або hledger-iadd. Для більш обширних/ефективних змін використовуйте текстовий редактор: Emacs + ledger-mode, VIM + vim-ledger або VS Code + hledger-vscode - деякі хороші варіанти (див. https://hledger.org/editors.html).

Щоб почати, запустіть hledger add і слідуйте підказкам, або збережіть кілька записів, як наведено вище, у $HOME/.hledger.journal, а потім спробуйте команди типу:

$ hledger print -x
$ hledger aregister assets
$ hledger balance
$ hledger balancesheet
$ hledger incomestatement

Запустіть hledger, щоб перелічити команди. Див. також розділи "Початок файлу журналу" та "Встановлення початкових балансів" у ЧАСТИНІ 5: ЗАГАЛЬНІ ЗАВДАННЯ.

ЧАСТИНА 1: ІНТЕРФЕЙС КОРИСТУВАЧА

ВХІДНІ ДАНІ

hledger читає один або кілька файлів даних щоразу, коли ви запускаєте його. Ви можете вказати файл за допомогою -f, ось так:

$ hledger -f ФАЙЛ [-f ФАЙЛ2 ...] print

Файли найчастіше у форматі журналу hledger, з розширенням .journal (.hledger або .j також працюють); ці файли описують операції, як загальний бухгалтерський журнал.

Коли файл не вказано, hledger шукає .hledger.journal у вашому домашньому каталозі.

Але більшість людей віддають перевагу зберіганню фінансових файлів у спеціальній папці, можливо, з контролем версій. Також, початок нового файлу журналу кожного року є поширеним (це не обов'язково, але допомагає тримати речі швидкими та організованими). Тому ми зазвичай налаштовуємо інший файл журналу, встановлюючи змінну середовища LEDGER_FILE, до чогось на зразок ~/finance/2023.journal. Для отримання додаткової інформації про те, як зробити це у вашій системі, див. "Загальні завдання > Встановлення LEDGER_FILE".

Кодування тексту

hledger очікує, що не-ASCII вхідні дані будуть декодовані з використанням кодування тексту локалі системи. (Для CSV/SSV/TSV файлів це можна перевизначити за допомогою правила CSV encoding.)

Отже, спроба читати файли не-ASCII, які мають неправильне кодування тексту, або коли не налаштовано локаль системи, призведе до помилки. Щоб виправити це, налаштуйте відповідно локаль вашої системи та/або перетворіть файли у кодування вашої системи (використовуючи iconv на unix, або powershell або notepad на Windows). Див. "Встановлення: Кодування тексту" для отримання додаткових порад.

Вихідні дані hledger будуть використовувати кодування локалі системи.

Документація та приклади hledger переважно використовують кодування UTF-8.

Формати даних

Зазвичай файл даних у форматі журналу hledger, але він може бути у будь-якому з підтримуваних форматів файлів, які наразі є:

Ці формати описані детальніше нижче.

hledger визначає формат автоматично на основі вищезгаданих розширень файлів. Якщо він не може розпізнати розширення файлу, він припускає формат journal. Тому для не-журнальних файлів важливо використовувати відоме розширення файлу, щоб або успішно прочитати, або показати відповідні повідомлення про помилки.

Ви також можете примусово вказати конкретний читач/формат, додавши префікс формату та двокрапку перед шлях до файлу. Наприклад, щоб прочитати файл .dat, що містить значення, розділені табуляцією:

$ hledger -f tsv:/де/файл.dat stats

Стандартний ввід

Ім'я файлу - означає стандартний ввід:

$ cat ФАЙЛ \| hledger -f- print

Якщо читаєте не-журнальні дані таким чином, вам потрібно написати формат як префікс, як timeclock: тут:

$ echo 'i 2009/13/1 08:00:00' \| hledger print -f timeclock:-

Кілька файлів

Ви можете вказати кілька опцій -f, щоб читати кілька файлів як один великий журнал. Роблячи це, зауважте, що певні функції (описані нижче) будуть впливати:

• Балансові твердження не побачать ефекту від операцій у попередніх файлах. (Зазвичай це не має значення, бо кожен файл встановлює відповідні початкові баланси.)
• Деякі директиви не вплинуть на попередні або наступні файли.

Якщо потрібно, ви можете обійти ці проблеми, використовуючи один батьківський файл, який включає інші, або об'єднуючи файли в один, наприклад: cat a.journal b.journal \| hledger -f- CMD.

Суворий режим

hledger перевіряє вхідні файли на валідність даних. За замовчуванням виявляються найважливіші помилки, при цьому все ще приймаються легкі журнальні файли без великої кількості оголошень:

• Чи є вхідні файли аналізуємими, з валідним синтаксисом?
• Чи всі операції збалансовані?
• Чи всі балансові твердження проходять?

З прапорцем -s/--strict, виконуються додаткові перевірки:

• Чи всі рахунки, на які здійснюються записи, оголошені директивою account? (Перевірка помилок рахунку)
• Чи всі товари оголошені директивою commodity? (Перевірка помилок товару)
• Чи всі перетворення товарів явно оголошені?

Ви можете використовувати команду check, щоб запустити окремі перевірки - ті, що перелічені вище, та ще кілька.

Команди

hledger надає різні підкоманди для виконання справ. Більшість з цих команд не змінюють файл журналу; вони просто читають його та виводять звіт. Кілька команд допомагають додавати дані та керувати файлами. Деякі часто використовувані команди: add, print, register, balancesheet та incomestatement.

Щоб показати резюме команд, запустіть hledger без аргументів. Ви можете побачити той самий звіт команд у початку ЧАСТИНИ 4: КОМАНДИ нижче.

Щоб використовувати певну команду, запустіть hledger CMD [CMDOPTS] [CMDARGS],

• CMD - це повна назва команди, або її стандартне скорочення, показане в списку команд, або будь-який префікс назви, що не призводить до плутанини.
• CMDOPTS - специфічні для команди опції, якщо є. Специфічні для команди опції мають бути записані після назви команди. Наприклад: hledger print -x.
• CMDARGS - додаткові аргументи для команди, якщо є. Більшість команд hledger приймають аргументи, що представляють запит, щоб обмежити дані певним чином. Наприклад: hledger reg assets:checking.

Щоб перелічити опції, аргументи та документацію команди в терміналі, запустіть hledger CMD -h. Наприклад: hledger bal -h.

Додаткові команди

На додачу до вбудованих команд, ви можете встановити додаткові команди, які також з'являться у списку команд hledger. Деякі з них можна встановити як окремі пакети; інші можна знайти в каталозі bin/ hledger, задокументовані на https://hledger.org/scripts.html.

Додаткові команди - це програми або скрипти у вашому шляху shell, імена яких починаються з "hledger-" і закінчуються без розширення або відомим розширенням (".bat", ".com", ".exe", ".hs", ".js", ".lhs", ".lua", ".php", ".pl", ".py", ".rb", ".rkt", або ".sh"), і (на unix та mac) які мають дозвіл на виконання для поточного користувача.

Ви можете запустити додаткові команди безпосередньо: hledger-ui --watch.

Або ви можете запустити їх з hledger, як вбудовані команди: hledger ui --watch. У цьому випадку буде використано файл конфігурації hledger, тож ви можете встановити спеціальні опції для аддону там. (До hledger 1.50, був потрібен аргумент -- перед опціями аддону, але тепер ні.)

Опції

Запустіть hledger -h, щоб побачити загальну довідку командного рядка. Опції можна записувати перед або після назви команди. Ці опції специфічні для CLI hledger:

Прапорці:
     --conf=CONFFILE        Використовувати додаткові опції, визначені в цьому файлі конфігурації. Якщо
                            не вказано, шукається вгору та в каталозі XDG для hledger.conf (або .hledger.conf в $HOME).
  -n --no-conf              ігнорувати будь-який файл конфігурації

І наступні загальні опції загальні для більшості команд hledger:

Загальні прапорці вхідних/перетворення даних:
  -f --file=[FMT:]FILE      Читати дані з FILE, або з stdin якщо FILE є -, 
                            визначаючи формат за розширенням або префіксом FMT:. 
                            Може бути вказано більше одного разу. Якщо не вказано, 
                            читає з $LEDGER_FILE або $HOME/.hledger.journal.
     --rules=RULESFILE      Використовувати правила, визначені в цьому файлі правил, для 
                            перетворення наступних CSV/SSV/TSV файлів. Якщо не 
                            вказано, використовується FILE.csv.rules для кожного FILE.csv.
     --alias=A=B|/RGX/=RPL  перетворювати назви рахунків з A на B, або шляхом 
                            заміни регулярних виразів
     --auto                 генерувати додаткові записи шляхом застосування правил автопостів 
                            ("=") до всіх операцій
     --forecast[=PERIOD]    Генерувати додаткові операції з періодичних правил 
                            ("~"), після останньої звичайної операції 
                            до 6 місяців від сьогодні. Або, протягом вказаного 
                            PERIOD (рівно потрібно). Правила автопостів 
                            також будуть застосовані до цих операцій. У 
                            hledger-ui, також зробити майбутні операції 
                            видимими при запуску.
  -I --ignore-assertions    не перевіряти балансові твердження за замовчуванням
     --txn-balancing=...    як перевірити, чи операції збалансовані:
                            'old':   використовувати глобальну точність відображення
                            'exact': використовувати точність операцій (за замовчуванням)
     --infer-costs          виводити еквівалентні пості для перетворення з вартостей
     --infer-equity         виводити вартості з еквівалентних постів перетворення
     --infer-market-prices  виводити ринкові ціни з вартостей
     --pivot=TAGNAME        використовувати інше поле або тег як назви рахунків
  -s --strict               виконувати додаткові перевірки помилок (і перевизначати -I)
     --verbose-tags         додавати теги, що вказують на згенеровані/змінені дані

Загальні прапорці виведення/звітування (підтримуються деякими командами):
  -b --begin=DATE           включати записи/операції на/після цієї дати
  -e --end=DATE             включати записи/операції до цієї дати
                            (з інтервалом звіту, буде скориговано до 
                            наступного підперіоду)
  -D --daily                багатоперіодичний звіт з 1-денним інтервалом
  -W --weekly               багатоперіодичний звіт з 1-тижневим інтервалом
  -M --monthly              багатоперіодичний звіт з 1-місячним інтервалом
  -Q --quarterly            багатоперіодичний звіт з 1-квартальним інтервалом
  -Y --yearly               багатоперіодичний звіт з 1-річним інтервалом
  -p --period=PERIODEXP     встановити початкову дату, кінцеву дату та/або інтервал звіту, 
                            з більшою гнучкістю
     --today=DATE           перевизначити сьогоднішню дату (впливає на відносні дати)
     --date2                відповідати/використовувати вторинні дати замість (застаріле)
  -U --unmarked             включати лише непозначені записи/операції
  -P --pending              включати лише очікуючі записи/операції
  -C --cleared              включати лише очищені записи/операції
                            (-U/-P/-C можна комбінувати)
  -R --real                 включати лише нереальні записи
  -E --empty                Показувати нульові елементи, які зазвичай приховані.
                            У hledger-ui & hledger-web, робити навпаки.
     --depth=DEPTHEXP       якщо число (або -NUM): показувати лише верхні NUM рівнів 
                            рахунків. Якщо REGEXP=NUM, застосовувати обмеження лише до 
                            рахунків, що відповідають регулярному виразу.
  -B --cost                 показувати суми, перетворені до їх вартості/суми продажу
  -V --market               Показувати суми, перетворені до їх вартості в кінці періоду(ів) 
                            у їхній валюті оцінки за замовчуванням.
                            Еквівалентно --value=end.
  -X --exchange=COMM        Показувати суми, перетворені до їх вартості в кінці періоду(ів) 
                            у вказаній валюті.
                            Еквівалентно --value=end,COMM.
     --value=WHEN[,COMM]    показувати суми, перетворені до їх вартості на 
                            вказані дати(у) у їхній валюті оцінки за замовчуванням або вказаній валюті. WHEN може бути:
                            'then':     вартість на дати операцій
                            'end':      вартість в кінці періоду(ів)
                            'now':      вартість сьогодні
                            YYYY-MM-DD: вартість на вказану дату
  -c --commodity-style=S    Перевизначити стиль відображення товару.
                            Наприклад: -c '.' або -c '1.000,00 EUR'
     --pretty[=YN]          Використовувати символи рамок у текстовому виведенні? Може бути 
                            'y'/'yes' або 'n'/'no'.
                            Якщо YN вказано, рівно потрібно.

Загальні прапорці довідки:
  -h --help                 показати довідку командного рядка
     --tldr                 показати приклади команд з tldr
     --info                 показати підручник з info
     --man                  показати підручник з man
     --version              показати інформацію про версію
     --debug=[1-9]          показати стільки відлагоджувального виведення (за замовчуванням: 1)
     --pager=YN             використовувати пейджер, коли потрібно ? y/yes (за замовчуванням) або n/no
     --color=YNA --colour   використовувати кольори в терміналі? y/yes (за замовчуванням), 
                            n/no, або a/auto (виявляти автоматично).
     --width=N              встановити ширину виведення (за замовчуванням: ширина терміналу)
     --height=N             встановити висоту виведення (за замовчуванням: висота терміналу)
     --file-url=URL         використовувати цю адресу замість шляху до файлу
     --watch                спостерігати за файлами та повторно запускати команду при зміні
     --watch-all            спостерігати за файлами та залежностями та повторно запускати команду при зміні
     --watch-args           спостерігати за файлами та аргументами та повторно запускати команду при зміні
     --watch-quick          використовувати швидке спостереження (менше використання CPU)
     --watch-poll           використовувати опитування для спостереження (якщо інші методи не працюють)
     --watch-delay=N        затримка спостереження в секундах (за замовчуванням: 0.5)
     --watch-ignore=GLOB    ігнорувати зміни у файлах, що відповідають GLOB
     --watch-include=GLOB   включати зміни у файлах, що відповідають GLOB
     --watch-quiet          не виводити повідомлення про зміни файлів
     --watch-verbose        виводити докладні повідомлення про зміни файлів
     --watch-debug          виводити дуже докладні повідомлення про зміни файлів
     --watch-recurse        рекурсивно спостерігати за підкаталогами
     --watch-no-recurse     не рекурсивно спостерігати за підкаталогами
     --watch-poll-delay=N   затримка опитування в секундах (за замовчуванням: 1)
     --watch-poll-throttle=N  обмеження опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-timeout=N  тайм-аут опитування в секундах (за замовчуванням: 60)
     --watch-poll-retries=N  кількість спроб опитування (за замовчуванням: 3)
     --watch-poll-backoff=N  коефіцієнт збільшення затримки опитування (за замовчуванням: 1.5)
     --watch-poll-max=N     максимальна затримка опитування в секундах (за замовчуванням: 10)
     --watch-poll-min=N     мінімальна затримка опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-stable=N  затримка стабільності опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-wait=N    затримка очікування опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-events=N  кількість подій опитування (за замовчуванням: 1000)
     --watch-poll-buffer=N  розмір буфера опитування (за замовчуванням: 1000)
     --watch-poll-threads=N кількість потоків опитування (за замовчуванням: 1)
     --watch-poll-queue=N   розмір черги опитування (за замовчуванням: 1000)
     --watch-poll-timeout-factor=N  коефіцієнт тайм-ауту опитування (за замовчуванням: 1.0)
     --watch-poll-retry-factor=N  коефіцієнт повторення опитування (за замовчуванням: 1.0)
     --watch-poll-backoff-factor=N  коефіцієнт збільшення опитування (за замовчуванням: 1.0)
     --watch-poll-max-retries=N  максимальна кількість спроб опитування (за замовчуванням: 3)
     --watch-poll-max-delay=N  максимальна затримка опитування в секундах (за замовчуванням: 10)
     --watch-poll-min-delay=N  мінімальна затримка опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-stable-delay=N  затримка стабільності опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-wait-delay=N  затримка очікування опитування в секундах (за замовчуванням: 0.1)
     --watch-poll-events-max=N  максимальна кількість подій опитування (за замовчуванням: 1000)
     --watch-poll-buffer-max=N  максимальний розмір буфера опитування (за замовчуванням: 1000)
     --watch-poll-threads-max=N максимальна кількість потоків опитування (за замовчуванням: 1)
     --watch-poll-queue-max=N   максимальний розмір черги опитування (за замовчуванням: 1000)

Зазвичай hledger приймає будь-який однозначний префікс прапорця, наприклад, ви можете написати --tl замість --tldr або --dry замість --dry-run.

Ви можете комбінувати короткі прапорці, які не потребують аргументів, наприклад, ви можете написати -MAST замість -M -A -S -T. Прапорці, що потребують аргумент, не можна комбінувати таким чином (-If FILE не спрацює).

Якщо одна й та ж опція з'являється більше одного разу в командному рядку, зазвичай перемагає останній (найправіший). Аналогічно, якщо використовуються взаємовиключні прапорці, перемагає правий. (Коли прапорці взаємовиключні, вони зазвичай мають префікс групи в --help.)

З більшістю команд аргументи інтерпретуються як запит hledger, який фільтрує дані. Деякі запити можна виразити або опціями, або аргументами.

Нижче наведено більше порад щодо використання інтерфейсу командного рядка - не соромтеся пропустити ці частини, поки вони вам не знадобляться.

Спеціальні символи

У командах, які ви вводите в командному рядку, певні символи мають особливе значення і іноді потребують "екранування" або "цитування", шляхом додавання зворотних слешів або укладання в лапки.

Якщо ви можете мінімізувати використання спеціальних символів у ваших даних, ви не будете мати справи з цим так часто. Наприклад, ви могли б використовувати дефіс - або підкреслення _ замість пробілів у назвах рахунків, і ви могли б використовувати код валюти USD замість символу валюти $ у сумах.

Але якщо ви віддаєте перевагу використанню назв рахунків із пробілами та $, це добре. Просто майте на увазі цю тему, щоб ви могли перевірити цей документ, коли потрібно. (Ці приклади перевірені на unix; деякі деталі можуть відрізнятися, якщо ви на Windows.)

Екранування спеціальних символів shell

Це деякі символи, які можуть мати особливе значення для вашого shell (програми, що інтерпретує командні рядки):

• SPACE, <, >, (, ), |, \, %
• $, якщо за ним йде символ слова

Тож, наприклад, щоб зіставити назву рахунку, що містить пробіли, як "credit card", не пишіть:

$ hledger register credit card

Замість цього, укладіть назву в одинарні лапки:

$ hledger register 'credit card'

На unix або в Windows powershell, якщо ви використовуєте подвійні лапки, ваш shell тихо буде вважати $ інтерполяцією змінної. Тому ви, ймовірно, повинні уникати подвійних лапок, якщо тільки ви не хочете цю поведінку, наприклад у скрипті:

$ hledger register "assets:$SOMEACCT"

Але в старому вікні CMD.EXE Windows, ви повинні використовувати подвійні лапки:

C:\Users\Me> hledger register "credit card"

На unix або в Windows powershell, як альтернативу лапкам, ви можете написати зворотний слеш перед кожним спеціальним символом:

$ hledger register credit\ card

Нарешті, оскільки запити hledger є регулярними виразами (описано нижче), ви також могли б заповнити цю прогалину з . який відповідає будь-якому символу:

$ hledger register credit.card

Екранування спеціальних символів регулярних виразів

Деякі символи також мають особливе значення в регулярних виразах, які часто є аргументами запитів hledger. До них відносяться:

• ., ^, $, [, ], (, ), |, \

Щоб екранувати один з них, напишіть \ перед ним. Але зауважте, що це додатково до екранування shell вище. Тож для символів, які є спеціальними і для shell, і для регулярних виразів, як \ і $, вам іноді знадобиться два рівні екранування.

Наприклад, звіт про баланс, що використовує запит cur:, що обмежує його лише валютою $, має бути написаний так:

$ hledger balance cur:\\$

Пояснення:

1. Додайте зворотний слеш \ перед знаком долара $, щоб захистити його від регулярних виразів (тож він буде зіставлятися буквально без особливого значення).
2. Додайте ще один зворотний слеш перед цим зворотним слешем, щоб захистити його від shell (тож shell не з'їсть його).
3. $ не потрібно захищати від shell в цьому випадку, бо за ним не йде символ слова; але було б безпечним зробити це.

Але ось інший спосіб написати це, який має бути легшим: додайте зворотні слеші для екранування від регулярних виразів, а потім укладіть в лапки для екранування від shell:

$ hledger balance cur:'\$'

Екранування в інших ситуаціях

Опції та аргументи hledger іноді використовуються в інших місцях, ніж командний рядок, де правила цитування/екранування інші. Наприклад, екранування зворотним слешем може бути недоступним. Ось швидке посилання:

| У unix shell | Використовуйте одинарні лапки та/або зворотний слеш (або подвійні лапки для інтерполяції змінної) | | У Windows powershell | Використовуйте одинарні лапки (або подвійні лапки для інтерполяції змінної) | | У Windows cmd | Використовуйте подвійні лапки | | У підказці фільтра hledger-ui | Використовуйте одинарні або подвійні лапки | | У формі пошуку hledger-web | Використовуйте одинарні або подвійні лапки | | У файлі аргументів | Не використовуйте пробіли, не екрануйте shell, екрануйте регулярні вирази, записуйте один аргумент/опцію на рядок | | У файлі конфігурації | Використовуйте одинарні або подвійні лапки, і укладіть весь аргумент (\'desc:a b\' не \'desc:\'a b\'\') | | У ghci (Haskell REPL) | Використовуйте подвійні лапки, і укладіть весь аргумент |

Символи Unicode

hledger очікує коректно обробляти не-ASCII символи:

• вони мають коректно аналізуватися у вхідних файлах та в командному рядку, у всіх інструментах hledger (add, iadd, форми пошуку/додавання/редагування hledger-web тощо)
• вони мають коректно відображатися у всіх інструментах hledger, і вирівнювання на екрані має зберігатися

Це вимагає добре налаштованого середовища. Ось кілька порад:

• Локаль системи має бути налаштована, яка може декодувати символи, що використовуються. Це є обов'язковим - див. Кодування тексту та Встановлення: Кодування тексту.
• Програмне забезпечення терміналу (наприклад, Terminal.app, iTerm, CMD.exe, xterm..) має підтримувати unicode. На Windows, вам може знадобитися використовувати Windows Terminal.
• Термінал має використовувати шрифт, який включає необхідні символи unicode.
• Термінал має бути налаштований для відображення широких символів як подвійної ширини (для вирівнювання звітів).
• На Windows, для найкращих результатів ви повинні запускати hledger в тому ж середовищі, в якому він був зібраний. Наприклад, hledger, зібраний в стандартному середовищі CMD.EXE (як двійкові файли на нашій сторінці завантаження), може показувати проблеми з відображенням при запуску в терміналі cygwin або msys, і навпаки. (Див. наприклад #961).

Регулярні вирази

Регулярний вираз (regexp) - це невелика частина тексту, де певні символи (як ., ^, $, +, *, (), |, [], \) мають особливе значення, формуючи маленьку мову для точного зіставлення тексту - дуже корисно в hledger та інших місцях. Щоб дізнатися все про них, відвідайте regular-expressions.info.

hledger підтримує регулярні вирази, коли б ви не вводили шаблон для зіставлення чогось, наприклад, у аргументах запиту, псевдонімах рахунків, правилах CSV if, формі пошуку hledger-web, пошук / hledger-ui тощо. Вам може знадобитися укладати їх у лапки, особливо в командному рядку (див. Спеціальні символи вище). Ось кілька прикладів:

Назви рахунків запиту (у лапках для використання в командному рядку):

Регулярний вираз:          Відповідає:
-------------------        ------------------------------------------------------------
bank                       активи:банк, активи:банк:ощад, витрати:мистецтво:банкси, ...
:банк                      активи:банк:ощад, витрати:мистецтво:банкси
:банк:                     активи:банк:ощад
'^банк'                    жодного з цих ( ^ відповідає початку тексту )
'банк$'                    активи:банк   ( $ відповідає кінцю тексту )
'великий \$ банк'          великий $ банк    ( \ вимикає спеціальне значення наступного символу )
'\bбанк\b'                 активи:банк, активи:банк:ощад  ( \b відповідає межам слова )
'(ощад|чек)ування'          ощад або чекування  ( (|) відповідає будь-якій альтернативі )
'ощад|чекування'            ощад або чекування  ( зовнішні дужки не потрібні )
'ощади?'                   ощад або ощади   ( ? відповідає 0 або 1 з попередньої речі )
'мій +банк'                мій банк, мій  банк, ... ( + відповідає 1 або більше попередньої речі )
'мій *банк'                мійбанк, мій банк, мій  банк, ... ( * відповідає 0 або більше попередньої речі )
'б.нк'                     банк, бонк, б нк, ... ( . відповідає будь-якому символу )

Деякі інші запити:

desc:'amazon|amzn|audible'  Операції Amazon
cur:EUR              Суми з символом товару, що містить EUR
cur:'\$'             Суми з символом товару, що містить $
cur:'^\$$'           Лише $ суми, не наприклад AU$ або CA$
cur:....?            Суми з 4-або-більше-символьними символами
tag:.=202[1-3]       Речі з будь-яким тегом, значення якого містить 2021, 2022 або 2023

Псевдоніми назв рахунків: приймати . замість : як розділювач рахунків:

alias /\./=:         замінює всі крапки в назвах рахунків на двокрапки

Показати кілька рахунків верхнього рівня, об'єднаних як один:

--alias='/^[^:]+/=об'  ( [^:] відповідає будь-якому символу, окрім : )

Показати рахунки з другим рівнем частини видаленої:

--alias '/^([^:]+):[^:]+/ = \1'
                     відповідає рахунку верхнього рівня та рахунку другого рівня
                     і замінює їх лише рахунком верхнього рівня
                     ( \1 в тексті заміни означає "те, що було зіставлено
                     першою дужкою регулярного виразу"

Правила CSV: відповідати записам CSV, що містять коди MCC пов'язані з харчуванням:

if \?MCC581[124]

Відповідати записам CSV з певною сумою біля кінця/початку місяця:

if %amount \b3\.99
&  %date   (29|30|31|01|02|03)$

Регулярні вирази hledger

Регулярні вирази hledger походять з бібліотеки regex-tdfa. Якщо вони не роблять того, що ви очікуєте, важливо знати точно, що вони підтримують:

1. вони нечутливі до регістру
2. вони відповідають інфіксу (вони не потребують зіставлення з усією річчю, що перевіряється)
3. вони є POSIX ERE (розширені регулярні вирази)
4. вони також підтримують межі слова GNU (\b, \B, \, \>)
5. зворотні посилання підтримуються при виконанні текстових замін у псевдонімах рахунків або правилах CSV, де зворотні посилання можуть використовуватися в тексті заміни для посилання на групи захоплення в регулярному виразі пошуку. В іншому випадку, якщо ви напишете \1, воно буде відповідати цифрі 1.
6. вони не підтримують модифікатори режиму ((?s)), класи символів (\w, \d), або щось інше, згадане вище.
7. вони, можливо, не (я гадаю, що ні) правильно підтримують текст зліва направо або двонаправлений текст.

Деякі речі, на які слід звернути увагу:

• У директиві alias і опції --alias, регулярні вирази мають бути укладені в прямі слеші (/REGEX/). В інших місцях hledger, ці не потрібні.
• У запитах, щоб відповідати метасимволу регулярного виразу, як $, як літерному символу, додайте зворотний слеш. Наприклад, щоб шукати суми зі знаком долара в hledger-web, напишіть cur:\$.
• У командному рядку, деякі метасимволи, як $, мають особливе значення для shell і тому мають бути екрановані ще раз. Див. Спеціальні символи.

Файли аргументів

Ви можете зберегти набір опцій командного рядка та аргументів у файлі, і використовувати їх, написавши @FILE.args як аргумент команди hledger. Розширення файлу .args є умовним, але не обов'язкове. У файлі аргументів:

• Кожен рядок може містити один аргумент, прапорець або опцію.
• Порожні рядки або рядки, що починаються з #, ігноруються.
• Прапорець та значення опції мають бути з'єднані через =.
• Значення опції або аргумент може містити пробіли. Не використовуйте одинарні або подвійні лапки.
• І загалом, використовуйте на один рівень менше цитування/екранування, ніж у командному рядку. Наприклад cur:\$, а не cur:\\$ як у командному рядку.

Наприклад:

# cash.args

активи:готівка
активи:charles schwab:sweep
cur:\$
-c=$1.

$ hledger bal @cash.args

Файли конфігурації

З hledger 1.40+, ви можете зберігати додаткові опції командного рядка та аргументи у більш функціональному файлі конфігурації hledger. Ось невеликий приклад:

# Загальні опції перелічені першими, і використовуються з командами hledger, що підтримують їх.
--pretty

# Опції після заголовка `[COMMAND]` використовуються лише з цією командою hledger.
[print]
--explicit --infer-costs

Щоб використовувати файл конфігурації, вкажіть його з опцією --conf. Його опції будуть вставлені близько початку вашого командного рядка, тож ви можете перевизначити їх опціями командного рядка, якщо потрібно.

Або, ви можете налаштувати автоматичний файл конфігурації, який використовується щоразу, коли ви запускаєте hledger, створивши hledger.conf у поточному каталозі або вище, або .hledger.conf у вашому домашньому каталозі (~/.hledger.conf), або hledger.conf у вашому каталозі конфігурації XDG (~/.config/hledger/hledger.conf).

Ось інший приклад конфігурації, з якої ви можете почати: https://github.com/simonmichael/hledger/blob/master/hledger.conf.sample

Ви можете покласти не лише опції, але й аргументи у файл конфігурації. Якщо перше слово у загальному розділі файлу конфігурації не починається з дефіса (наприклад, print), воно трактується як аргумент команди (перевизначаючи будь-який аргумент у командному рядку).

У unix-машинах, ви можете додати рядок шебанга у початок файлу конфігурації, встановити дозвіл на виконання файлу, і використовувати його як скрипт. Наприклад (прапорець -S потрібен на деяких операційних системах):

#!/usr/bin/env -S hledger --conf

Ви можете ігнорувати файли конфігурації, додавши прапорець -n/--no-conf до командного рядка. Це корисно при використанні hledger у скриптах, або при усуненні неполадок. Коли використовуються обидві опції --conf і --no-conf, перемагає найправіша.

Щоб перевірити обробку файлів конфігурації, використовуйте --debug або --debug=8. Або, запустіть команду setup, яка відобразить будь-які активні файли конфігурації. (setup не впливає на файли конфігурації, на відміну від інших команд.)

Попередження!

Не так багато функцій hledger потребують попередження, але це одна!

Автоматичні файли конфігурації, хоч і зручні, також роблять hledger менш передбачуваним і надійним. Легко зробити файл конфігурації, який змінює поведінку звіту, або порушує ваші скрипти/додатки hledger способами, які здивують вас пізніше.

Якщо ви не хочете цього,

1. Просто не створюйте файл hledger.conf на вашій машині.
2. Також будьте уважні до завантажених каталогів, які можуть містити файл hledger.conf.
3. Також якщо ви ділитеся скриптами або прикладами або підтримкою, майте на увазі, що інші можуть мати файл hledger.conf.

Навпаки, коли ви вирішите використовувати цю функцію, намагайтеся пам'ятати:

1. Коли команда hledger не працює, як очікувалося, спробуйте її знову з -n (--no-conf), щоб побачити, чи файл конфігурації був винен.
2. Коли ви викликаєте hledger зі скрипта, подумайте, чи цей виклик має використовувати -n чи ні.
3. Будьте обережні з тим, що ви кладете у свій файл конфігурації; намагайтеся враховувати ефект на всі ваші звіти.
4. Щоб усунути неполадки ефекту файлів конфігурації, запустіть з --debug або --debug 8.

Функція файлу конфігурації була додана в hledger 1.40.

Автодоповнення оболонки

Якщо ви використовуєте оболонки bash або zsh, ви можете опціонально налаштувати контекстно-чутливе автодоповнення для команд hledger. Спробуйте натиснути hledger<ПРОБІЛ><ТАБ><ТАБ> (має перерахувати всі команди hledger) або hledger reg acct:<ТАБ><ТАБ> (має перерахувати ваші назви рахунків верхнього рівня). Якщо автодоповнення не працює, або для отримання більше деталей, див. Встановлення > Автодоповнення оболонки.

ВИХІДНІ ДАНІ

Призначення вихідних даних

Команди hledger надсилають свої вихідні дані в термінал за замовчуванням. Ви можете, звісно, перенаправити це, наприклад, у файл, використовуючи стандартний синтаксис оболонки:

$ hledger print > foo.txt

Деякі команди (print, register, stats, команди балансу) також надають опцію -o/--output-file, яка робить те саме без потреби в оболонці. Наприклад:

$ hledger print -o foo.txt
$ hledger print -o -        # записувати в stdout (за замовчуванням)

Формат вихідних даних

Деякі команди пропонують інші види вихідних даних, не просто текст на терміналі. Ось ці команди та формати, що наразі підтримуються:

Ви також можете побачити, які формати виводу підтримує команда, запустивши hledger CMD -h і подивившись на опцію -O/--output-format=FMT.

Ви можете вибрати формат виводу, використовуючи цю опцію:

$ hledger print -O csv    # друкувати CSV в стандартний вивід

або вибираючи відповідне розширення імені файлу з опцією -o/--output-file=FILE.FMT:

$ hledger balancesheet -o foo.csv    # записувати CSV у foo.csv

Опція -O може бути поєднана з -o, щоб перевизначити розширення файлу, якщо потрібно:

$ hledger balancesheet -o foo.txt -O csv    # записувати CSV у foo.txt

Ось кілька нотаток про різні формати виводу.

Текстовий вивід

Це за замовчуванням: людино-читабельний, простий текстовий звіт, придатний для перегляду з моноширинним шрифтом у терміналі. Якщо ваші дані містять unicode або широкі символи, вам знадобиться термінал і шрифт, які відображають їх правильно. (Це може бути складно на MS Windows.)

Деякі звіти (register, aregister) зазвичай використовують повну ширину вікна. Якщо це не працює або ви хочете перевизначити це, ви можете використовувати опцію -w/--width.

Звіти балансу (balance, balancesheet, incomestatement...) використовують стільки ширини, скільки їм потрібно. Багатоперіодичні багатовалютні звіти часто можуть бути ширшими за вікно. Крім використання пейджера, корисні прийоми для цієї ситуації включають --layout=bare, -X COMM, cur:, --transpose, --tree, --depth, --drop, перемикання на html вивід тощо.

Символи рамок

hledger малює прості межі таблиць за замовчуванням, щоб мінімізувати ризик проблем з відображенням, спричинених терміналом/шрифтом, що не підтримує символи рамок. Але ваш термінал і шрифт, ймовірно, підтримують їх, тож ми рекомендуємо використовувати прапорець --pretty, щоб показувати гарніші таблиці в терміналі. Це гарний прапорець, щоб додати до вашого файлу конфігурації hledger.

Колір

hledger намагається автоматично виявити підтримку ANSI кольору та текстового оформлення і використовувати їх, коли це доречно. (Наразі використовується дуже мінімально: деякі звіти показують негативні числа червоним, і вивід довідки використовує жирний текст для акценту.)

Ви можете перевизначити це, встановивши змінну середовища NO_COLOR, щоб вимкнути її, або використовуючи опцію --color/--colour, можливо, у вашому файлі конфігурації.

Пейджинг

У середовищах, схожих на unix, коли відображаються великі вихідні дані (у будь-якому форматі виводу) в терміналі, hledger намагається використовувати пейджер, коли це доречно. (Ви можете вимкнути це з опцією --pager=no, можливо, у вашому файлі конфігурації.)

Пейджер показує одну сторінку тексту за раз і дозволяє прокручувати, щоб побачити більше. Поки він активний, зазвичай ПРОБІЛ показує наступну сторінку, h показує довідку, а q виходить. Клавіші Home/End/Page Up/Page Down/стрілки, а також прокрутка миші, також можуть працювати.

hledger використовуватиме пейджер, вказаний змінною середовища PAGER, інакше less, якщо доступний, інакше more, якщо доступний. (З одним винятком: hledger help -p TOPIC завжди використовуватиме less, щоб він міг прокрутити до теми.)

Пейджер очікує відображати ANSI кольори та текстове оформлення hledger. Якщо ви бачите сміття символів, вам може знадобитися налаштувати ваш пейджер для обробки ANSI кодів. Або ви можете вимкнути колір, як описано вище.

Якщо ви використовуєте пейджер less, hledger автоматично додає кілька опцій до змінної LESS, щоб увімкнути ANSI кольори та кілька інших зручностей. (На момент написання: --chop-long-lines --hilite-unread --ignore-case --no-init --quit-at-eof --quit-if-one-screen --RAW-CONTROL-CHARS --shift=8 --squeeze-blank-lines --use-backslash). Якщо це не працює добре, ви можете встановити ваші вподобані опції у змінній HLEDGER_LESS, яка буде використовуватися замість цього.

HTML вивід

HTML вивід може бути стилізований опціональним файлом hledger.css у тому ж каталозі.

HTML вивід буде фрагментом HTML, а не повним документом HTML. Як інші вихідні дані hledger, для не-ASCII символів він використовуватиме кодування тексту локалі системи (див. Кодування тексту).

CSV / TSV вивід

У виводі CSV або TSV, позначки груп цифр (наприклад, тисячні розділювачі) автоматично вимикаються.

FODS вивід

FODS - це формат електронної таблиці OpenDocument як простий XML, як приймається LibreOffice та OpenOffice. Якщо ви використовуєте їхні програми електронних таблиць, це краще за CSV, бо працює між локалями (десяткова крапка проти десяткової коми, кодування символів зберігається в XML заголовку, тож немає проблем з умлаутами), підтримує фіксовані заголовки рядків і стовпців, типи клітинок (рядок проти числа проти дати), розділення числа та валюти (валюта відображається, але тип клітинки все ще число, доступний для обчислень), стилі (жирний), межі. До речі, ви все ще можете витягувати CSV з FODS/ODS, використовуючи різні утиліти, як libreoffice --headless або ods2csv.

Beancount вивід

Це формат журналу Beancount. Ви можете використовувати це для експорту ваших даних hledger до Beancount, наприклад, щоб використовувати веб-додаток Fava.

hledger намагатиметься підлаштувати ваші дані до Beancount автоматично. Будьте обережні і перевірте перетворення, поки ви не будете впевнені, що воно добре. Якщо ви плануєте часто експортувати до Beancount, ви можете віддати перевагу конвенціям Beancount, для чистішого перетворення:

• використовуйте назви рахунків, дружні до Beancount
• використовуйте коди валют замість символів валют
• використовуйте нотацію вартості замість постів перетворення еквіваленту
• уникають віртуальних постів, призначень балансу та вторинних дат.

Є одна велика коригування, яке ви повинні зробити самі: для Beancount, назви рахунків верхнього рівня мають бути Assets, Liabilities, Equity, Income, та/або Expenses. Ви можете використовувати псевдоніми рахунків, щоб тимчасово переписати ваші назви рахунків, якщо потрібно, як у цьому файлі конфігурації hledger2beancount.conf.

2024-12-20: Ще кілька речей, що ще не обробляються автоматично:

• Директиви P не перетворюються автоматично - перетворюйте їх самі.
• Призначення балансу не перетворюються (Beancount не підтримує їх) - замініть їх явними сумами.

Назви рахунків Beancount

Окрім назв верхнього рівня, hledger підлаштує ваші назви рахунків, щоб зробити дійсні назви рахунків Beancount, капіталізуючи кожну частину, замінюючи пробіли на -, замінюючи інші непідтримувані символи на C<HEXBYTES>, додаючи A до частин назви рахунку, які не починаються з літери або цифри, і додаючи :A до назв рахунків, які мають лише одну частину.

Назви товарів Beancount

hledger підлаштує ваші назви товарів, щоб зробити дійсні назви товарів/валют Beancount, які мають бути 2-24 великими літерами, цифрами або ', ., _, -, починаючись з літери і закінчуючись літерою або цифрою. hledger перетворюватиме відомі символи валют на коди валют ISO 4217, капіталізуватиме літери, замінюватиме пробіли на -, замінюватиме інші непідтримувані символи на C<HEXBYTES>, і додаватиме або додаватиме C, якщо потрібно.

Віртуальні пости Beancount

Beancount не дозволяє віртуальні пости; якщо у вас є будь-які, вони будуть опущені з виводу beancount.

Метадані Beancount

теги hledger будуть перетворені на метадані Beancount (окрім тегів, чиї назви починаються з _). Назви метаданих будуть підлаштовані, щоб бути сумісними з Beancount: починаючись з малої літери, принаймні двох символів довжиною, і з непідтримуваними символами, закодованими. Значення метаданих використовуватимуть тип рядка Beancount.

У hledger, об'єкти можуть мати той самий тег, повторений з кількома значеннями. Наприклад, рахунок активи:готівка може мати обидва теги type:Asset та type:Cash. Для Beancount вони будуть об'єднані в один, зі значеннями, об'єднаними через кому. Наприклад: type: "Asset, Cash".

Вартості Beancount

Beancount не дозволяє надлишкові вартості та пости перетворення, як hledger. Якщо у вас є будь-які з цих, пости перетворення будуть опущені. Наразі ми підтримуємо принаймні одну групу вартість + пост перетворення на операцію.

Валюта операцій Beancount

Оголошення валюти операцій (або кількох) покращує звіти Beancount та Fava. Наразі hledger оголошуватиме кожну валюту, використану в сумах вартості, як валюту операцій. Якщо потрібно, замініть ці своїм оголошенням, як

option "operating_currency" "USD"

SQL вивід

SQL вивід очікує працювати принаймні з SQLite, MySQL та Postgres.

Інструкції SQL очікують бути виконаними в порожній базі даних. Якщо у вас вже є створені таблиці через вивід SQL hledger, ви, ймовірно, захочете або очистити дані з цих (через інструкції delete або truncate SQL) або drop таблиці повністю перед імпортом; інакше ваші пости будуть дубльовані.

Для SQLite, це корисніше, якщо ви модифікуєте згенерований id поле, щоб бути PRIMARY KEY. Наприклад:

$ hledger print -O sql | sed 's/id serial/id INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL/g' | ...

Це ще не дуже використовується; відгуки вітаються.

JSON вивід

Наш JSON досить великий і багатий, оскільки це вірне представлення внутрішніх типів даних hledger. Щоб зрозуміти його структуру, прочитайте визначення типів Haskell, які переважно знаходяться в https://github.com/simonmichael/hledger/blob/master/hledger-lib/Hledger/Data/Types.hs. Специфікація OpenAPI hledger-web також може бути релевантною.

hledger зберігає числа з іноді до 255 значущих цифр. Це забагато цифр для більшості споживачів JSON, тож у виводі JSON ми округлюємо числа до максимум 10 десяткових знаків. (Ми не обмежуємо кількість цілих цифр.) Якщо ви вважаєте, що це спричиняє проблеми, будь ласка, повідомте нас. Пов'язане: #1195

Це ще не дуже використовується; відгуки вітаються.

Стилі товарів

При відображенні сум, hledger визначає стандартний стиль відображення для кожного товару/валюти, як описано нижче в Стиль відображення товарів.

Якщо потрібно, це можна перевизначити опцією -c/--commodity-style (окрім сум вартості і сум, відображених командою print, які завжди відображаються з усіма десятковими цифрами). Наприклад, наступне змусить суми доларів відображатися, як показано:

$ hledger print -c '$1.000,0'

Цю опцію можна повторити, щоб встановити стиль відображення для кількох товарів/валют. Її аргумент як описано в директиві товару. Зауважте, що опускання символу товару встановить стиль відображення лише для товару без символу, а не для всіх товарів.

У деяких випадках hledger буде коригувати форматування чисел, щоб покращити їхню парсабельність (наприклад, додаючи кінцеві десяткові позначки, коли потрібно).

Відлагоджувальний вивід

Ми маємо на меті, щоб hledger був відносно легким для усунення неполадок, інспектування та розробки. Ви можете додати --debug[=N] до будь-якого командного рядка hledger, щоб побачити додатковий відлагоджувальний вивід. N варіюється від 1 (найменший вивід, за замовчуванням) до 9 (максимальний вивід). Зазвичай ви починаєте з 1 і збільшуєте, поки не бачите достатньо. Відлагоджувальний вивід йде до stderr і не впливає на -o/--output-file (окрім випадку, коли ви перенаправляєте stderr до stdout, наприклад: 2>&1). Він буде перемішаний з нормальним виводом, що може допомогти виявити, коли частини коду оцінюються. Щоб захопити відлагоджувальний вивід у файлі журналу замість цього, ви можете зазвичай перенаправити stderr, наприклад:

hledger bal --debug=3 2>hledger.log

(Ця опція не працює у файлі конфігурації ще.)

Середовище

Ці змінні середовища впливають на hledger:

HLEDGER_LESS Якщо less є вашим пейджером, ця змінна вказує опції less, які hledger має використовувати. (В іншому випадку використовуються LESS + власні опції.)

LEDGER_FILE Файл журналу за замовчуванням, який використовується, коли не надано опцію -f/--file. Наприклад, це може бути ~/finance/main.journal. Це також може бути шаблон glob, наприклад ./2???.journal. (Якщо шаблон відповідає кільком файлам, використовується лише перший за алфавітом.) Якщо LEDGER_FILE вказує на неіснуючий файл, буде викинуто помилку. Якщо значення порожнє, воно ігнорується.

Якщо LEDGER_FILE не встановлено і не надано -f, файл журналу за замовчуванням - $HOME/.hledger.journal (або якщо домашній каталог не можна виявити, ./.hledger.journal).

Див. також Загальні завдання > Встановлення LEDGER_FILE.

NO_COLOR Якщо ця змінна середовища існує (з будь-яким значенням, включаючи порожнє), hledger не використовуватиме ANSI кольори у виводі терміналу, окрім випадку, коли перевизначено явною опцією --color=y або --colour=y.

ЧАСТИНА 2: ФОРМАТИ ДАНИХ

Журнал

Звичайним джерелом даних hledger є простий текстовий файл, що містить записи журналу у форматі журналу hledger. Якщо ви шукаєте швидке посилання, перестрибніть до шпаргалки журналу (або використовуйте зміст на https://hledger.org/hledger.html).

Цей файл представляє Загальний журнал бухгалтерії. Розширення файлу .journal найчастіше використовується, хоча не є суворо обов'язковим. Файл журналу містить кілька записів операцій, кожен описує передачу грошей (або будь-якого товару) між двома або більше названими рахунками, у простому форматі, придатному для читання як hledger, так і людьми.

Формат журналу hledger сумісний з більшістю формату журналу Ledger, але не з усім. Відмінності та поради щодо взаємодії описані на https://hledger.org/ledger.html. З певною обережністю та униканням несумісних функцій, ви можете тримати ваш журнал hledger придатним для читання Ledger і навпаки. Це може бути корисно, наприклад, для порівняння поведінки однієї програми проти іншої.

Ви можете використовувати hledger без вивчення чогось більше про цей файл; просто використовуйте команди add, web або import, щоб створювати та оновлювати його.

Багато користувачів, однак, редагують файл журналу текстовим редактором і відстежують зміни з системою контролю версій, як git. Додатки редактора, як ledger-mode або hledger-mode для Emacs, vim-ledger для Vim, і hledger-vscode для Visual Studio Code, полегшують це, додаючи колір, форматування, автодоповнення табуляції та корисні команди. Див. Редактори на hledger.org для повного списку.

Файл журналу hledger може містити три види речей: рядки коментарів, операції та директиви (включаючи правила періодичних операцій та правила автоматичних постів). Розуміння формату файлу журналу також дасть вам гарне розуміння моделі даних hledger. Ось швидка шпаргалка/огляд, за яким йдуть докладні описи кожної частини.

Шпаргалка журналу

# Ось головний синтаксис формату журналу hledger
# (опускаючи додатковий синтаксис сумісності з Ledger).

###############################################################################

# 1. Це рядки коментарів, для нотаток або тимчасового вимкнення речей.
# Вони починаються з # або ;
comment
Або, рядки можуть бути укладені в "comment" / "end comment".
Це блок
закоментованих
рядків.
end comment

# Деякі записи журналу можуть мати коментарі з крапкою з комою в кінці рядка  ; як це
# Деякі з них вимагають 2 або більше пробілів перед крапкою з комою.

###############################################################################

# 2. Директиви налаштовують обробку або вивід певним чином.
# Вам не потрібні жодні директиви, щоб почати.
# Але вони можуть додати більше перевірок помилок або змінити спосіб відображення.
# Вони починаються з слова, літери або символу.
# Вони найчастіше розташовані зверху, перед операціями.

account assets             ; Оголосити дійсні назви рахунків і порядок відображення.
account assets:savings     ; Підрозділ. Це представляє банківський рахунок.
account assets:checking    ; Ще один. Зауважте, 2+ пробіли після назви рахунку.
account assets:receivable  ; Тип обліку визначається з англійських назв,
account passifs            ; або оголошується з тегом "type", type:L
account expenses           ; type:X
                           ; Коментар наступного рядка, з відступом.
account expenses:rent      ; Підрозділи успадковують тип батьківського рахунку.

commodity $0.00         ; Оголосити дійсні товари та їхні стилі відображення.
commodity 1.000,00 EUR

decimal-mark .          ; Десятковий розділювач, використаний у цьому файлі (якщо неоднозначний).

payee Whole Foods       ; Оголосити дійсне ім'я платника.

tag trip                ; Оголосити дійсне ім'я тегу.

P 2024-03-01 AAPL $179  ; Оголосити ринкову ціну для AAPL у $ у цю дату.

include other.journal   ; Включити інший файл журналу тут.

# Оголосити повторювану "періодичну операцію", для бюджетних/прогнозних звітів
~ monthly  set budget goals  ; <- Зауважте, 2+ пробіли перед описом.
    (expenses:rent)      $1000
    (expenses:food)       $500

# Оголосити правило автоматичного посту, щоб змінити існуючі операції у звітах
= revenues:consulting
    liabilities:tax:2024:us          *0.25  ; Додати зобов'язок податку та витрати
    expenses:tax:2024:us            *-0.25  ; для 25% доходу.

###############################################################################

# 3. Операції - це все про це.
# Вони є датованими подіями, зазвичай рухами грошей між 2 або більше рахунками.
# Вони починаються з числової дати.
# Ось їхня основна форма:
#
# DATE DESCRIPTION    ; Дата операції та опціональний опис.
#   ACCOUNT1  AMOUNT  ; Пост на суму до/від цього рахунку, з відступом.
#   ACCOUNT2  AMOUNT  ; Другий пост, збалансовуючи перший.
#   ...               ; Більше, якщо потрібно. Суми мають підсумовуватися до нуля.
#                     ; Зауважте, 2+ пробіли між назвами рахунків і сумами.

2024-01-01 opening balances         ; На початку, оголосіть існуючі баланси таким чином.
    assets:savings          $10000  ; Назви рахунків можуть бути будь-якими. маленькі літери легко друкувати.
    assets:checking          $1000  ; активи, зобов'язки, капітал, доходи, витрати - загальні.
    liabilities:credit card  $-500  ; баланси зобов'язків, капіталу, доходів зазвичай негативні.
    equity:start                    ; Одна сума може бути залишена порожньою. $-1050 тут виводиться. 
                                    ; Деякі з цих рахунків ми не оголошували вище,
                                    ; тож -s/--strict скаржився б.

2024-01-03 ! (12345) pay rent
    ; Додаткові коментарі операції, з відступом.
    ; Може бути ! або * після дати, що означає "очікується" або "очищено".
    ; Може бути дужки (code) після дати/статусу.
                                    ; Суми зі знаком показують напрямок потоку.
    assets:checking          $-500  ; Мінус означає видалення з цього рахунку (кредит).
    expenses:rent             $500  ; Плюс означає додавання до цього рахунку (дебет).

; Зберігання операцій у порядку дати є необов'язковим (але допомагає перевірці помилок).

2024-01-02 Gringott's Bank | withdrawal  ; Опис може бути PAYEE | NOTE
    assets:bank:gold       -10 gold
    assets:pouch            10 gold

2024-01-02 shopping
    expenses:clothing        1 gold
    expenses:wands           5 gold
    assets:pouch            -6 gold

2024-01-02 receive gift
    revenues:gifts          -3 "Chocolate Frogs"  ; Складні символи товарів
    assets:pouch             3 "Chocolate Frogs"  ; мають бути в подвійних лапках.

2024-01-15 buy some shares, in two lots                 ; Вартість може бути зазначена.
    assets:investments:2024-01-15     2.0 AAAA @ $1.50  ; @  означає вартість за одиницю
    assets:investments:2024-01-15-02  3.0 AAAA @@ $4    ; @@ означає загальну вартість
                      ; ^ Підрозділи за лотами іноді корисні.
    assets:checking                 $-7

2024-01-15 assert some account balances on this date
    ; Баланси можуть бути затверджені в будь-якій операції, з =, для додаткової перевірки помилок.
    ; Операції затвердження, як ця, можна зробити з hledger close --assert --show-costs
    ;
    assets:savings                    $0                   = $10000
    assets:checking                   $0                   =   $493
    assets:bank:gold                   0 gold              =    -10 gold
    assets:pouch                       0 gold              =      4 gold
    assets:pouch                       0 "Chocolate Frogs" =      3 "Chocolate Frogs"
    assets:investments:2024-01-15      0.0 AAAA            =      2.0 AAAA @  $1.50
    assets:investments:2024-01-15-02   0.0 AAAA            =      3.0 AAAA @@ $4
    liabilities:credit card           $0                   =  $-500

2024-02-01 note some event, or a transaction not yet fully entered, on this date
    ; Пости не потрібні.

# Консистентний формат дати YYYY-MM-DD рекомендований,
# але ви можете використовувати . або / і опускати початкові нулі, якщо хочете.
2024.01.01
2024/1/1

Коментарі

Рядки в журналі ігноруються, якщо вони починаються з решітки (#) або крапки з комою (;). (Див. також Інший синтаксис.) hledger також ігноруватиме регіони, що починаються з рядка comment і закінчуються рядком end comment (або кінцем поточного файлу). Ось пропозиція для вибору між ними:

• # для нотаток верхнього рівня
• ; для тимчасового коментування речей
• comment для швидкого коментування великих регіонів (пам'ятайте про це, або ви можете збутися)

Наприклад:

# рядок коментаря
; ще один рядок коментаря
comment
Багаторядковий коментар,
продовжується до "end comment" директиви
або кінця поточного файлу.
end comment

Деякі записи hledger можуть мати прикріплені коментарі одного рядка, від ; (крапка з комою) до кінця рядка. Див. Коментарі операцій, Коментарі постів та Коментарі рахунків нижче.

Операції

Операції є основною одиницею інформації у файлі журналу. Вони представляють події, зазвичай рух певної кількості товарів між двома або більше названими рахунками.

Кожна операція записується як запис журналу, що починається з простої дати у стовпці 0. Це може бути доповнено будь-якими з наступних необов'язкових полів, розділених пробілами:

• статус символ (порожній, !, або *)
• код (будь-яке коротке число або текст, у дужках)
• опис (будь-який залишок тексту до кінця рядка або крапки з комою)
• коментар (будь-який залишок тексту після крапки з комою до кінця рядка, і будь-які наступні рядки з відступом, що починаються з крапки з комою)
• 0 або більше рядків постів з відступом (коментарі з відступом також дозволені, але не порожні рядки або рядки без відступу).

Ось простий файл журналу, що містить одну операцію:

2008/01/01 income
  assets:bank:checking   $1
  income:salary         $-1

Дати

Прості дати

hledger приймає ці формати дати: YYYY-MM-DD, YYYY/MM/DD або YYYY.MM.DD, з необов'язковими початковими нулями. Рік може бути опущений, у цьому випадку він буде виведений з контексту: поточної операції, рік за замовчуванням, встановлений з директиви Y, або поточна дата, коли команда запускається. Деякі приклади: 2010-01-31, 2010/01/31, 2010.1.31, 1/31.

(Інтерфейс також приймає прості дати, а також більш гнучкі розумні дати, задокументовані в підручнику hledger.)

Дати постів

Ви можете дати окремим постам іншу дату, ніж у батьківської операції, додавши коментар посту, що містить тег (див. нижче) як ; date:DATE. (Є також сумісний синтаксис Ledger, ; [DATE], який може бути зручним.)

Це, ймовірно, найкращий спосіб точно контролювати дати постів. Наприклад, у цьому прикладі витрати повинні з'явитися у звітах травня, а списання з рахунку має бути показано 6/1 для легкої звірки з банком:

2015/5/30
    expenses:food     $10  ; їжа придбана в суботу 5/30
    assets:checking        ; банк очистив це в понеділок, date:6/1

$ hledger -f t.j register food
2015-05-30                      expenses:food                  $10           $10

$ hledger -f t.j register checking
2015-06-01                      assets:checking               $-10          $-10

DATE має бути простою датою; якщо рік не вказано, він використовуватиме рік дати операції. Тег date: має мати дійсне значення простої дати, якщо він присутній, наприклад тег date: без значення не дозволений.

Статус

Операції (або окремі пости в операції) можуть мати позначку статусу, яка є єдиним символом перед описом операції (або назвою посту), відокремленим від неї пробілом, що вказує на один з трьох статусів:

При звітуванні ви можете фільтрувати за статусом з прапорцями -U/--unmarked, -P/--pending, і -C/--cleared (і ви можете поєднувати ці, наприклад -UP, щоб відповідати всім, окрім очищених). Або ви можете використовувати запити status:, або клавіші U, P, C в hledger-ui.

(Зауважте: у Ledger стан "непозначений" називається "нечітким"; у hledger ми перейменували його на "непозначений" для семантичної ясності.)

Позначки статусу необов'язкові, але можуть бути корисними, наприклад, для звірки з реальними обліками. Деякі режими редактора надають підсвічування та ярлики для роботи зі статусом. Наприклад, у режимі ledger Emacs, ви можете перемикати статус операції з C-c C-e, або статус посту з C-c C-c.

Що насправді означають "нечіткий", "очікується" та "очищено", залежить від вас. Ось одна пропозиція:

З цією схемою, ви б використовували -PC, щоб побачити поточний баланс у вашому банку, -U, щоб побачити речі, які, ймовірно, скоро потраплять на ваш банківський рахунок (як некешовані чеки), і без прапорців, щоб побачити найактуальніший стан ваших фінансів.

Код

Після позначки статусу, але перед описом, ви можете опціонально написати "код" операції, у дужках. Це гарне місце для запису номера чека або якогось іншого важливого ідентифікатора операції або посилання.

Опис

Після полів дати, позначки статусу та/або коду, решта рядка (або до початку коментаря з ;) є описом операції. Тут ви можете описати операцію (називається "оповідання" у традиційному бухгалтерському обліку), або ви можете записати ім'я платника/одержувача, або залишити його порожнім.

Описи операцій з'являються у виводі print та у звітах register, і можуть бути перераховані командою descriptions.

Ви можете запитувати за описом з desc:DESCREGEX, або поворотити на опис з --pivot desc.

Одержувач і нотатка

Іноді люди хочуть виділене поле одержувача/платника, яке можна запитувати та перевіряти більш суворо. Якщо ви хочете цього, ви можете написати символ | (вертикальна риска) в описі. Це ділить його на поле "одержувача" зліва та поле "нотатки" справа. (Обидва можуть бути порожніми.)

Ви можете запитувати ці з payee:PAYEEREGEX і note:NOTEREGEX, перераховувати їхні значення командами payees та notes, або поворотити на payee або note.

Зауважте: в операціях без символу |, опис, одержувач і нотатка мають однакове значення. Як тільки додається |, вони стають відмінними. (Якщо ви хочете змінити цю поведінку, будь ласка, запропонуйте це в списку розсилки.)

Якщо ви хочете більш сувору перевірку помилок, ви можете оголосити дійсні імена одержувачів з директивами payee, а потім забезпечити ці з hledger check payees. (Зауважте: через вищезгадане, для цього вам знадобиться забезпечити, щоб кожен опис операції містив | і, отже, ім'я одержувача, навіть якщо воно порожнє.)

Коментарі операцій

Текст після ;, після опису операції, і/або на рядках з відступом безпосередньо під нею, утворюють коментарі для цієї операції. Вони відтворюються командою print, але інакше ігноруються, окрім випадків, коли вони можуть містити теги, які не ігноруються.

2012-01-01 something  ; коментар операції
    ; другий рядок коментаря операції
    expenses   1
    assets

Пости

Пост є додаванням якоїсь суми до, або видаленням якоїсь суми з рахунку. Кожен рядок посту починається з принаймні одного пробілу або табуляції (2 або 4 пробіли загальноприйняті), після яких йде:

• (необов'язково) статус символ (порожній, !, або *), після якого йде пробіл
• (обов'язково) назва рахунку (будь-який текст, опціонально включаючи одинарні пробіли. Якщо після назви рахунку на тому ж рядку щось є, назва рахунку має бути закінчена двома або більше пробілами.)
• (необов'язково) сума
• (необов'язково) коментар посту того самого рядка, що починається з крапки з комою (;).

Якщо сума позитивна, вона додається до рахунку; якщо негативна, вона видаляється з рахунку.

Суми постів в операції мають підсумовуватися до нуля, що вказує на те, що припливи та відпливи рівні. Ми називаємо це збалансованою операцією. (Ви можете прочитати більше про деталі балансування операцій нижче.)

Якщо сума не записана, вона буде обчислена автоматично з інших постів в операції, щоб збалансувати операцію. Іншими словами, в будь-якій операції ви можете залишити один пост без суми, щоб заощадити час на введення.

Дебет і кредит

Традиційні бухгалтерські поняття дебету і кредиту, звісно, існують у hledger, але ми представляємо їх числовим знаком. Позитивні та негативні суми постів представляють дебет і кредит відповідно.

Вам не потрібно це пам'ятати, але якщо ви хочете - наприклад, щоб допомогти новачкам або говорити з вашим бухгалтером - ось зручна мнемоніка:

дебет / плюс / ліворуч / короткі слова
кредит / мінус / праворуч / довші слова

Назви рахунків

Рахунки є основним способом категоризації речей у hledger. Як у Подвійному бухгалтерському обліку, вони можуть представляти реальні світові рахунки (наприклад, банківський рахунок), або більш абстрактні категорії, як "гроші, витрачені на їжу" або "гроші, позичені у Френка".

Назви рахунків гнучкі. Вони можуть бути великими або малими; вони можуть містити літери, цифри, пунктуацію, символи або окремі пробіли; вони можуть бути будь-якою мовою.

Зазвичай ми використовуємо п'ять традиційних бухгалтерських категорій як початкову точку для назв рахунків. У англійській мові це:

assets, liabilities, equity, revenues, expenses

Про ці буде більше в Типах рахунків нижче. У документації hledger ви можете бачити, як їх називають A, L, E, R, X для скорочення.

Розділювач двох пробілів

Зауважте два або більше пробілів після назви рахунку, які іноді потрібні. Назви рахунків hledger, успадковані від Ledger, дуже дозвільні; вони можуть містити майже будь-який текст, включаючи окремі пробіли та крапки з комою. Через це, вони мають бути закінчені двома або більше пробілами, якщо після них на тому ж рядку щось є. Наприклад, якщо сума, призначення балансу або коментар того самого рядка йде після назви рахунку, вони мають бути попереджені двома або більше пробілами, інакше вони вважатимуться частиною назви рахунку:

погано:     assets:accounts receivable $10        ; <- занадто близько!
добре:    assets:accounts receivable  $10

погано:     assets:accounts receivable =$1000     ; <- занадто близько!
добре:    assets:accounts receivable  =$1000

погано:     assets:accounts receivable ; коментар.   <- занадто близько!
добре:    assets:accounts receivable  ; коментар

Цей розділювач двох пробілів з'являється в кількох місцях у hledger, наприклад, після назв рахунків у постах або директивах рахунків; також після виразу періоду в правилах періодичних операцій. Коли ви починаєте, очікуйте, що це зловить вас принаймні раз. Це іноді дратує, але дозволяє нам використовувати виразні назви рахунків і все ще зберігати легкий синтаксис.

Ієрархія рахунків

Для більш точного звітування ми зазвичай ділимо рахунки на більш детальні підрозділи, підрозділи підрозділів тощо, записуючи повну двокрапку між частинами назви рахунку. Наприклад, замість написання assets та expenses, ми могли б написати assets:bank:checking та expenses:food. З цих назв hledger виведе цю ієрархію з п'яти рахунків:

assets
assets:bank
assets:bank:checking
expenses
expenses:food

Або як контур:

assets
 bank
  checking
expenses
 food

Звіти hledger можуть узагальнювати дерево рахунків до будь-якої глибини, тож ви можете робити свої підкатегорії такими детальними, як вам подобається. Але не перестарайтеся, особливо на початку; простіші категорії можуть бути меншою роботою.

Інші функції назв рахунків

Заключення назви рахунку в дужки або квадратні дужки, як (expenses:food), увімкне нестандартну функцію бухгалтерії: віртуальні пости.

Назви рахунків можуть бути переписані та переформатовані, тимчасово або постійно, псевдонімами рахунків.

Суми

Після назви рахунку, зазвичай є сума. (Зауважте: між назвою рахунку та сумою має бути два або більше пробілів.)

Формат сум hledger гнучкий, підтримуючи кілька міжнародних форматів. Ось кілька прикладів. Суми мають число (кількість):

1

..і зазвичай символ валюти або назву товару (більше про це нижче), ліворуч або праворуч від кількості, з або без розділювача пробілу:

$1
4000 AAPL
3 "green apples"

Суми можуть бути попереджені мінусом (або плюсом, хоча плюс є за замовчуванням), Знак може бути записаний перед або після символу валюти ліворуч:

-$1
$-1

Один або більше пробілів між знаком і числом прийнятні при аналізі (але вони не відображатимуться у виводі):

+ $1
$-      1

Підтримується наукова нотація E:

1E-6
EUR 1E3

Десяткові розділювачі

Десятковий розділювач може бути записаний як крапка або кома:

1.23
1,23

Обидва ці поширені у міжнародних числових форматах, тож hledger не має упередження щодо одного чи іншого. Через те, що hledger також підтримує позначки груп цифр (наприклад, тисячні розділювачі), це означає, що число, як 1,000 або 1.000, що містить лише одну крапку або кому, є неоднозначним. У таких випадках hledger за замовчуванням припускає, що це десятковий розділювач, і аналізуватиме обидва як 1.

Щоб допомогти hledger аналізувати такі неоднозначні числа точніше, якщо ви використовуєте позначки груп цифр, ми рекомендуємо оголошувати десятковий розділювач явно. Найкращий спосіб - додати директиву decimal-mark у верхню частину кожного файлу даних, ось так:

decimal-mark .

Або ви можете оголосити його на товар за допомогою директиви commodity, описаної нижче.

hledger також приймає числа, як 10., без цифр після десяткового розділювача (і відображатиме їх іноді з цим способом, щоб усунути неоднозначність - див. Кінцеві десяткові розділювачі).

Позначки груп цифр

У цілій частині кількості суми (ліворуч від десяткового розділювача), групи цифр можуть опціонально бути розділені позначкою групи цифр - комою або крапкою (будь-яка, що не використовується як десятковий розділювач), або пробілом (кілька варіантів пробілів Unicode, як нерозривний пробіл, також приймаються). Тож ось усі дійсні суми у файлі журналу:

     $1,000,000.00
  EUR 2.000.000,00
INR 9,99,99,999.00
      1 000 000.00   ; <- звичайний пробіл
      1 000 000.00   ; <- нерозривний пробіл

Товар

Суми в hledger мають обидва "кількість", яка є підписаною десятковою кількістю, і "товар", який є символом валюти, тікером акцій або будь-яким словом або фразою, що описує щось, що ви відстежуєте.

Якщо назва товару містить не-літери (пробіли, цифри або пунктуацію), ви повинні завжди записувати її в подвійних лапках ("green apples", "ABC123").

Якщо ви напишете лише просте число, у нього також буде товар, з іменем ""; ми називаємо це "товаром без символу".

Насправді, hledger поєднує ці однотоварні суми в більш потужні багатотоварні суми, з якими він працює більшість часу. Багатотоварна сума могла б бути, наприклад: 1 USD, 2 EUR, 3.456 TSLA. На практиці, ви бачитимете лише багатотоварні суми у виводі hledger; ви не можете записувати їх безпосередньо у файл журналу.

За замовчуванням, формат сум у журналі впливає на те, як hledger відображає їх у виводі. Це пояснюється в Стилі відображення товарів нижче.

Вартості

Після суми посту, ви можете зазначити її вартість (при покупці) або ціну продажу (при продажу) в іншому товарі, написавши або @ ЦІНА_ЗА_ОДИНИЦЮ або @@ ЗАГАЛЬНА_ЦІНА після неї. Це вказує на операцію перетворення, де один товар обмінюється на інший.

(Ви також можете бачити це, назване "ціна операції" у документації hledger, обговореннях або коді; цей термін був нейтральним до напрямку і нагадував, що це ціна, специфічна для операції, але ми тепер просто називаємо це "вартістю", з розумінням, що операція може бути покупкою або продажем.)

Вартості зазвичай записуються явно з @ або @@, але можуть бути виведені автоматично для простих багатотоварних операцій. Зауважте, якщо вартості виводяться, порядок постів має значення; до вартості додається перший пост, у валюті другого.

Як приклад, ось кілька способів запису покупок іноземної валюти в hledger, використовуючи нотацію вартості або явно, або неявно:

1. Написати ціну за одиницю, як @ ЦІНА_ЗА_ОДИНИЦЮ після суми:

2009/1/1
  assets:euros     €100 @ $1.35  ; сто євро придбано за $1.35 кожен
  assets:dollars                 ; збалансована сума -$135.00

2. Написати загальну ціну, як @@ ЗАГАЛЬНА_ЦІНА після суми:

2009/1/1
  assets:euros     €100 @@ $135  ; сто євро придбано за $135 за лот
  assets:dollars

3. Вказати суми для всіх постів, використовуючи точно дві валюти, і дозволити hledger вивести ціну, що збалансовує операцію. Зауважте ефект порядку постів: ціна додається до першого посту, роблячи його €100 @@ $135, як у прикладі 2:

2009/1/1
  assets:euros     €100          ; сто євро придбано
  assets:dollars  $-135          ; за $135

Суми можуть бути перетворені на вартість під часу звітування за допомогою прапорця -B/--cost; це обговорюється більше в розділі Звіт про вартість.

Зауважте, що вартість зазвичай має бути позитивною сумою, хоча це не обов'язково. Це може бути трохи плутаним, див. обговорення в --infer-market-prices: ринкові ціни з транзакцій.

Твердження балансу

hledger підтримує твердження балансу Ledger-стилю у файлах журналу. Вони виглядають, наприклад, як = ПОТРІБНИЙ_БАЛАНС після суми посту. Наприклад, ось ми твердимо очікуваний баланс доларів на рахунках a та b після кожного посту:

2013/1/1
  a   $1 =  $1
  b      = $-1

2013/1/2
  a   $1 =  $2
  b  $-1 = $-2

Після читання файлу журналу, hledger перевірить усі твердження балансу і повідомить про помилку, якщо будь-яке з них не виконується. Твердження балансу можуть захистити вас від, наприклад, випадково порушити звірені баланси під часу очищення старих записів. Ви можете тимчасово вимкнути їх з прапорцем -I/--ignore-assertions, що може бути корисно для усунення неполадок або для читання файлів Ledger. (Зауважте: цей прапорець наразі не вимикає призначення балансу, описане нижче).

Твердження та впорядкування

hledger обчислює і перевіряє твердження балансу рахунку в порядку дат (а коли є кілька тверджень в той самий день, у порядку аналізу). Зауважте, що це відрізняється від Ledger, який перевіряє твердження завжди в порядку аналізу, ігноруючи дати.

Це означає в hledger, що ви можете вільно змінювати порядок операцій, постів або файлів, і твердження балансу зазвичай продовжуватимуть працювати. Виняток - коли ви змінюєте порядок кількох постів в той самий день, до того самого рахунку, які мають твердження балансу; тоді їх, ймовірно, доведеться оновити.

Твердження та кілька файлів

Якщо рахунок має операції, що з'являються в кількох файлах, твердження балансу все ще можуть працювати - але лише якщо ті файли є частиною ієрархії, зробленої директивами include.

Якщо ті самі файли вказані з двома опціями -f у командному рядку, твердження в другому не побачать баланси з першого.

Щоб обійти це, упорядкуйте ваші файли в ієрархію з include. Або, ви могли б об'єднати файли тимчасово і обробити їх як один великий файл.

Чому це працює таким чином? Можливо, це пов'язано з метою hledger забезпечити стабільні, передбачувані звіти. Ієрархія файлів вважається "постійною", частиною ваших даних, тоді як порядок аргументів командного рядка - ні. Ми не хочемо, щоб тимчасові зміни могли змінити значення даних. Наприклад, було б розчаруванням, якби завтра всі ваші твердження балансу зламалися, бо ви написали аргументи командного рядка в іншому порядку. (Обговорення вітається.)

Твердження та вартості

Твердження балансу ігнорують вартості і зазвичай мають бути записані без них:

2019/1/1
  (a)     $1 @ €1 = $1

Ми дозволяємо вартості бути записаними в сумах тверджень балансу, однак, і print показує їх, але вони не впливають на те, чи твердження виконується чи ні. Це для зворотної сумісності (hledger's close команда використовувала генерувати твердження балансу з вартостями), і тому призначення балансу використовують вартості (див. нижче).

Твердження та товари

Балансові твердження, описані вище, є "твердженнями балансу одного товару": вони твердять і перевіряють баланс в одному товарі, ігноруючи будь-які інші, що можуть бути присутні. Це так само, як балансові твердження в Ledger.

Якщо рахунок містить кілька товарів, ви можете твердити їхні баланси, записавши кілька постів з твердженнями балансу, по одному для кожного товару:

2013/1/1
  usd   $-1
  eur   €-1
  both

2013/1/2
  both    0 = $1
  both    0 = €1

У hledger ви можете зробити "твердження балансу єдиного товару" (зауважте множину) - тобто, твердити, що рахунок містить два або більше зазначених товарів і нічого іншого. Це можна зробити шляхом

1. ізоляції кожного товару в окремий пост, як описано вище
2. і також твердження, що немає товарів у батьківському рахунку самому собою:

2013/1/1
  usd       $-1
  eur       €-1
  both        0 == 0   ; нічого в рукаві
  both:usd   $1 == $1  ; долар тут
  both:eur   €1 == €1  ; євро там

Твердження та підрозділи

Всі балансові твердження вище (і = і ==) є "твердженнями балансу, виключними для підрозділів"; вони ігнорують будь-які баланси, що існують у глибших підрозділах.

У hledger ви можете зробити "твердження балансу, включені для підрозділів" додаванням зірочки після знаку дорівнює (=* або ==*):

2019/1/1
  equity:start
  assets:checking  $10
  assets:savings   $10
  assets            $0 ==* $20  ; активи + підрозділи містять $20 і нічого іншого

Твердження та статус

Балансові твердження завжди враховують пости всіх статусів (непозначені, очікувані або очищені); вони не впливають на прапорці -U/--unmarked / -P/--pending / -C/--cleared або запит status:.

Твердження та віртуальні пости

Балансові твердження завжди враховують як реальні, так і віртуальні пости; вони не впливають на прапорець --real/-R або запит real:.

Твердження та автоматичні пости

Балансові твердження впливають на прапорець --auto, який генерує автоматичні пости, що може змінювати баланси рахунків. Через те, що автоматичні пости є необов'язковими в hledger, рахунки, на які вони впливають, ефективно мають два баланси. Але балансові твердження можуть тестувати лише один або інший з цих. Тож, щоб уникнути хитрих тверджень, або:

• твердити баланс, обчислений з --auto, і завжди використовувати --auto з цим файлом
• або твердити баланс, обчислений без --auto, і ніколи не використовувати --auto з цим файлом
• або уникати балансових тверджень на рахунках, на які впливають автоматичні пости (або уникати автоматичних постів взагалі).

Твердження та точність

Балансові твердження порівнюють точно обчислені суми, які не завжди те, що показано у звітах. Наприклад, директива товару може обмежити точність відображення, але це не вплине на балансові твердження. Повідомлення про помилки балансових тверджень показують точні суми.

Твердження та hledger add

Балансові твердження можуть бути включені в суми, надані в add. Всі типи тверджень підтримуються, і твердження можуть використовуватися як у звичайному файлі журналу.

Усі операції, не тільки ті, що мають явне твердження, перевіряються на відповідність існуючим твердженням у журналі. Це означає, що додана операція може не пройти, навіть якщо її твердження правильні на момент дати операції.

Якщо ця перевірка тверджень не потрібна, її можна вимкнути з -I.

Однак, призначення балансу наразі не підтримуються.

Коментарі постів

Текст після ;, в кінці рядка посту, і/або на рядках з відступом безпосередньо під ним, утворюють коментарі для цього посту. Вони відтворюються командою print, але інакше ігноруються, окрім випадків, коли вони можуть містити теги, які не ігноруються.

2012-01-01
    expenses   1  ; коментар для посту 1
    assets
    ; коментар для посту 2
    ; другий коментарний рядок для посту 2

Балансування операцій

Як саме hledger вирішує, чи операція збалансована? Особливо коли вона включає вартості, які часто неточні через повторювані десяткові знаки або неточні дані від фінансових установ? У кожному товарі hledger підсумовує пости операції, після перетворення будь-яких з вартістю; потім перевіряє, чи ця сума дорівнює нулю, коли округлена до відповідної кількості десяткових цифр - яку ми називаємо точністю балансування.

Оскільки версії 1.50, hledger виводить точність балансування в кожній операції з постів у цій операції (як у Ledger). Тобто, коли перевіряється баланс товару A, використовується найвища десяткова точність, побачена для A у записі журналу (окрім сум вартості). Це робить балансування операцій надійним; будь-які дисбаланси мають бути видимо враховані в записі журналу, точність відображення може бути вільно збільшена з -c, і сумісність з журналами Ledger і Beancount хороша.

Зауважте, що hledger версій до 1.50 працювали інакше: вони дозволяли точність відображення перевизначити точність балансування. Це маскувало маленькі дисбаланси і спричиняло крихкість (див. issue #2402). Як результат, деякі записи журналу (або правила CSV) , що працювали з hledger <1.50, тепер відхиляються з помилкою "незбалансована операція". Якщо ви зіткнетеся з цією проблемою, її легко виправити:

• Ви можете відновити стару поведінку, додавши --txn-balancing=old до команди або до вашого файлу ~/.hledger.conf. Це дозволяє вам продовжувати використовувати старі журнали без змін, хоча без вищезгаданих переваг.
• Або ви можете виправити проблемні записи (рекомендовано). Є три способи, використовуйте, який здається найкращим:
  1. зробити суми вартості точнішими (додати більше/кращих десяткових цифр)
  2. або зробити суми без вартості менш точними (видалити непотрібні десяткові цифри, що підвищують точність)
  3. або додати пост, щоб поглинути дисбаланс (наприклад, "expenses:rounding". Зауважте, що один пост може опускати суму; це зручно тут.)

Теги

Теги - це спосіб додавання додаткових міток або полів даних до операцій, постів або рахунків, які ви можете зіставляти з запитом tag: у звітах. (Див. запити нижче.)

Тег - це одне слово або слово з дефісом, відразу після якого йде двокрапка, записане в коментарі. (Так, зберігання даних у коментарях трохи дивне.) Ось операція з тегом:

2025-01-01 groceries        ; some-tag:
    assets:checking
    expenses:food       $1

Тег може мати значення, один рядок тексту після двокрапки. Значення тегів не можуть містити нові рядки.:

2025-01-01 groceries        ; tag1: this is tag1's value

Кілька тегів можна розділити комою. Значення тегів не можуть містити коми.:

2025-01-01 groceries        ; tag1:value 1, tag2:value 2, comment text

Тег може мати кілька значень:

2025-01-01 groceries        ; tag1:value 1, tag1:value 2

Ви можете записати кожен тег на власному рядку, якщо вам це подобається (але вони не можуть містити коми):

2025-01-01 groceries
    ; tag1: value 1
    ; tag2: value 2

Теги можна прикріпити до окремих постів, а не до загальної операції:

2025-01-01 rent
    assets:checking
    expenses:rent       $1000  ; postingtag:

Теги можна прикріпити до рахунків, у їхній директиві рахунку:

account assets:checking    ; acct-number: 123-45-6789

Поширення тегів

На додачу до того, до чого вони прикріплені, теги також впливають на пов'язані дані кількома способами, дозволяючи більш потужні запити:

1. Рахунки -> пости. Пости успадковують теги своїх рахунків.
2. Операції -> пости. Пости успадковують теги своєї операції.
3. Пости -> операції. Операції також отримують теги своїх постів.

Тож, коли ви використовуєте запит tag:, щоб зіставити цілі операції, окремі пости або рахунки, добре знати, як теги поводяться. Ось приклад, що показує всі три види поширення:

account assets:checking
account expenses:food           ; atag:

2025-01-01 groceries            ; ttag:
    assets:checking             ; p1tag:
    expenses:food           $1  ; p2tag:

Відображення тегів

Ви можете використовувати команду tags, щоб перерахувати назви тегів або значення.

Команда print також показує теги.

Ви можете використовувати --pivot, щоб відображати значення тегів в інших звітах, різними способами (наприклад, додані до назв рахунків, як псевдопідрозділи).

Коли використовувати теги?

Теги надають більше вимірів категоризації, доповнюючи рахунки та описи операцій. Коли використовувати кожен з цих - це трохи справа смаку. Рахунки мають найбільше вбудовану підтримку, і запити з регулярними виразами на описах також доволі потужні. Тож, можливо, вам не потрібні теги взагалі. Але якщо ви хочете відстежувати кілька перетинних категорій, вони можуть бути гарним варіантом. Наприклад, ви могли б тегувати операції подорожей з trip: YEAR:PLACE, не порушуючи ваші звичайні категорії рахунків.

Назви тегів

Що дозволено в назві тегу? Більшість символів, окрім пробілів. Наприклад, 😀: є дійсним тегом.

Для додаткової перевірки помилок, ви можете оголосити дійсні назви тегів з директивою tag, а потім забезпечити ці з командою check. Але зауважте, що теги виявляються досить вільно наразі, іноді там, де ви не хотіли їх. Наприклад, коментар як ; див. https://foo.com додає тег https.

Є кілька назв тегів, які мають особливе значення для hledger. Вони пояснюються в інших місцях, але ось швидке посилання:

 type                   -- оголошує тип рахунку
 date                   -- перевизначає дату посту
 date2                  -- перевизначає вторинну дату посту
 assert                 -- з'являється на операціях, згенерованих close --assert
 retain                 -- з'являється на операціях, згенерованих close --retain
 start                  -- з'являється на операціях, згенерованих close --migrate/--close/--open/--assign
 t                      -- з'являється на постах, згенерованих з timedot літер

 generated-transaction  -- з'являється на операціях, згенерованих правилом періодичності
 modified-transaction   -- з'являється на операціях, до яких додано автоматичні пости
 generated-posting      -- з'являється на згенерованих постах
 cost-posting           -- з'являється на постах, які мають (або могли б мати) вартість,
                           і які мають еквівалентні пости перетворення в операції
 conversion-posting     -- з'являється на постах, які до V/Conversion рахунку
                           і які мають еквівалентний пост вартості в операції

Друга група вище (generated-transaction тощо) зазвичай прихована, з префіксом _ доданим. Це означає, що print за замовчуванням не показує їх; але ви все ще можете використовувати їх у запитах. Ви можете додати прапорець --verbose-tags, щоб зробити їх видимими, що може бути корисно для усунення неполадок.

Директиви

Окрім операцій, є ще дещо, що ви можете покласти у файл journal: директиви. Це оголошення, що починаються з ключового слова, які змінюють поведінку hledger. Деякі директиви можуть мати більш специфічні піддирективи, з відступом під ними. Директиви hledger схожі на директиви Ledger у багатьох випадках, але є також багато відмінностей. Директиви не потрібні, але можуть бути корисними. Ось основні директиви:

Директиви та кілька файлів

Директиви відрізняються своїм охопленням, тобто які записи журналу та які файли вхідних даних вони впливають. Найчастіше директива вплине на наступні записи та включені файли, якщо є, до кінця поточного файлу - і нічого далі. Ви можете вважати це незручним! Наприклад, директиви alias не впливають на батьківські або сусідні файли. Але зазвичай є обхідні шляхи; наприклад, покладіть директиви alias у ваш найвищий файл, перед включенням інших файлів.

Обмеження, хоча на початку може бути дратівним, має добру причину; воно дозволяє звітам бути стабільними та детермінованими, незалежно від порядку вхідних даних. Без цього, звіти могли б показувати різні числа залежно від порядку опцій -f, або позицій директив include у ваших файлах.

Ефекти директив

Ось усі директиви hledger з їх ефектами та охопленням - дев'ять основних директив, плюс чотири інші, які ми вважаємо необов'язковими:

Директива account

Директиви account можна використовувати для оголошення рахунків (тобто місць, куди передаються та звідки передаються суми). Хоча це не обов'язково, ці оголошення можуть забезпечити кілька переваг:

• Вони можуть документувати ваш намічений план рахунків, забезпечуючи довідку.
• Вони можуть зберігати додаткову інформацію про рахунок як коментарі, або як теги, які можна використовувати для фільтрації або повороту звітів.
• Вони можуть обмежити, які рахунки можуть бути використані для постів операцій, наприклад, у суворому режимі, що допомагає запобігти помилкам.
• Вони впливають на порядок відображення рахунків у звітах, дозволяючи неалфавітне сортування (наприклад, Доходи з'являються вище Витрат).
• Вони допомагають hledger знати ваші типи рахунків (активи, зобов'язки, капітал, доходи, витрати), що дозволяє звіти, як balancesheet та incomestatement.
• Вони допомагають з автодоповненням назв рахунків (у hledger add, hledger-web, hledger-iadd, ledger-mode тощо.)

Вони записуються як слово account, за яким йде назва рахунку hledger-стилю. Наприклад:

account assets:bank:checking

Піддирективи, схожі на Ledger, з відступом також приймаються, але ігноруються:

account assets:bank:checking
  format subdirective  ; наразі ігнорується

Коментарі рахунку

Текст після двох або більше пробілів і ; у кінці рядка директиви рахунку, і/або після ; на рядках з відступом безпосередньо під нею, утворюють коментарі для цього рахунку. Вони ігноруються, окрім випадків, коли вони можуть містити теги, які не ігноруються.

Необхідність двох пробілів для коментарів рахунку тієї самої лінії пояснюється тим, що ; дозволено в назвах рахунків.

account assets:bank:checking    ; коментар того самого рядка, принаймні 2 пробіли перед крапкою з комою
  ; коментар наступного рядка
  ; деякі теги - type:A, acctnum:12345

Перевірка помилок рахунку

За замовчуванням, рахунки не потрібно оголошувати; вони виникають, коли пост посилається на них. Це зручно, але це означає, що hledger не може попередити вас, коли ви помилково напишете назву рахунку в журналі. Зазвичай ви дізнаєтеся про цю помилку пізніше, як додатковий рахунок у звітах балансу, або неправильний баланс при звірці.

У суворому режимі, увімкненому з прапорцем -s/--strict, або коли ви запускаєте hledger check accounts, hledger повідомить про помилку, якщо будь-яка операція використовує назву рахунку, що не була оголошена директивою account. Деякі нотатки:

• Оголошення чутливе до регістру; операції мають використовувати правильну назву рахунку з правильним регістром.
• Область дії директиви account є "весь файл і нижче" (див. директиви). Це означає, що вона впливає на всі записи поточного файлу та будь-які файли, що включаються, але не на батьківські або сусідні файли. Позиція директив account у файлі не має значення, хоча зазвичай їх кладуть зверху.
• Рахунки можна оголошувати лише у файлах journal, але вони впливатимуть на включені файли всіх типів.
• Наразі неможливо оголосити "всі можливі підрозділи" з узагальнювальним символом; кожен рахунок, на який здійснюється пост, має бути оголошений.
• Якщо ви використовуєте виведення еквівалентності, вам також знадобляться оголошення для назв рахунків, які він генерує.

Порядок відображення рахунків

Директиви account також змушують hledger відображати рахунки в певному порядку, а не просто за алфавітом. Наприклад, ось традиційний порядок для рахунків верхнього рівня:

account assets
account liabilities
account equity
account revenues
account expenses

Тепер hledger відображає їх у цьому порядку:

$ hledger accounts
assets
liabilities
equity
revenues
expenses

Якщо є неоголошені рахунки, вони відображатимуться останніми, в алфавітному порядку.

Сортування виконується в межах кожної групи рахунків-сусідів, на кожному рівні дерева рахунків. Наприклад, оголошення типу account parent:child впливає на позицію child серед його сусідів.

Зауважте, що це не впливає на позицію parent; для цього потрібно оголошення account parent.

Сусідні рахунки завжди відображаються разом; hledger не відображатиме x:y між a:b та a:c.

Директива account одночасно оголошує рахунок як дійсну ціль для посту та оголошує його порядок відображення; ви не можете легко зробити одне без іншого.

Типи рахунків

hledger знає, що у бухгалтерії є три основні типи рахунків:

і два більше, що представляють зміни в цих:

hledger також використовує кілька підтипів:

Як зручність, hledger виявлятиме ці типи автоматично з англійських назв рахунків. Але краще оголошувати їх явно, додавши тег type: у директиви рахунків. Значенням тегу може бути будь-який з типів або однолітерних скорочень вище.

Ось типовий набір оголошень типів рахунків. Підрозділи успадковують тип батьківського рахунку, або можуть перевизначити його:

account assets             ; type: A
account liabilities        ; type: L
account equity             ; type: E
account revenues           ; type: R
account expenses           ; type: X

account assets:bank        ; type: C
account assets:cash        ; type: C

account equity:conversion  ; type: V

Це дозволяє легкі звіти balancesheet, balancesheetequity, cashflow та incomestatement, і запити за type:.

Поради:

• Ви можете перерахувати рахунки та їхні типи для усунення неполадок:

$ hledger accounts --types [ACCTPAT] [type:TYPECODES] [-DEPTH] [--locations]

• Добре б мати оголошений принаймні один рахунок для кожного типу рахунку. Мати деякі типи оголошеними та деякі виведеними може порушити певні звіти.
• Правила для виведення типів з назв рахунків такі (використовуючи регулярні вирази). Якщо вони не працюють для вас, просто ігноруйте їх і оголошуйте свої типи з тегами type:.

Якщо назва рахунку містить цей регулярний вираз без урахування регістру | його тип
--------------------------------------------------------------------|-------------
^assets?(:.+)?:(cash\|bank\|che(ck\|que?)(ing)?\|savings?)(:|$) | Cash
^assets?(:|$)                                                       | Asset
^(debts?\|liabilit(y\|ies))(:|$)                                      | Liability
^equity:(trad(e\|ing)\|conversion)s?(:|$)                             | Conversion
^equity(:|$)                                                        | Equity
^(income\|revenue)s?(:|$)                                            | Revenue
^expenses?(:|$)                                                     | Expense

• Як згадувалося вище, підрозділи успадковують тип від їхніх батьківських рахунків. Точніше, тип рахунку вирішується першим з цих, що існує:
  1. Оголошення type: для цього рахунку.
  2. Оголошення type: у батьківських рахунках вище, віддаючи перевагу найближчому.
  3. Тип рахунку, виведений з назви цього рахунку.
  4. Тип рахунку, виведений з назви батьківського рахунку, віддаючи перевагу найближчому.
  5. В іншому випадку, він не матиме типу.
• Псевдоніми рахунків можуть порушити типи рахунків.

Директива alias

Ви можете визначити правила псевдонімів рахунків, які переписують ваші назви рахунків або їх частини перед генерацією звітів. Це може бути корисно для:

• розширення коротких назв рахунків до їхньої повної форми, що дозволяє легше введення даних і менш багатослівний журнал
• адаптації старих журналів до вашого поточного плану рахунків
• експериментування з новими організаціями рахунків, як нова ієрархія
• об'єднання двох рахунків в один, наприклад, щоб побачити їхню суму або різницю в одному рядку
• налаштування звітів

Псевдоніми рахунків також переписують назви рахунків у директивах account. Вони не впливають на назви рахунків, що вводяться через hledger add або hledger-web.

Псевдоніми рахунків дуже потужні. Вони зазвичай легко використовуються правильно, але ви можете також генерувати недійсні назви рахунків з ними; більше про це нижче.

Див. також Переписати назви рахунків.

Основні псевдоніми

Щоб встановити псевдонім рахунку, використовуйте директиву alias у вашому файлі журналу. Це впливає на всі наступні записи журналу в поточному файлі або його включених файлах (але зауважте: не на сусідні або батьківські файли). Пробіли навколо = необов'язкові:

alias OLD = NEW

Або, ви можете використовувати опцію --alias 'OLD=NEW' у командному рядку. Це впливає на всі записи. Це корисно для експериментування з псевдонімами інтерактивно.

OLD та NEW - чутливі до регістру повні назви рахунків. hledger замінить будь-яке входження старої назви рахунку новою. Підрозділи також впливають. Наприклад:

alias checking = assets:bank:wells fargo:checking
; переписує "checking" на "assets:bank:wells fargo:checking", або "checking:a" на "assets:bank:wells fargo:checking:a"

Регулярні псевдоніми

Є також більш потужний варіант, що використовує регулярний вираз, позначений обведенням зразка в прямі слеші.

(Це єдине місце, де hledger вимагає прямі слеші навколо регулярного виразу.)

Наприклад:

alias /REGEX/ = REPLACEMENT

або:

$ hledger --alias '/REGEX/=REPLACEMENT' ...

Будь-яка частина назви рахунку, що відповідає REGEX, буде замінена на REPLACEMENT. REGEX нечутливий до регістру як зазвичай.

Якщо вам потрібно відповідати прямому слешу, екрануйте його зворотним слешем, наприклад /\/=:/.

Якщо REGEX містить дужки для груп збігу, вони можуть бути посилані звичайним зворотним слешем і номером у REPLACEMENT:

alias /^(.+):bank:([^:]+):(.*)/ = \1:\2 \3
; переписує "assets:bank:wells fargo:checking" на "assets:wells fargo checking"

REPLACEMENT продовжується до кінця рядка (або на командному рядку, до кінця аргументу опції), тож він може містити кінцеві пробіли.

Поєднання псевдонімів

Ви можете визначити стільки псевдонімів, скільки хочете, використовуючи директиви журналу та/або опції командного рядка.

Рекурсивні псевдоніми - де назва рахунку переписується однією псевдонімною, потім іншою псевдонімною, і так далі - дозволені. Кожен псевдонім бачить ефект попередньо застосованих псевдонімів.

У таких випадках важливо знати, які псевдоніми будуть застосовані і в якому порядку. Для (кожного назви рахунку в) кожного запису журналу, ми застосовуємо:

1. Директиви alias, що передують запису журналу, найбільш нещодавно проаналізовані першими (тобто, читаючи вгору від запису журналу, знизу вгору)
2. Опції --alias, в порядку, в якому вони з'явилися в командному рядку (зліва направо).

Іншими словами, для (назви рахунку в) даного запису журналу:

• найближче оголошення псевдоніму перед/вище запису застосовується першим
• наступний псевдонім перед/вище того буде застосований наступним, і так далі
• псевдоніми, визначені після/нижче запису, не впливають на нього.

Це дає ближнім псевдонімам перевагу над віддаленими, і допомагає забезпечити семантичну стабільність - псевдоніми працюватимуть однаково незалежно від того, які файли читаються і в якому порядку.

У разі проблем, додавання --debug=6 до командного рядка покаже, які псевдоніми застосовуються коли.

Псевдоніми та кілька файлів

Як пояснюється в Директиви та кілька файлів, директиви alias не впливають на батьківські або сусідні файли. Наприклад, у цій команді,

hledger -f a.aliases -f b.journal

псевдоніми рахунків, визначені в a.aliases, не впливатимуть на b.journal. Включення псевдонімів також не працює:

include a.aliases

2023-01-01  ; не впливає a.aliases
  foo  1
  bar

Це означає, що псевдоніми рахунків зазвичай мають бути оголошені на початку вашого найвищого файлу, ось так:

alias foo=Foo
alias bar=Bar

2023-01-01  ; впливає псевдоніми вище
  foo  1
  bar

include c.journal  ; також впливає

Директива end aliases

Ви можете очистити (забути) всі поточні визначені псевдоніми (побачені в журналі до цього часу, або визначені в командному рядку) з цією директивою:

end aliases

Псевдоніми можуть генерувати погані назви рахунків

Майте на увазі, що псевдоніми рахунків можуть створювати неправильні назви рахунків, що могло б спричинити плутані звіти або недійсний вивід print. Наприклад, ви могли б стерти всі назви рахунків:

2021-01-01
  a:aa     1
  b

$ hledger print --alias '/.*/='
2021-01-01
                   1

Вищезазначений вивід print не є дійсним журналом. Або ви могли б вставити неправильну подвійну пробіл, що спричинить print вивід, який при повторному аналізі дав би інший журнал:

2021-01-01
  old    1
  other

$ hledger print --alias old="new  USD" \| hledger -f- print
2021-01-01
    new             USD 1
    other

Псевдоніми та типи рахунків

Якщо рахунок з оголошенням типу (див. Оголошення рахунків > Типи рахунків) перейменовується псевдонімом, зазвичай тип рахунку залишається в дії.

Однак, перейменування способом, що змінює дерево рахунків (наприклад, перейменування батьківських рахунків, але не їхніх дітей, або навпаки), могло б запобігти успадкуванню типу дітьми.

По-друге, якщо тип рахунку виводиться з його назви, перейменування псевдонімом могло б запобігти або змінити це.

Якщо ви використовуєте псевдоніми рахунків і запит type: не зіставляє рахунки, як ви очікуєте, спробуйте усунення неполадок з командою accounts, наприклад:

$ hledger accounts --types -1 --alias assets=bassetts

Директива commodity

Директива commodity виконує кілька функцій:

1. Вона оголошує, які символи товарів можуть використовуватися в журналі, забезпечуючи корисну перевірку помилок з суворим режимом або командою перевірки. Див. Перевірка помилок товарів нижче.

2. Вона оголошує, як всі суми в цьому товарі мають відображатися, наприклад, скільки десяткових знаків показувати. Див. Стиль відображення товарів вище.

3. (Якщо директива decimal-mark не діє): Вона встановлює десятковий розділювач, який очікується (крапка або кома) при аналізі сум у цьому товарі, у цьому файлі та файлах, що включаються, від директиви до кінця поточного файлу. Див. Десяткові розділювачі вище.

4. Вона оголошує точність, з якою мають порівнюватися суми цього товару при перевірці збалансованості операцій, будь-де в цьому файлі та файлах, що включаються, до кінця поточного файлу.

Оголошення товарів вирішує кілька загальних проблем аналізу/відображення, тож ми рекомендуємо це.

Зауважте, що ефекти 3 і 4 вище закінчуються в кінці файлу директиви, і не впливатимуть на сусідні або батьківські файли. Тож якщо ви покладаєтеся на них (особливо 4) і використовуєте кілька файлів, розміщення ваших директив товарів у батьківському файлі верхнього рівня може бути важливим. Або, зберігайте ваші десяткові розділювачі неоднозначними і ваші записи збалансованими та точними.

Опускання символу товару встановить стиль відображення лише для товару без символу, а не для всіх товарів.

Стилі товарів можна перевизначити опцією командного рядка -c/--commodity-style.

(Пов'язане: #793)

Синтаксис директиви commodity

Директива commodity зазвичай є словом commodity, за яким йде зразок суми (і опціонально коментар). Лише символ суми та формат числа мають значення. Наприклад:

commodity $1000.00
commodity 1.000,00 EUR
commodity 1 000 000.0000   ; товар без символу

Товари не мають тегів (теги в коментарі будуть проігноровані).

Директива commodity зразка суми завжди має включати десятковий розділювач (крапка або кома) (це правило допомагає усунути неоднозначність десяткових розділювачів і груп цифр). Якщо ви не хочете показувати будь-які десяткові цифри, напишіть десятковий розділювач в кінці:

commodity 1000. AAAA       ; показувати AAAA без десяткових

Директиви commodity, що містять пробіли, цифри або пунктуацію, мають бути в подвійних лапках, як зазвичай:

commodity 1.0000 "AAAA 2023"

Директиви commodity зазвичай включають зразок суми, але можуть оголошувати лише символ (тобто лише функція 1 вище):

commodity $
commodity INR
commodity "AAAA 2023"
commodity ""               ; товар без символу

Директиви commodity можуть бути також записані з вкладеною піддирективою format, як у Ledger. Символ повторюється і має бути однаковим у обох місцях. Інші піддирективи наразі ігноруються:

; відображати індійські рупії з назвою валюти ліворуч,
; тисячі, лаки і крори розділені комами,
; крапка як десятковий розділювач і два десяткових знаки.
commodity INR
  format INR 1,00,00,000.00
  an unsupported subdirective  ; ігнорується hledger

Перевірка помилок товарів

У суворому режимі (-s/--strict) (або коли ви запускаєте hledger check commodities) hledger повідомить про помилку, якщо використовується неоголошений символ товару. (З однією винятком: нульові суми завжди дозволені мати без символу товару.) Це працює як перевірка помилок рахунку (описано вище).

Директива decimal-mark

Ви можете використовувати директиву decimal-mark - зазвичай одну на файл, у верхній частині файлу - щоб оголосити, який символ представляє десятковий розділювач при аналізі сум у цьому файлі. Він може виглядати як

decimal-mark .

або

decimal-mark ,

Це запобігає будь-якій неоднозначності при аналізі чисел у файлі, тож ми рекомендуємо це, особливо якщо файл містить позначки груп цифр (наприклад, тисячні розділювачі).

Директива include

Ви можете витягнути вміст додаткових файлів, написавши директиву include, ось так:

include SOMEFILE

Це має той же ефект, що і якби вміст SOMEFILE був вбудований у цю точку. (З будь-якими директивами include в SOMEFILE, що обробляються аналогічно, рекурсивно.)

Тільки файли журналу можуть включати інші файли. Вони можуть включати файли журналу, timeclock або timedot, але не CSV файли.

Якщо шлях до файлу починається з тильди, це означає ваш домашній каталог: include ~/main.journal.

Якщо він починається зі слеша, це абсолютний шлях: include /home/user/main.journal. В іншому випадку це відносно до теки файлу, що включає: include ../finances/main.journal.

Також, шлях може мати префікс формату файлу, щоб примусово встановити певний формат файлу, перевизначаючи розширення файлу(ів) (як описано в Форматах даних): include timedot:notes/2023.md.

Шлях може містити глоб-шаблони, щоб відповідати кільком файлам. Глоби hledger схожі на zsh: ? щоб відповідати будь-якому символу; [a-z] щоб відповідати будь-якому символу в діапазоні; * щоб відповідати нулю або більше символів, що не є розділювачем шляху (як /); ** щоб відповідати нулю або більше підтек або нулю або більше символів на початку імені файлу; тощо. Для зручності, include завжди виключає поточний файл. Тож, ви можете зробити

• include *.journal щоб включити всі інші файли журналу в поточній теці (окрім прихованих файлів)
• include **.journal щоб включити всі інші файли журналу в цій теці та нижче (окрім прихованих файлів і верхніх прихованих тек)
• include timelogs/2????.timedot щоб включити всі timedot файли з назвами, схожими на рік.

Зауважте, що * і ** зазвичай не відповідають прихованим файлам або прихованим текам, з одним винятком: ** все ж таки шукає в не верхніх прихованих теках. Якщо це спричиняє проблеми, зробіть ваш глоб-шаблон більш специфічним (наприклад, **.journal замість **).

Якщо ви використовуєте багато, або глибоко вкладені файли include, і маєте помилку, яку важко визначити: гарна команда для усунення неполадок - hledger files --debug=6 (або 7).

Директива P

Директива P оголошує ринкову ціну, яка є курсом обміну між двома товарами в певну дату. Це дозволяє звіти про вартість перетворювати суми одного товару на їхню вартість в іншому товарі, з цієї дати і після неї. Ці ціни часто отримуються з біржі акцій, біржі криптовалют або ринку обміну валют.

Формат:

P DATE COMMODITY1SYMBOL COMMODITY2AMOUNT

DATE - проста дата, COMMODITY1SYMBOL - символ товару, що цінується, і COMMODITY2AMOUNT - сума (символ і кількість) товару 2, за яку коштує одна одиниця товару 1 в цю дату. Приклади:

# один євро коштував $1.35 з 2009-01-01:
P 2009-01-01 € $1.35

# і $1.40 з 2010-01-01:
P 2010-01-01 € $1.40

Прапорці -V, -X і --value використовують ці ринкові ціни, щоб показати вартість сум в іншому товарі. Див. Звіт про вартість.

[automated-postings]

Директива payee

payee PAYEE NAME

Ця директива може використовуватися для оголошення обмеженого набору одержувачів, які можуть з'являтися в описах операцій. Перевірка "payees" повідомить про помилку, якщо будь-яка операція посилається на одержувача, що не був оголошений. Наприклад:

payee Whole Foods    ; коментар

Одержувачі не мають тегів (теги в коментарі будуть проігноровані).

Щоб оголосити порожнє ім'я одержувача, використовуйте "".

payee ""

Піддирективи в стилі Ledger, якщо є, наразі ігноруються.

Директива tag

tag TAGNAME

Ця директива може використовуватися для оголошення обмеженого набору дозволених назв тегів у тегах. TAGNAME має бути дійсною назвою тегу (без пробілів). Наприклад:

tag  item-id

Будь-які вкладені піддирективи наразі ігноруються.

Перевірка "tags" повідомить про помилку, якщо використовується неоголошена назва тегу. Це досить легко випадково створити тег через нормальне використання двокрапок у коментарях; якщо ви хочете запобігти цьому, ви можете оголосити і перевірити ваші теги.

Періодичні операції

Директива ~ оголошує "періодичне правило", яке генерує тимчасові додаткові операції, зазвичай повторювані з певним інтервалом, коли hledger запускається з прапорцем --forecast. Ці "прогнозовані операції" корисні для прогнозування майбутньої активності. Вони існують лише протягом звіту і лише коли --forecast використовується; вони не зберігаються у файлі журналу hledger.

Періодичні правила також мають друге використання: з прапорцем --budget вони встановлюють бюджетні цілі для бюджетування.

Періодичні правила можуть бути трохи складними, тож перед використанням прочитайте цілий цей розділ, або принаймні наступні поради:

1. Дві пробіли, випадково додані або пропущені, спричинять вам проблеми - прочитайте про це нижче.
2. Для усунення неполадок, покажіть згенеровані операції з hledger print --forecast tag:generated або hledger register --forecast tag:generated.
3. Прогнозовані операції почнуться лише після останньої операції без прогнозу.
4. Прогнозовані операції закінчаться через 6 місяців від сьогодні, за замовчуванням. Див. точні правила початку/кінця нижче.
5. Вирази періоду можуть бути складними. Їхня документація потребує покращення, але варто вивчити.
6. Деякі вирази періоду з повторюваним інтервалом мають починатися на природній межі цього інтервалу. Наприклад, у weekly from DATE, DATE має бути понеділком. ~ weekly from 2019/10/1 (вівторок) дасть помилку.
7. Інші вирази періоду з інтервалом автоматично розширюються, щоб охопити цілий номер цього інтервалу. (Це зроблено для покращення звітів, але це також впливає на періодичні операції. Так, це трохи неузгоджене з вищезгаданим.) Наприклад: ~ every 10th day of month from 2023/01, що еквівалентно ~ every 10th day of month from 2023/01/01, буде скориговано, щоб починатися 2019/12/10.

Синтаксис періодичного правила

Періодичне правило операції виглядає як нормальний запис журналу, де дата замінена на ~ (тильда), за якою йде вираз періоду (мнемоніка: ~ схожа на синусоїду, що повторюється.):

# щомісяця 1-го числа
~ monthly
    expenses:rent          $2000
    assets:bank:checking

# щомісяця 15-го числа в першому кварталі 2023:
~ monthly from 2023-04-15 to 2023-06-16
    expenses:utilities          $400
    assets:bank:checking

Вираз періоду має той самий синтаксис, що і для визначення багатоперіодних звітів, просто інтерпретується інакше; там він вказує звітні періоди; тут він вказує дати повторення (початкові дати періодів).

Періодичні правила та відносні дати

Часткові або відносні дати (як 12/31, 25, tomorrow, last week, next quarter) зазвичай не рекомендовані в періодичних правилах, оскільки результати змінюватимуться з плином часу. Якщо використовуються, вони будуть інтерпретовані відносно, за перевагою:

1. першого дня року за замовчуванням, вказаного останньою директивою Y
2. або дати, вказаної з --today
3. або дати, коли ви запускаєте звіт.

Вони не будуть впливати на дати періоду звіту або періоду прогнозу.

Дві пробіли між виразом періоду та описом!

Якщо вираз періоду супроводжується описом операції, між ними має бути два або більше пробіли. Це допомагає hledger знати, де вираз періоду закінчується, щоб описи не випадково змінювали їхнє значення, як у цьому прикладі:

; 2 або більше пробілів потрібно тут, щоб період не був зрозумілий як "every 2 months in 2023"
;               ||
;               vv
~ every 2 months  in 2023, we will review
    assets:bank:checking   $1500
    income:acme inc

Тож,

• Пишіть два пробіли між вашим виразом періоду та описом операції, якщо є.
• Не пишіть випадково два пробіли посередині вашого виразу періоду.

Автоматичні пости

Директива = оголошує "правило автоматичного посту", яке додає додаткові пости до існуючих операцій. (Пам'ятайте, пости - це назви рахунків і суми під датою та описом операції.)

У журналі, правило автоматичного посту виглядає досить як операція, але замість дати та опису воно має = (мнемоніка: "відповідає") і запит, ось так:

= QUERY
    ACCOUNT    AMOUNT
    ...

Запити як запити командного рядка; підрядкова назва рахунку найпоширеніша. Запити з термінами, що містять пробіли, мають бути в одинарних або подвійних лапках.

Кожне правило = працює ось як: коли hledger запускається з прапорцем --auto, будь-де в журналі, де QUERY відповідає посту, додаються пости правила до цієї операції, безпосередньо під відповідним постом. Зауважте, що ці згенеровані пости тимчасові, існують лише протягом звіту і лише коли використовується --auto; вони не зберігаються у файлі журналу hledger.

Суми можуть залежати від суми відповідного посту. Тож автоматичні пости можуть бути корисними для, наприклад, додавання постів податку зі стандартним відсотком. AMOUNT може бути:

• число без символу товару, як 2. До цього буде додано символ товару відповідного посту.
• нормальна сума з символом товару, як $2. Це буде використано як є.
• зірочка, за якою йде число, як *2. Це помножить суму відповідного посту (і загальну ціну, якщо є) на число.
• зірочка, за якою йде сума з символом товару, як *$2. Це помножить і також замінить символ товару цим новим.

Деякі приклади:

; щоразу, коли я купую їжу, запланувати доларову благодійність
= expenses:food
    (liabilities:charity)   $-1

; коли я купую подарунок, також вирахувати цю суму з бюджетного рахунку
= expenses:gifts
    assets:checking:gifts  *-1
    assets:checking         *1

2017/12/1
  expenses:food    $10
  assets:checking

2017/12/14
  expenses:gifts   $20
  assets:checking

$ hledger print --auto
2017-12-01
    expenses:food              $10
    assets:checking
    (liabilities:charity)      $-1

2017-12-14
    expenses:gifts             $20
    assets:checking
    assets:checking:gifts     -$20
    assets:checking            $20

Зауважте, що повністю покладатися на згенеровані дані, як ці, має деякі недоліки - менше переносимості, менше стійкості, менше аудитабельності іншими, і менше надійності (наприклад, ваші твердження балансу залежатимуть від того, чи використовуєте ви чи не використовуєте --auto). Альтернативою є використання автоматичних постів у "одноразовому" стилі - використовуйте їх, щоб допомогти побудувати складний запис журналу, перегляньте його з hledger print --auto, і тоді скопіюйте цей вивід у файл журналу, щоб зробити його постійним.

Автоматичні пости та кілька файлів

Правило автоматичного посту може впливати на будь-яку операцію в поточному файлі, або в будь-якому батьківському або дочірньому файлі. Зауважте, наразі воно не впливатиме на сусідні файли (коли використовується кілька -f/--file, див. #1212).

Автоматичні пости та дати

Дата посту (або вторинна дата) у відповідному пості, або (маючи перевагу) дата посту в самому правилі автоматичного посту, також буде використана в згенерованому пості.

Автоматичні пости та балансування операцій / виведення сум / твердження балансу

Наразі автоматичні пости додаються:

• після виведення відсутніх сум та перевірки збалансованості операцій, але
• перед перевіркою тверджень балансу.

Зауважте, це означає, що записи журналу мають бути збалансовані як до, так і після додавання автоматичних постів. Це змінилося в hledger 1.12+; див. #893 для фону.

Це також означає, що ви не можете мати більше одного автоматичного посту з відсутньою сумою, застосованого до певної операції, бо не вдасться вивести суми.

Теги автоматичних постів

Автоматичні пости матимуть деякі додаткові теги:

• generated-posting:= QUERY - показує, що це було згенеровано правилом автоматичного посту, і запит
• _generated-posting:= QUERY - прихований тег, що не з'являється у виводі hledger. Це можна використовувати, щоб зіставити пости, згенеровані "прямо зараз", а не згенеровані в минулому і збережені у журналі.

Також, будь-яка операція, що була змінена додаванням правил автоматичних постів, матиме ці теги додані:

• modified: - ця операція була змінена
• _modified: - прихований тег, що не з'являється в коментарі; ця операція була змінена "прямо зараз".

Автоматичні пости лише на прогнозовані операції

Порада: ви можете зробити автоматичні пости, що застосовуються лише до прогнозованих операцій, але не до записаних операцій, додавши tag:_generated-transaction до їхнього QUERY. Це може бути корисно при генерації нових записів журналу для збереження у журналі.

Інший синтаксис

Формат журналу hledger підтримує ще кілька інших функцій, переважно, щоб полегшити взаємодію або перетворення з Ledger. Зауважте, що деякі з функцій нижче є потужними і можуть бути корисними в особливих випадках, але загалом вони вважаються менш важливими або навіть не рекомендованими для більшості користувачів. Недоліки згадані, щоб допомогти вам вирішити, чи хочете ви їх використовувати.

Призначення балансу

Призначення балансу Ledger-стилю також підтримуються. Вони як твердження балансу, але без суми посту ліворуч від знаку дорівнює; натомість вона обчислюється автоматично, щоб задовольнити твердження. Це може бути зручно під час введення даних, наприклад, коли встановлюються початкові баланси:

; початок нового журналу, встановлення балансів рахунків активів
2016/1/1 opening balances
  assets:checking            = $409.32
  assets:savings             = $735.24
  assets:cash                 = $42
  equity:opening balances

або коли коригується баланс до реальності:

; готівки скінчилися; оновити баланс, записати будь-які незареєстровані витрати як загальні витрати
2016/1/15
  assets:cash    = $0
  expenses:misc

Обчислена сума залежить від балансу рахунку в товарі в цей момент (який залежить від попередніх датованих постів товару до цього рахунку з останнього твердження балансу або призначення).

Недоліки: використання призначень балансу робить ваш журнал менш явним; щоб знати точну суму посту, вам доведеться запустити hledger або зробити обчислення самостійно, замість того, щоб просто прочитати її. Також призначення балансу примусово встановлюють баланси, що може приховувати помилки. Ці речі роблять ваші фінансові дані менш переносимими, менш стійкими до майбутнього і менш надійними при аудиті.

Призначення балансу та вартості

Вартість у призначенні балансу спричинить обчислення суми з прикріпленою вартістю:

2019/1/1
  (a)             = $1 @ €2

$ hledger print --explicit
2019-01-01
    (a)         $1 @ €2 = $1 @ €2

Призначення балансу та кілька файлів

Призначення балансу обробляє кілька файлів як твердження балансу. Вони бачать баланс з інших файлів, раніше включених з поточного файлу, але не з попередніх сусідніх або батьківських файлів.

Дати постів у дужках

Для встановлення дат постів і вторинних дат постів, підтримується також синтаксис дужок Ledger: [DATE], [DATE=DATE2] або [=DATE2] у коментарях постів. hledger намагатиметься проаналізувати будь-яку послідовність слів 0123456789/-.= у квадратних дужках цим способом. З DATE виводиться рік з операції, а DATE2 виводиться рік з DATE.

Недоліки: ще один синтаксис для вивчення, дублюється з hledger's date:/tags, і плутається з синтаксисом дати лоту Ledger.

Директива D

D AMOUNT

Ця директива встановлює товар за замовчуванням, який буде використовуватися для будь-яких наступних сум без товару (тобто прості числа) при аналізі журналу. Цей ефект триває до наступної директиви D або кінця поточного файлу.

Для сумісності/історичних причин, D також діє як директива commodity (встановлюючи десятковий розділювач товару для аналізу та стиль відображення для виводу). Тож її аргумент не просто символ товару, а повна сума, що демонструє стиль. Сума має містити десятковий розділювач (або крапка, або кома). Наприклад:

; товари без символу мають трактуватися як долари
; (і відображатися з символом долара ліворуч, розділювачами тисяч і двома десятковими знаками)
D $1,000.00

1/1
  a     5  ; <- сума без товару, проаналізована як $5 і відображена як $5.00
  b

Взаємодії з іншими директивами:

Для встановлення стилю відображення товару, директива commodity має найвищий пріоритет, потім директива D.

Для виявлення десяткового розділювача товару під часу аналізу, decimal-mark має найвищий пріоритет, потім commodity, потім D.

Для перевірки символів товару з командою перевірки, потрібна директива commodity (hledger check commodities ігнорує директиви D).

Недоліки: опускання символів товару робить ваші фінансові дані менш явними, менш переносимими і менш надійними при аудиті. Це зазвичай нездійсненна стратегія; рано чи пізно ви захочете відстежувати кілька товарів. D перевантажена функціями, що дублюються з commodity і decimal-mark. І вона працює інакше, ніж D в Ledger.

Директива apply account

Ця директива встановлює батьківський рахунок за замовчуванням, який буде доданий до всіх рахунків у наступних записах, до директиви end apply account або кінця поточного файлу. Наприклад:

apply account home

2010/1/1
    food    $10
    cash

end apply account

еквівалентно:

2010/01/01
    home:food           $10
    home:cash          $-10

Директиви account також впливають, і будь-який включений вміст також. Назви рахунків, введені через hledger add або hledger-web, не впливають.

Якщо є псевдоніми рахунків, вони застосовуються після додавання батьківського рахунку.

Недоліки: це може зробити ваші фінансові дані менш явними, менш переносимими і менш надійними при аудиті.

Директива Y

Y YEAR

або (застарілі форми, що зберігають сумісність): year YEAR apply year YEAR

Пробіл необов'язковий. Це встановлює рік за замовчуванням для використання в наступних датах, які не вказують рік. Наприклад:

Y2009  ; встановити рік за замовчуванням 2009

12/15  ; еквівалентно 2009/12/15
  expenses  1
  assets

year 2010  ; змінити рік за замовчуванням на 2010

2009/1/30  ; вказує рік, не впливає
  expenses  1
  assets

1/31   ; еквівалентно 2010/1/31
  expenses  1
  assets

Недоліки: опускання року (принаймні в основних датах операцій) робить ваші фінансові дані менш явними, менш переносимими і менш надійними при аудиті. Такі дати можуть відокремитися від відповідної директиви Y, наприклад, при оцінці регіону журналу у вашому редакторі. Відсутня директива Y робить звіти залежними від сьогоднішньої дати.

Вторинні дати

Вторинна дата записується після основної дати, після знаку дорівнює: DATE1=DATE2. Якщо рік опущено, використовується рік основної дати. При запуску звітів, використовується основна (ліва) дата за замовчуванням, але з прапорцем --date2 (--aux-date або --effective також працюють для користувачів Ledger), використовується вторинна (права) дата.

Значення вторинних дат визначаєте ви. Наприклад, "основна - це дата очищення банку, вторинна - дата ініціювання транзакції, якщо інша".

На практиці, ця функція зазвичай додає плутанини:

• Вам доведеться пам'ятати значення основних і вторинних дат і дотримуватися цього послідовно.
• Це розділяє ваш облік на два режими, і вам доведеться пам'ятати, який режим підходить для певного звіту.
• Зазвичай ваші твердження балансу працюватимуть лише з одним з цих режимів.
• Це робить ваші фінансові дані складнішими, менш переносимими і менш зрозумілими при аудиті.
• Це взаємодіє з кожною функцією, створюючи постійну вартість для розробників.
• Це відволікає нових користувачів і підтримувачів.
• Дати постів простіші і працюють краще.

Тож вторинні дати офіційно застаріли в hledger, залишаючись лише як засіб сумісності з Ledger; ми рекомендуємо використовувати дати постів натомість.

Коментарі з зірочкою

Рядки, що починаються з * (зірочка/астериск), також є коментарями. Ця функція дозволяє користувачам Emacs вставляти заголовки org у свій журнал, дозволяючи їм згортати/розгортати/переходити по ньому, коли переглядається з org mode.

Недоліки: ще один, нетрадиційний синтаксис коментарів для вивчення. Зменшує переносимість вашого журналу. І перемикання на Emacs org mode лише для згортання/розгортання означало б втрату переваг режиму ledger; зараз ви можете додати режим outshine до ledger mode, щоб отримати згортання, не втрачаючи переваг режиму ledger.

Вирази оцінки

У Ledger дозволено писати функцію оцінки або значення в подвійних дужках після суми. hledger ігнорує ці.

Віртуальні пости

Пост з дужками навколо назви рахунку, як (some:account) 10, називається віртуальним постом без балансу. Ці пости не беруть участь у балансуванні операцій. (І якщо ви записуєте їх без суми, завжди виводиться нульова сума.) Ці можуть бути зручними в особливих обставинах, але вони порушують подвійний бухгалтерський облік і роблять ваші дані менш переносимими між додатками, тож багато людей уникають їх використання взагалі.

Пост з квадратними дужками навколо назви рахунку ([some:account]) називається віртуальним постом з балансом. Віртуальні пости з балансом в операції мають підсумовуватися до нуля, як звичайні пости, але окремо від них. Ці не є частиною подвійного бухгалтерського обліку, але принаймні вони збалансовані. Приклад:

2022-01-01 купівля їжі готівкою, оновлення бюджетних підрозділів рахунків, та ще щось
  assets:cash                    $-10  ; <- ці балансують одна одну
  expenses:food                    $7  ; <-  
  expenses:food                    $3  ; <-  
  [assets:checking:budget:food]  $-10  ;   <- а ці балансують одна одну
  [assets:checking:available]     $10  ;   <-  
  (something:else)                 $5  ;     <- це не вимагає балансування

Звичайні пости, чиї назви рахунків не обведені дужками або квадратними дужками, називаються реальними постами. Ви можете виключити віртуальні пости зі звітів з прапорцем -R/--real або запитом real:1.

Інші директиви Ledger

Ці інші директиви Ledger наразі приймаються, але ігноруються. Це дозволяє hledger читати більше файлів Ledger, але майте на увазі, що звіти hledger можуть відрізнятися від звітів Ledger, якщо ви використовуєте ці.

apply fixed COMM AMT
apply tag   TAG
assert      EXPR
bucket / A  ACCT
capture     ACCT REGEX
check       EXPR
define      VAR=EXPR
end apply fixed
end apply tag
end apply year
end tag
eval / expr EXPR
python
  PYTHONCODE
tag         NAME
value       EXPR
--command-line-flags

Див. також https://hledger.org/ledger.html для детального порівняння синтаксису hledger/Ledger.

Інші позначення вартості/лотів

Невелике відхилення для користувачів Ledger і Beancount.

Ledger має кілька пов'язаних з вартістю/лотом позначень:

• @ UNITCOST та @@ TOTALCOST
  • виражає курс обміну, як у hledger
  • коли купується, також створює лот, який можна вибрати в момент продажу
• (@) UNITCOST та (@@) TOTALCOST (віртуальна вартість)
  • як вище, але також означає "ця вартість була виняткова, не використовуй її при виведенні ринкових цін"
• {=UNITCOST} та {{=TOTALCOST}} (фіксована ціна)
  • коли купується, означає, що це також фіксована вартість, не дозволяючи їй коливатися у звітах про вартість
• {UNITCOST} та {{TOTALCOST}} (ціна лоту)
  • може використовуватися ідентично @ UNITCOST та @@ TOTALCOST, також створює лот
  • коли продається, поєднано з @ ..., вибирає існуючий лот за основою його вартості. Не перевіряє, чи цей лот присутній.

Beancount має простіший синтаксис і поведінку:

• @ UNITCOST та @@ TOTALCOST
  • виражає вартість без створення лоту, як у hledger
  • коли купується (набувається) або продається (відчужується) лот, і поєднано з {...}, використовується лише для документування вартості/ціни продажу

Наразі, hledger

• приймає будь-який або всі вищезгадані в будь-якому порядку після суми посту
• підтримує @ і @@
• розглядає (@) і (@@) як синоніми для @ і @@
• ігнорує решту. (Це може порушити балансування операцій.)

CSV

hledger може читати операції з файлів CSV (значення, розділені комами). Більш точно, він може читати DSV (значення, розділені розділювачем), з файлу або стандартного вводу. Найпоширеніші варіанти - кома, крапка з комою і табуляція, і hledger розпізнає їх автоматично на основі розширення файлу .csv, .ssv або .tsv або префіксу шляху до файлу csv:, ssv: або tsv:.

(Щоб дізнатися про виробництво CSV або TSV виводу, див. Формат виводу.)

Кожен файл CSV має бути описаний відповідним файлом правил. Це містить правила, що описують дані CSV (рядок заголовка, розташування полів, формат дати тощо), як побудувати з них операції hledger і як класифікувати операції на основі опису або інших атрибутів.

За замовчуванням, hledger очікує, що цей файл правил буде названий як CSV файл, з доданим розширенням .rules, у тій самій теці. Наприклад, коли проситься читати foo/FILE.csv, hledger шукає foo/FILE.csv.rules. Ви можете вказати інший файл правил з опцією --rules.

Принаймні, файл правил має ідентифікувати поля дати та суми, і часто він також вказує формат дати і скільки рядків заголовка є. Ось простий CSV файл і файл правил для нього:

Date, Description, Id, Amount
12/11/2019, Foo, 123, 10.23

# basic.csv.rules
skip         1
fields       date, description, , amount
date-format  %d/%m/%Y

$ hledger print -f basic.csv
2019-11-12 Foo
    expenses:unknown           10.23
    income:unknown            -10.23

Є вступний Підручник: Імпорт даних CSV на hledger.org, і більше прикладів правил CSV нижче, і більша колекція на https://github.com/simonmichael/hledger/tree/master/examples/csv.

Шпаргалка правил CSV

Наступні види правил можуть з'явитися у файлі правил, в будь-якому порядку. (Порожні рядки і рядки, що починаються з #, ; або *, ігноруються.)

Робота з CSV поради можна знайти нижче, включаючи Як оцінюються правила CSV.

source

Якщо ви скажете hledger читати файл csv з -f foo.csv, він шукатиме правила в foo.csv.rules. Або, ви можете сказати йому читати файл правил, з -f foo.csv.rules, і він шукатиме дані в foo.csv (з 1.30). Ці майже еквівалентні, але другий метод надає деякі додаткові функції. Наприклад, даний файл може бути відсутнім, без виклику помилки; він просто вважається порожнім.

Для більшої гнучкості, додайте правило source, яке дозволяє вказати інший файл даних:

source ./Checking1.csv

Якщо файл не існує, він просто вважається порожнім, без виклику помилки.

Якщо ви вкажете лише ім'я файлу без шляху, hledger шукатиме його в теці ~/Downloads:

source Checking1.csv

Ви можете використовувати глоб-шаблон, щоб уникнути вказування точного імені файлу:

source Checking1*.csv

Це має ще одну перевагу: якщо шаблон відповідає кільком файлам, hledger читатиме найновіший (найбільш нещодавно змінений). Це уникає проблем, якщо ви завантажували файл кілька разів без очищення.

Все це дозволяє зручний робочий процес, де ви просто завантажуєте CSV файли, а потім запускаєте hledger import rules/*.

Див. також "Робота з CSV > Читання файлів, вказаних правилом".

Команди очищення даних / генерації даних

Після source файлу, ви можете написати | (вертикальна риска) і команду очищення даних (або ланцюжок команд). Якщо правила CSV hledger не достатні, ви можете попередньо обробити завантажені дані командою або скриптом у вашій оболонці, щоб зробити їх придатнішими для перетворення. Команда буде виконана вашою оболонкою за замовчуванням, у теці файлу правил, отримає вміст файлу даних як стандартний ввід і має вивести нуль або більше рядків значень, розділених символами, придатних для перетворення правилами CSV.

Приклади:

source ./paypal.json | paypalcsv
source data/simplefin.json | simplefincsv - 'chase.*card'
source OfxDownload*.csv | grep -vE '^(([^,]*,){6}[^,]*|)$' | sort -t, -n +2
source History_for_Account_Z20144832*.csv   # | grep -E '^([^,]*,){12}[^,]*$' | sed -E -e 's/^ //' -e 's/\.([0-9]),/.\10,/g' -e 's/,([0-9]+),/,\1.00,/g'

Або, після source ви можете написати | і команду генерації даних (без шаблону файлу перед |). Ця команда не отримує вхідних даних, і має вивести нуль або більше рядків значень, розділених символами, придатних для перетворення правилами CSV.

Приклади:

source | paypaljson | paypalcsv
source | paypalcsv data/paypal.json
source | simplefinjson >data/simplefin.json && simplefincsv data/simplefin.json 'chase.*card'
source | simplefincsv data/simplefin.json 'unify.*checking'

(paypal* і simplefin* скрипти у bin/)

Коли hledger запускає одну з цих команд, він виводитиме команду на stderr. Якщо команда виробляє вихідну помилку, але виходить успішно, hledger покаже вихідну помилку як попередження. Якщо команда не вдається, hledger не вдається і показує вихідну помилку у повідомленні про помилку.

*Додано в 1.50;