packages feed

hledger-flow-0.21.0: src/Hledger/Flow/Init/Example.hs

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes #-}

module Hledger.Flow.Init.Example
  ( exampleImportFiles,
    isSampleStatement,
    exampleBaseFiles,
    starterOwner,
    exampleAccount,
    exampleAccountPath,
    sampleAccountDir,
    untouchedExample,
    directivesAreStarter,
    journalIsCommentsOnly,
  )
where

import qualified Data.ByteString as B
import Data.List (intercalate)
import Data.Maybe (fromMaybe, mapMaybe)
import qualified Data.Text as T
import qualified Data.Text.Encoding as T
import qualified Data.Text.IO as TIO
import Hledger.Flow.Common (Shell (..), nativeShell)
import Hledger.Flow.DocHelpers (DocLink (Balances, ManualJournals, RulesFiles), docURL)
import Hledger.Flow.PathHelpers (AbsDir, AbsFile, RelDir, RelFile, pathOccupied)
import Hledger.Flow.Types (BaseDir)
import Path
import qualified Path.IO as PathIO
import System.Environment (lookupEnv)
import qualified System.FilePath as F
import qualified System.FilePath.Windows as Windows
import System.IO.Error (tryIOError)
import Text.Read (readMaybe)

starterOwner :: IO RelDir
starterOwner = do
  let variable = case nativeShell of
        Posix -> "USER"
        PowerShell -> "USERNAME"
  value <- either (const Nothing) id <$> tryIOError (lookupEnv variable)
  return (fromMaybe [reldir|me|] (value >>= validOwner))
  where
    validOwner name
      | Windows.isValid name,
        Windows.splitDirectories name == [name],
        not (any Windows.isPathSeparator name),
        T.strip text == text,
        not (T.isPrefixOf "." text || T.isPrefixOf "~" text),
        not (T.isSuffixOf "." text),
        ';' `notElem` name,
        not (T.isSuffixOf ".journal" folded),
        folded /= "_manual_",
        B.length (T.encodeUtf8 text) <= 255 = parseRelDir name
      | otherwise = Nothing
      where
        text = T.pack name
        folded = T.toCaseFold text

exampleAccount :: RelDir -> RelDir
exampleAccount owner = owner </> [reldir|mybank/checking|]

exampleAccountPath :: RelDir -> T.Text
exampleAccountPath account = "import/" <> T.pack (intercalate "/" parts)
  where
    parts = F.splitDirectories (F.dropTrailingPathSeparator (toFilePath account))

sampleName :: RelFile
sampleName = [relfile|hledger-flow-example.csv|]

isSampleStatement :: AbsFile -> Bool
isSampleStatement file = filename file == sampleName

rulesName :: RelFile
rulesName = [relfile|mybank-checking.rules|]

sampleCsv :: Integer -> T.Text
sampleCsv year = T.unlines $
  zipWith (<>) (sampleCsvRows year) [",Comment", ",\"" <> starterNotice <> "\"", ","]

sampleCsvRows :: Integer -> [T.Text]
sampleCsvRows year =
  ["Date,Description,Amount", date <> ",Example purchase,-5.00", date <> ",Example refund,5.00"]
  where
    date = T.pack (show year) <> "-01-02"

sampleRules :: T.Text
sampleRules = T.unlines
  [ "# Rules for the example statement.",
    "# Docs: " <> docURL RulesFiles,
    "skip 1",
    "fields date, description, amount",
    "currency USD",
    "account1 assets:mybank:checking",
    "account2 expenses:unknown",
    "",
    "if Example",
    " account2 expenses:example"
  ]

