slaesvuo/hledger
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

journal: clarify that txn/posting comments must start with semicolon

Browse Source
This commit is contained in:
Simon Michael 2017-11-01 08:01:56 -07:00
parent 0e4d791371
commit 4ab71f0d0a
3 changed files with 50 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
hledger-lib/Hledger/Read/Common.hs
View File

@ -610,15 +610,15 @@ multilinecommentp = do
emptyorcommentlinep :: JournalParser m () emptyorcommentlinep :: JournalParser m ()
emptyorcommentlinep = do emptyorcommentlinep = do
lift (many spacenonewline) >> (commentp <|> (lift (many spacenonewline) >> newline >> return "")) lift (many spacenonewline) >> (linecommentp <|> (lift (many spacenonewline) >> newline >> return ""))
return () return ()
-- | Parse a possibly multi-line comment following a semicolon. -- | Parse a possibly multi-line comment following a semicolon.
followingcommentp :: JournalParser m Text followingcommentp :: JournalParser m Text
followingcommentp = followingcommentp =
-- ptrace "followingcommentp" -- ptrace "followingcommentp"
do samelinecomment <- lift (many spacenonewline) >> (try semicoloncommentp <|> (newline >> return "")) do samelinecomment <- lift (many spacenonewline) >> (try commentp <|> (newline >> return ""))
newlinecomments <- many (try (lift (some spacenonewline) >> semicoloncommentp)) newlinecomments <- many (try (lift (some spacenonewline) >> commentp))
return $ T.unlines $ samelinecomment:newlinecomments return $ T.unlines $ samelinecomment:newlinecomments
-- | Parse a possibly multi-line comment following a semicolon, and -- | Parse a possibly multi-line comment following a semicolon, and
@ -650,10 +650,10 @@ followingcommentandtagsp mdefdate = do
-- to get good error positions. -- to get good error positions.
startpos <- getPosition startpos <- getPosition
commentandwhitespace :: String <- do commentandwhitespace :: String <- do
let semicoloncommentp' = (:) <$> char ';' <*> anyChar `manyTill` eolof let commentp' = (:) <$> char ';' <*> anyChar `manyTill` eolof
sp1 <- lift (many spacenonewline) sp1 <- lift (many spacenonewline)
l1 <- try (lift semicoloncommentp') <|> (newline >> return "") l1 <- try (lift commentp') <|> (newline >> return "")
ls <- lift . many $ try ((++) <$> some spacenonewline <*> semicoloncommentp') ls <- lift . many $ try ((++) <$> some spacenonewline <*> commentp')
return $ unlines $ (sp1 ++ l1) : ls return $ unlines $ (sp1 ++ l1) : ls
let comment = T.pack $ unlines $ map (lstrip . dropWhile (==';') . strip) $ lines commentandwhitespace let comment = T.pack $ unlines $ map (lstrip . dropWhile (==';') . strip) $ lines commentandwhitespace
-- pdbg 0 $ "commentws:"++show commentandwhitespace -- pdbg 0 $ "commentws:"++show commentandwhitespace
@ -676,14 +676,15 @@ followingcommentandtagsp mdefdate = do
return (comment, tags, mdate, mdate2) return (comment, tags, mdate, mdate2)
-- A transaction/posting comment must start with a semicolon.
-- This parser ignores leading whitespace.
commentp :: JournalParser m Text commentp :: JournalParser m Text
commentp = commentStartingWithp commentchars commentp = commentStartingWithp ";"
commentchars :: [Char] -- A line (file-level) comment can start with a semicolon, hash,
commentchars = "#;*" -- or star (allowing org nodes). This parser ignores leading whitespace.
linecommentp :: JournalParser m Text
semicoloncommentp :: JournalParser m Text linecommentp = commentStartingWithp ";#*"
semicoloncommentp = commentStartingWithp ";"
commentStartingWithp :: [Char] -> JournalParser m Text commentStartingWithp :: [Char] -> JournalParser m Text
commentStartingWithp cs = do commentStartingWithp cs = do

16
hledger-lib/doc/hledger_journal.5.m4.md
View File

@ -541,8 +541,9 @@ P 2010/1/1 € $1.40
## Comments ## Comments
Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or Lines in the journal beginning with a semicolon (`;`) or hash (`#`) or
asterisk (`*`) are comments, and will be ignored. (Asterisk comments star (`*`) are comments, and will be ignored. (Star comments cause
make it easy to treat your journal like an org-mode outline in emacs.) 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. 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. If there is no `end comment`, the comment extends to the end of the file.
@ -552,19 +553,20 @@ description and/or indented on the following lines (before the
postings). Similarly, you can attach comments to an individual postings). Similarly, you can attach comments to an individual
posting by writing them after the amount and/or indented on the 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: Some examples:
```journal ```journal
# a journal comment # a file comment
; also a journal comment ; also a file comment
comment comment
This is a multiline comment, This is a multiline file comment,
which continues until a line which continues until a line
where the "end comment" string where the "end comment" string
appears on its own. appears on its own (or end of file).
end comment end comment
2012/5/14 something ; a transaction comment 2012/5/14 something ; a transaction comment
@ -573,7 +575,7 @@ end comment
posting2 posting2
; a comment for posting 2 ; a comment for posting 2
; another comment line for posting 2 ; another comment line for posting 2
; a journal comment (because not indented) ; a file comment (because not indented)
``` ```
## Tags ## Tags

73
tests/journal/comments.test
View File

@ -1,78 +1,56 @@
# comment tests # 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 hledger -f - print
<<< <<<
2009/01/01 x ; file comments, ignored
; transaction comment 1 # file comment using a hash
; transaction comment 2 * file comment using a star (org node)
a 1 ; file comments need not
b # start in
>>> * column 0
2009/01/01 x
; transaction comment 1
; transaction comment 2
a 1
b
>>>=0 ; pre-transaction comment, ignored
# 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
2009/1/1 x ; transaction same line comment 2009/1/1 x ; transaction same line comment
; transaction new line comment ; transaction new line comment
a 1 ; posting 1 same line comment a 1 ; posting 1 same line comment
; posting 1 new line comment ; posting 1 new line comment
b a
; posting 2 new line comment ; 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 2009/01/01 x ; transaction same line comment
; transaction new line comment ; transaction new line comment
a 1 ; posting 1 same line comment a 1 ; posting 1 same line comment
; posting 1 new line comment ; posting 1 new line comment
b a
; posting 2 new line comment ; posting 2 new line comment
>>>2 >>>2
>>>=0 >>>=0
# 4. a posting comment should appear in print # 2. transaction comments must use ;
hledger -f - print hledger -f - print
<<< <<<
2010/01/01 x 2017/1/1 this # and * are not ; the comment
a 1 ; comment
b -1
>>> >>>
2010/01/01 x 2017/01/01 this # and * are not ; the comment
a 1 ; comment
b -1
>>>2 >>>2
>>>=0 >>>=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 hledger -f - register
<<< <<<
2010/1/1 x 2010/1/1 x
@ -84,3 +62,4 @@ hledger -f - register
b -1 0 b -1 0
>>>2 >>>2
>>>=0 >>>=0