Release 0.3.0.0

Author: TravisCardwell

CHANGELOG.md

@@ -24,6 +24,17 @@ following conventions:
 
 [KaC]: <https://keepachangelog.com/en/1.0.0/>
 
+## 0.3.0.0 (2020-08-23)
+
+### Breaking
+
+* Add default section support
+* Add top-level queues array support
+* Add import support
+* Add user-defined tag support
+* Remove split property
+* Change templates to use snake-case properties
+
 ## 0.2.0.0 (2020-08-11)
 
 ### Breaking

Makefile

@@ -70,6 +70,13 @@ clean-all: clean # clean package and remove artifacts
 > @rm -f *.yaml.lock
 .PHONY: clean-all
 
+coverage: # run tests with code coverage *
+> @command -v hr >/dev/null 2>&1 && hr -t || true
+> @stack test --coverage $(RESOLVER_ARGS) $(STACK_YAML_ARGS) $(NIX_PATH_ARGS)
+> @stack hpc report .
+.PHONY: coverage
+# https://github.com/commercialhaskell/stack/issues/1305
+
 grep: # grep all non-hidden files for expression E
 > $(eval E:= "")
 > @test -n "$(E)" || $(call die,"usage: make grep E=expression")
@@ -205,7 +212,9 @@ todo: # search for TODO items
 >   -not -path './build/*' \
 >   -not -path './project/*' \
 >   -not -path ./Makefile \
->   | xargs grep -Hn TODO || true
+>   | xargs grep -Hn TODO \
+>   | grep -v '^Binary file ' \
+>   || true
 .PHONY: todo
 
 version: # show current version

README.md

@@ -16,8 +16,7 @@
 ## Overview
 
 Queue Sheet is a utility that builds PDFs of lists.  Printed PDFs can be used
-to track progress when offline.  Optionally include URLs when sharing a PDF
-with others so that they can easily access the media.
+to track progress when offline.
 
 Use Queue Sheet to track:
 
@@ -53,12 +52,13 @@ $ stack install
 
 See the [`queue-sheet` man page](doc/queue-sheet.1.md) for usage information.
 
-See the [example](example) directory for example files and output.
+See the [examples](examples) directory for example queue files, templates, and
+built output.
 
 ## Project
 
 Queue Sheet was written quickly to solve a particular pain point.  There are
-no plans to expose a library or put the package on Hackage.
+no plans to put the package on Hackage.
 
 ### Links
 

LibOA.hs app/LibOA.hsLibOA.hs renamed to app/LibOA.hs