exampleImportFiles :: RelDir -> Integer -> [(RelFile, T.Text)]
exampleImportFiles starter year =
  (exampleAccount starter </> rulesName, starterComment "# " sampleRules)
    : paths ((samplePath, sampleCsv year) : manualFiles ++ balanceFiles)
  where
    account = F.dropTrailingPathSeparator (toFilePath (exampleAccount starter))
    bank = F.takeDirectory account
    owner = F.takeDirectory bank
    yearName = show year
    samplePath = account F.</> "1-in" F.</> yearName F.</> toFilePath sampleName
    date day = T.pack yearName <> "-" <> day
    entry day description postings = (date day <> " " <> description) : map ("    " <>) postings
    manual level phase help example =
      (level F.</> "_manual_" F.</> yearName F.</> (phase ++ "-import.journal"),
       journalExample ManualJournals help example)
    balance suffix help example =
      (account F.</> (yearName ++ "-" ++ suffix ++ ".journal"), journalExample Balances help example)
    manualFiles =
      [ manual "" "pre" ["Record an entry shared across owners before their imported activity."]
          (entry "01-01" "Fund the household cash box from my cash"
            ["assets:household:cash  150.00 USD", "assets:me:cash"]),
        manual "" "post" ["Record a transfer between owners after reviewing both sets of statements."]
          (entry "01-02" "Reimburse partner for shared groceries"
            ["assets:partner:cash  35.00 USD", "assets:me:cash"]),
        manual owner "pre" ["Fill a gap in a transfer between this owner's banks before their first statements."]
          (entry "01-01" "Move savings to a new bank"
            ["assets:otherbank:savings  75.00 USD", "assets:mybank:checking"]),
        manual owner "post" ["Record a transfer between this owner's banks after reviewing their statements."]
          (entry "01-02" "Move emergency savings back to checking"
            ["assets:mybank:checking  50.00 USD", "assets:otherbank:savings"]),
        manual bank "pre" ["Record a transfer between accounts at this bank before their imported activity."]
          (entry "01-01" "Move money from checking to savings"
            ["assets:mybank:savings  25.00 USD", "assets:mybank:checking"]),
        manual bank "post" ["Fill in a transfer missing from both exports after reviewing this bank's statements."]
          (entry "01-02" "Sweep savings into checking"
            ["assets:mybank:checking  12.00 USD", "assets:mybank:savings"]),
        manual account "pre"
          ["Fill a gap before this account's first statement.", "Put opening balances in the dedicated yearly opening file."]
          (entry "01-01" "Replace debit card"
            ["expenses:bank-fees  5.00 USD", "assets:mybank:checking"]),
        manual account "post"
          ["Assert this account's balance after its imported entries for the same day.",
           "Use the balance shown by your bank. Put closing balances in the dedicated yearly closing file."]
          (entry "01-02" "Check balance after the sample statement"
            ["assets:mybank:checking  0 USD = 0 USD"])
      ]
    balanceFiles =
      [ balance "opening" ["Record what this account already held just before its first imported transaction."]
          (entry "01-01" "Checking opening balance"
            ["assets:mybank:checking  100.00 USD", "equity:opening/closing balances"]),
        balance "closing"
          ["Close this account's balance to zero when you deliberately close your books.",
           "This example assumes the starter opening balance and sample statement."]
          (entry "12-31" "Checking closing balance"
            ["assets:mybank:checking  -100.00 USD = 0 USD", "equity:opening/closing balances"])
      ]

starterNotice :: T.Text
starterNotice = "Generated by hledger-flow init as a starter. This file is yours to edit. hledger-flow leaves it as you save it."

starterComment :: T.Text -> T.Text -> T.Text
starterComment prefix contents = prefix <> starterNotice <> "\n" <> contents

optionalIncludeNotice :: T.Text
optionalIncludeNotice = "; This file is optional. If absent, hledger-flow omits it from the include files it maintains."

optionalJournal :: T.Text -> T.Text
optionalJournal contents = starterComment "; " (optionalIncludeNotice <> "\n" <> contents)

journalExample :: DocLink -> [T.Text] -> [T.Text] -> T.Text
journalExample link help example = optionalJournal $ T.unlines $
  map ("; " <>) help ++ ["; Docs: " <> docURL link, "", "; Example. Remove its leading semicolons and adapt it."]
    ++ map ("; " <>) example

exampleBaseFiles :: Integer -> [(RelFile, T.Text)]
exampleBaseFiles year = paths $
  [("directives.journal", starterDirectives)]
    ++ [ (priceDir F.</> name, starterComment "; " (T.unlines
           [ "; This file is optional. Remove its include line from prices.journal to omit the pair.",
             "; Add market prices here.",
             "; P " <> date <> " " <> quote
           ]))
         | (name, quote) <- pairs
       ]
    ++ [(priceDir F.</> "prices.journal", optionalJournal (T.unlines ["include " <> T.pack name | (name, _) <- pairs]))]
  where
    priceDir = "prices" F.</> show year
    date = T.pack (show year) <> "-01-01"
    pairs = [("EUR-USD.prices", "EUR 1.10 USD"), ("BTC-USD.prices", "BTC 99000.00 USD")]

starterDirectives :: T.Text
starterDirectives = T.unlines
  [ "; Ledger-wide directives go here. https://hledger.org/dev/hledger.html#directives",
    "; " <> starterNotice,
    optionalIncludeNotice,
    "",
    "; Common commodities. https://hledger.org/dev/hledger.html#commodity-aliases",
    "commodity 1,000.00 USD  ; alias: US$",
    "commodity 1,000.00 EUR  ; alias: €",
    "commodity 1,000.00 GBP  ; alias: £",
    "commodity 1,000.00 CAD  ; alias: CA$",
    "commodity 1,000.00 AUD  ; alias: A$",
    "commodity 1,000. JPY    ; alias: JP¥",
    "commodity 1,000.00 CNY  ; alias: CN¥, alias: RMB",
    "commodity 1,000.00 INR  ; alias: ₹",
    "",
    "; Bitcoin and satoshis. https://hledger.org/dev/hledger.html#commodity-units",
    "commodity 1.00000000 BTC  ; alias: 100000000 SAT, alias: ₿",
    "commodity 1. SAT",
    "",
    "; Account types. https://hledger.org/dev/hledger.html#account-types",
    "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",
    "account equity:unrealised-gain  ; type: U",
    "account revenues:gain           ; type: G"
  ]

