From 4ab71f0d0ad3a2ce0e51b157a84622d340acfac7 Mon Sep 17 00:00:00 2001 From: Simon Michael Date: Wed, 1 Nov 2017 08:01:56 -0700 Subject: [PATCH] journal: clarify that txn/posting comments must start with semicolon --- hledger-lib/Hledger/Read/Common.hs | 25 +++++---- hledger-lib/doc/hledger_journal.5.m4.md | 18 +++--- tests/journal/comments.test | 75 +++++++++---------------- 3 files changed, 50 insertions(+), 68 deletions(-) diff --git a/hledger-lib/Hledger/Read/Common.hs b/hledger-lib/Hledger/Read/Common.hs index 9afc3ae65..539b2c005 100644 --- a/hledger-lib/Hledger/Read/Common.hs +++ b/hledger-lib/Hledger/Read/Common.hs @@ -610,15 +610,15 @@ multilinecommentp = do emptyorcommentlinep :: JournalParser m () emptyorcommentlinep = do - lift (many spacenonewline) >> (commentp <|> (lift (many spacenonewline) >> newline >> return "")) + lift (many spacenonewline) >> (linecommentp <|> (lift (many spacenonewline) >> newline >> return "")) return () -- | Parse a possibly multi-line comment following a semicolon. followingcommentp :: JournalParser m Text followingcommentp = -- ptrace "followingcommentp" - do samelinecomment <- lift (many spacenonewline) >> (try semicoloncommentp <|> (newline >> return "")) - newlinecomments <- many (try (lift (some spacenonewline) >> semicoloncommentp)) + do samelinecomment <- lift (many spacenonewline) >> (try commentp <|> (newline >> return "")) + newlinecomments <- many (try (lift (some spacenonewline) >> commentp)) return $ T.unlines $ samelinecomment:newlinecomments -- | Parse a possibly multi-line comment following a semicolon, and @@ -650,10 +650,10 @@ followingcommentandtagsp mdefdate = do -- to get good error positions. startpos <- getPosition commentandwhitespace :: String <- do - let semicoloncommentp' = (:) <$> char ';' <*> anyChar `manyTill` eolof + let commentp' = (:) <$> char ';' <*> anyChar `manyTill` eolof sp1 <- lift (many spacenonewline) - l1 <- try (lift semicoloncommentp') <|> (newline >> return "") - ls <- lift . many $ try ((++) <$> some spacenonewline <*> semicoloncommentp') + l1 <- try (lift commentp') <|> (newline >> return "") + ls <- lift . many $ try ((++) <$> some spacenonewline <*> commentp') return $ unlines $ (sp1 ++ l1) : ls let comment = T.pack $ unlines $ map (lstrip . dropWhile (==';') . strip) $ lines commentandwhitespace -- pdbg 0 $ "commentws:"++show commentandwhitespace @@ -676,14 +676,15 @@ followingcommentandtagsp mdefdate = do return (comment, tags, mdate, mdate2) +-- A transaction/posting comment must start with a semicolon. +-- This parser ignores leading whitespace. commentp :: JournalParser m Text -commentp = commentStartingWithp commentchars +commentp = commentStartingWithp ";" -commentchars :: [Char] -commentchars = "#;*" - -semicoloncommentp :: JournalParser m Text -semicoloncommentp = commentStartingWithp ";" +-- A line (file-level) comment can start with a semicolon, hash, +-- or star (allowing org nodes). This parser ignores leading whitespace. +linecommentp :: JournalParser m Text +linecommentp = commentStartingWithp ";#*" commentStartingWithp :: [Char] -> JournalParser m Text commentStartingWithp cs = do diff --git a/hledger-lib/doc/hledger_journal.5.m4.md b/hledger-lib/doc/hledger_journal.5.m4.md index 1ec0007d7..29dc9ff6c 100644 --- a/hledger-lib/doc/hledger_journal.5.m4.md +++ b/hledger-lib/doc/hledger_journal.5.m4.md @@ -541,8 +541,9 @@ P 2010/1/1 € $1.40 ## Comments Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or -asterisk (`*`) are comments, and will be ignored. (Asterisk comments -make it easy to treat your journal like an org-mode outline in emacs.) +star (`*`) are comments, and will be ignored. (Star comments cause +org-mode nodes to be ignored, allowing emacs users to fold and navigate +their journals with org-mode or orgstruct-mode.) Also, anything between [`comment` and `end comment` directives](#multi-line-comments) is a (multi-line) comment. If there is no `end comment`, the comment extends to the end of the file. @@ -551,20 +552,21 @@ You can attach comments to a transaction by writing them after the description and/or indented on the following lines (before the postings). Similarly, you can attach comments to an individual posting by writing them after the amount and/or indented on the -following lines. +following lines. +Transaction and posting comments must begin with a semicolon (`;`). Some examples: ```journal -# a journal comment +# a file comment -; also a journal comment +; also a file comment comment -This is a multiline comment, +This is a multiline file comment, which continues until a line where the "end comment" string -appears on its own. +appears on its own (or end of file). end comment 2012/5/14 something ; a transaction comment @@ -573,7 +575,7 @@ end comment posting2 ; a comment for posting 2 ; another comment line for posting 2 -; a journal comment (because not indented) +; a file comment (because not indented) ``` ## Tags diff --git a/tests/journal/comments.test b/tests/journal/comments.test index d513813f1..eb97d9491 100644 --- a/tests/journal/comments.test +++ b/tests/journal/comments.test @@ -1,78 +1,56 @@ # comment tests -# 1. +# 1. several comment characters allowed for file characters; +# print shows in-transaction & posting comments; +# comment line is preserved, starting column is not. hledger -f - print <<< -2009/01/01 x - ; transaction comment 1 - ; transaction comment 2 - a 1 - b ->>> -2009/01/01 x - ; transaction comment 1 - ; transaction comment 2 - a 1 - b +; file comments, ignored +# file comment using a hash +* file comment using a star (org node) + ; file comments need not + # start in + * column 0 ->>>=0 - -# 2. -hledger -f - print -<<< -2009/01/01 x - a 1 - b -; comment line after postings ->>> -2009/01/01 x - a 1 - b - ->>>=0 - -# 3. print should preserve transaction (entry) comments and which line they're on -hledger -f - print -<<< -; leading journal comment, not preserved - -; transaction preceding comment, not preserved +; pre-transaction comment, ignored 2009/1/1 x ; transaction same line comment - ; transaction new line comment + ; transaction new line comment a 1 ; posting 1 same line comment ; posting 1 new line comment - b + a ; posting 2 new line comment -; journal comment right after the transaction, not preserved +; file comment right after the transaction, ignored -; trailing journal comment, not preserved +; trailing file comment, ignored >>> 2009/01/01 x ; transaction same line comment ; transaction new line comment a 1 ; posting 1 same line comment ; posting 1 new line comment - b + a ; posting 2 new line comment >>>2 >>>=0 -# 4. a posting comment should appear in print +# 2. transaction comments must use ; hledger -f - print <<< -2010/01/01 x - a 1 ; comment - b -1 - +2017/1/1 this # and * are not ; the comment >>> -2010/01/01 x - a 1 ; comment - b -1 +2017/01/01 this # and * are not ; the comment >>>2 >>>=0 -# 5. a posting comment should not appear in register +# 3. posting comments must use ; +hledger -f - print +<<< +2017/1/1 + a 0 # hash & star not allowed for posting comments +>>>=1 + +# 4. register does not show comments hledger -f - register <<< 2010/1/1 x @@ -84,3 +62,4 @@ hledger -f - register b -1 0 >>>2 >>>=0 +