@@ -0,0 +1,101 @@
+------------------------------------------------------------------------------
+-- |
+-- Module      : Main
+-- Description : queue-sheet program
+-- Copyright   : Copyright (c) 2020 Travis Cardwell
+-- License     : MIT
+------------------------------------------------------------------------------
+
+{-# LANGUAGE RecordWildCards #-}
+
+module Main (main) where
+
+-- https://hackage.haskell.org/package/base
+import Control.Applicative (optional)
+import System.Exit (exitFailure)
+
+-- https://hackage.haskell.org/package/optparse-applicative
+import qualified Options.Applicative as OA
+
+-- (queue-sheet)
+import QueueSheet (version)
+import QueueSheet.Build (buildPdf)
+
+-- (queue-sheet:executable)
+import qualified LibOA
+
+------------------------------------------------------------------------------
+-- $Constants
+
+-- | Default template file
+defaultTemplate :: FilePath
+defaultTemplate = "template.tex"
+
+------------------------------------------------------------------------------
+-- $Library
+
+-- | Display an error and exit the program
+errorExit :: String -> IO a
+errorExit msg = do
+    putStrLn $ "error: " ++ msg
+    exitFailure
+
+------------------------------------------------------------------------------
+-- $Options
+
+-- | Program options
+data Options
+  = Options
+    { optTemplate :: !FilePath
+    , optOutput   :: !(Maybe FilePath)
+    , optQueues   :: !FilePath
+    }
+  deriving Show
+
+-- | Parse program options
+parseOptions :: IO Options
+parseOptions = OA.execParser
+    $ OA.info (LibOA.helper <*> LibOA.versioner version <*> options)
+    $ mconcat
+        [ OA.fullDesc
+        , OA.progDesc "queue sheet utility"
+        , OA.failureCode 2
+        ]
+  where
+    options :: OA.Parser Options
+    options = Options
+      <$> templateOption
+      <*> optional outputOption
+      <*> queuesArgument
+
+    templateOption :: OA.Parser FilePath
+    templateOption = OA.strOption $ mconcat
+      [ OA.long "template"
+      , OA.short 't'
+      , OA.metavar "TEMPLATE.tex"
+      , OA.value defaultTemplate
+      , OA.showDefaultWith id
+      , OA.help "template file"
+      ]
+
+    outputOption :: OA.Parser FilePath
+    outputOption = OA.strOption $ mconcat
+      [ OA.long "output"
+      , OA.short 'o'
+      , OA.metavar "QUEUES.pdf"
+      , OA.help "output file"
+      ]
+
+    queuesArgument :: OA.Parser FilePath
+    queuesArgument = OA.strArgument $ mconcat
+      [ OA.metavar "QUEUES.yaml"
+      , OA.help "YAML file specifying queue information"
+      ]
+
+------------------------------------------------------------------------------
+-- $main
+
+main :: IO ()
+main = do
+  Options{..} <- parseOptions
+  either errorExit return =<< buildPdf optQueues optTemplate optOutput

app/queue-sheet.hs

@@ -14,8 +14,8 @@ hyphenate: false
 
 # DESCRIPTION
 
-Queue Sheet is a utility that builds PDFs of lists.  The printed PDFs can be
-used to track progress through the queues when offline.
+Queue Sheet is a utility that builds PDFs of lists.  Printed PDFs can be used
+to track progress through queues when offline.
 
 # OPTIONS
 
@@ -34,75 +34,113 @@ used to track progress through the queues when offline.
 # ARGUMENTS
 
 *QUEUES.yaml*
-:   YAML file specifying queue information
+:   queue file
 
 # FILES
 
 ## `QUEUES.yaml`
 
-This file is an object with two properties.
+A queue is a named list of items.  For example, a podcast can be represented
+as a queue where the queue name is the name of the podcast and each item in
+the queue is an episode of the podcast.  Queues can optionally be organized
+into sections.  For example, sections can be used to organize podcast queues
+by theme.
 
-The *sections* property is a list of section names (strings).  Note that the
-order determines the order in the output.
+Queues are specified in YAML format.  They may be specified in a few different
+ways, depending on how you want to organize them.
 
-The *queues* property is a list of queue objects with the following
-properties:
+To create a queue sheet of queues without sections, the YAML file consists of
+a list of queue objects, which have the following properties:
 
 *name*
-:   name of the queue (string, required)
+:   queue name (string, required)
 
 *url*
 :   queue URL (string, optional)
 
-*section*
-:   name of the section (string, required)
-
-*split*
-:   *true* to display items on separate lines (boolean, default *false*)
+*date*
+:   date of last update (string, optional)
 
 *tags*
 :   list of tags (list of string, optional)
 
-*date*
-:   date of last update (string, optional)
-
 *prev*
-:   previous (complete) item (item, optional)
+:   previous item (item, optional)
 
 *next*
 :   list of next items (list of items, optional)
 
-If both *prev* and *next* are specified, then *prev* is ignored.
+The only required property is *name*.
 
-An item name may be specified using a string.  To associate a URL with an
-item, use an object with the following properties:
+The *tags* property is a list of string tags that are associated with the
+queue.  A tag must consist of at least one ASCII letter, number, period,
+underscore, or dash.  For example, tag "complete" can be used to indicate that
+there will be no new episodes of a podcast that is complete.
+
+The *next* property is a list of next items in the queue.  When the list is
+exhausted, the previous item can be specified using the *prev* property.  If
+both *prev* and *next* are specified, *prev* is ignored.
+
+Items can be specified by name only, using a string or a number.  To associate
+a URL with an item, use an object with the following properties:
 
 *name*
 :   name of the item (string, required)
 
 *url*
 :   item URL (string, optional)
 
-The following tags are supported:
+To organize queues into sections, the YAML file should be written as an object
+with two properties:
 
-*complete*
-:   no new items will be added to the queue
+*sections*
+:   list of sections names (optional)
 
-*partial*
-:   not all items of the source queue are added to the queue
+*queues*
+:   list of queue objects (required)
+
+Sections names are specified using strings.  The order that the sections are
+listed determines the order that they are displayed on the queue sheet.
+
+Queue objects are as above, with an additional property to specify the
+section:
+
+*section*
+:   name of the section (string, optional)
+
+Queues that are not explicitly associated with a section are associated with
+an implicit default section.
+
+To make it easier to share queue files, imports are also supported.  Import
+another queue file using an import object instead of a queue object in a list
+of queues.  An import object has the following properties:
+
+*import*
+:   path to the queue file to import (string, required)
+
+*section*
+:   section to associate all of the imported queues with (string, optional)
+
+Paths are relative to the current file.  For example, simply specify the
+filename of the file to import when the file is in the same directory.
+
+When you specify *section*, the section must be defined in the current file.
+When you do not specify *section*, the sections of the imported queues are
+used, but they must also be defined in the current file.
 
 ## Template
 
-A LaTeX template is used to build the PDF, using XeTeX.  Unless specified
-otherwise, `template.tex` is used.
+YAML files specify the data, and templates determine how that data is
+displayed.  A LaTeX template is used to build the PDF, using XeTeX.  Unless
+specified otherwise, `template.tex` is used.
 
 It is a Jinja2-style template using the following syntax:
 
 Interpolations
 :   `<< section.name >>`
 
 Tags
-:   `<! if queue.isSplit !>`
+:   `<! if section.name !>`
 
 Comments
 :   `<# comment #>`
@@ -120,6 +158,9 @@ A section is an object with the following properties:
 *queues*
 :   list of queues
 
+Only sections that contain queues are passed to the template.  The *name*
+property of the default section is empty.
+
 A queue is an object with the following properties:
 
 *name*
@@ -128,24 +169,18 @@ A queue is an object with the following properties:
 *url*
 :   queue URL or empty string if no URL (string)
 
-*isSplit*
-:   *true* to display items on separate lines (boolean)
-
-*isPartial*
-:   *true* if the partial tag is set (boolean)
-
-*isComplete*
-:   *true* if the complete tag is set (boolean)
-
 *date*
 :   date or empty string if no date (string)
 
-*prevItem*
+*prev_item*
 :   previous item or empty string if not set (item)
 
-*nextItems*
+*next_items*
 :   list of next items (list of items)
 
+Queue tags are exposed as boolean properties prefixed with "tag_".  For
+example, a tag named "complete" is exposed as "tag_complete".
+
 An item is an object with the following properties:
 
 *name*

doc/queue-sheet.1.md

@@ -0,0 +1,11 @@
+---
+
+sections:
+  - Haskell
+
+queues:
+
+  - import: haskell-love-2020.yaml
+    section: Haskell
+  - import: zurihac-2020.yaml
+    section: Haskell