paths :: [(FilePath, a)] -> [(RelFile, a)]
paths = mapMaybe (\(p, a) -> fmap (\path -> (path, a)) (parseRelFile p))

untouchedExample :: BaseDir -> [AbsFile] -> IO (Maybe RelDir)
untouchedExample base [source]
  | Just rel <- stripProperPrefix (importRoot base) source,
    [ownerName, "mybank", "checking", "1-in", yearName, name] <- F.splitDirectories (toFilePath rel),
    name == toFilePath sampleName,
    Just starter <- parseRelDir ownerName,
    Just year <- readMaybe yearName,
    Just generated <- parseRelFile ("3-journal" F.</> yearName F.</> "hledger-flow-example.journal"),
    Just yearIndex <- parseRelFile (yearName ++ "-include.journal") = do
      let account = sampleAccountDir base starter
      result <- tryIOError $ do
        let rules = account </> rulesName
            journal = account </> generated
            bank = parent account
            owner = parent bank
            indexes dir = [dir </> yearIndex, dir </> [relfile|all-years.journal|]]
            otherStarters =
              [ (file, contents)
                | (relative, contents) <- exampleImportFiles starter year,
                  let file = importRoot base </> relative,
                  isProperPrefixOf owner file, file /= source, file /= rules
              ]
            allowed = [source, rules, journal] ++ map fst otherStarters ++ concatMap indexes [owner, bank, account]
            dirs = concatMap (takeWhile (isProperPrefixOf owner) . iterate parent . parent) allowed
            optionalStarter (file, contents) = do
              exists <- PathIO.doesFileExist file
              if exists then matches file contents else pure True
        cleanPath <- allM plainDir [importRoot base, owner]
        cleanContents <- if cleanPath then containsOnly dirs allowed owner else return False
        if cleanContents then do
          current <- (&&) <$> matches source (sampleCsv year)
                          <*> matches rules (starterComment "# " sampleRules)
          sampleMatches <- if current then pure True
            else (&&) <$> matches source (T.unlines (sampleCsvRows year)) <*> matches rules sampleRules
          if sampleMatches then allM optionalStarter otherStarters else pure False
        else pure False
      return (case result of Right True -> Just (exampleAccount starter); _ -> Nothing)
  where
    matches file expected = (== T.encodeUtf8 expected) <$> B.readFile (toFilePath file)
untouchedExample _ _ = return Nothing

containsOnly :: [AbsDir] -> [AbsFile] -> AbsDir -> IO Bool
containsOnly allowedDirs allowedFiles dir = do
  (dirs, files) <- PathIO.listDir dir
  if all (`elem` allowedDirs) dirs && all (`elem` allowedFiles) files
    then do
      hasLinks <- (||) <$> (or <$> traverse PathIO.isSymlink dirs) <*> (or <$> traverse PathIO.isSymlink files)
      if hasLinks then return False else and <$> traverse (containsOnly allowedDirs allowedFiles) dirs
    else return False

importRoot :: BaseDir -> AbsDir
importRoot base = base </> [reldir|import|]

sampleAccountDir :: BaseDir -> RelDir -> AbsDir
sampleAccountDir base owner = importRoot base </> exampleAccount owner

-- Starter declarations and comments do not add transactions to the ledger.
directivesAreStarter :: BaseDir -> IO Bool
directivesAreStarter base = do
  let file = base </> [relfile|directives.journal|]
  exists <- pathOccupied file
  if exists
    then elem <$> readJournalBody file <*> pure [Just [], Just (journalBody starterDirectives)]
    else pure True

journalIsCommentsOnly :: AbsFile -> IO Bool
journalIsCommentsOnly file = (== Just []) <$> readJournalBody file

readJournalBody :: AbsFile -> IO (Maybe [T.Text])
readJournalBody file = do
  regular <- regularFile file
  if regular then Just . journalBody <$> TIO.readFile (toFilePath file) else pure Nothing

journalBody :: T.Text -> [T.Text]
journalBody = filter (\line -> not (T.null line || T.isPrefixOf ";" line)) . map T.strip . T.lines

plainDir :: AbsDir -> IO Bool
plainDir dir = do
  exists <- PathIO.doesDirExist dir
  if exists then not <$> PathIO.isSymlink dir else pure False

regularFile :: AbsFile -> IO Bool
regularFile file = do
  exists <- PathIO.doesFileExist file
  if exists then not <$> PathIO.isSymlink file else pure False

allM :: (a -> IO Bool) -> [a] -> IO Bool
allM check = fmap and . traverse check