dev: includedirectivep: cleanups, docs

hledger-lib/Hledger/Read/JournalReader.hs

@@ -304,11 +304,13 @@ includedirectivep = do
         Nothing  -> paths
         Just fmt -> map ((show fmt++":")++) paths
   -- parse them inline
-  forM_ prefixedpaths $ parseChild parentpos
+  forM_ prefixedpaths $ parseIncludedFile parentpos
 
   where
-    getFilePaths
-      :: MonadIO m => Int -> SourcePos -> FilePath -> JournalParser m [FilePath]
+
+    -- Find the files matched by a glob pattern, using the current parse context
+    -- for detecting the current directory and for error messages.
+    getFilePaths :: MonadIO m => Int -> SourcePos -> FilePath -> JournalParser m [FilePath]
     getFilePaths parseroff parserpos fileglobpattern = do
       -- Expand a ~ at the start of the glob pattern, if any.
       fileglobpattern' <- lift $ expandHomePath fileglobpattern
@@ -328,8 +330,11 @@ includedirectivep = do
         else customFailure $ parseErrorAt parseroff $
                 "No existing files match pattern: " ++ fileglobpattern
 
-    parseChild :: MonadIO m => SourcePos -> PrefixedFilePath -> ErroringJournalParser m ()
-    parseChild parentpos prefixedpath = do
+    -- Parse the given included file (and any deeper includes, recursively)
+    -- as if it was inlined in the current (parent) file.
+    -- The position in the parent file is provided for error messages.
+    parseIncludedFile :: MonadIO m => SourcePos -> PrefixedFilePath -> ErroringJournalParser m ()
+    parseIncludedFile parentpos prefixedpath = do
       let (_mprefix,filepath) = splitReaderPrefix prefixedpath
 
       parentj <- get
@@ -372,6 +377,7 @@ includedirectivep = do
       -- Update the parse state.
       put parentj'
 
+      where
         newJournalWithParseStateFrom :: FilePath -> Journal -> Journal
         newJournalWithParseStateFrom filepath j = nulljournal{
           jparsedefaultyear      = jparsedefaultyear j