Add runConfig

[kalhauge]

• runConfig is like run but it allows the user to specify their
  own config options. One usage is like this:

main :: IO ()
main = do
  withUtf8 $
    Rib.runConfig [reldir|content|] [reldir|dest|]
      (option (maybeReader parseAbsDir) $
        long "base-url"
        <> help "Set the base url of the server"
        <> value [absdir|/|]
        <> showDefault
        <> hidden
        <> metavar "BASEURL"
      )
      generateSite

-- | Generate a site using a base-url
generateSite :: Path Abs Dir -> Action ()

This aims to address part of the issue in #142. Only a suggestion.

[srid]

How would this behave if I added a sub-command to configParser? What would the rib-sample --help look like?

[kalhauge]

I implemented an example use in kalhauge/rib-sample@8c70b33.

The rib-sample --help looks like this:

Usage: rib-sample COMMAND
  Rib static site generator CLI

Available options:
  --publish                Publish the webpage (ei. ignore dafts)
  --base-url BASEURL       Set the base url of the server (default: "/")
  -h,--help                Show this help text

Available commands:
  generate                 Run one-off generation of static files
  watch                    Watch the source directory, and generate when it
                           changes
  serve                    Like watch, but also starts a HTTP server

[srid]

I implemented an example use in kalhauge/rib-sample@8c70b33.

Thanks. Consider this alternative approach (diff applied on your branch):

diff --git a/src/Main.hs b/src/Main.hs
index 14847e3..801c00e 100644
--- a/src/Main.hs
+++ b/src/Main.hs
@@ -27,6 +27,7 @@ import Options.Applicative
 import Path
 import Rib (IsRoute, Pandoc)
 import qualified Rib
+import qualified Rib.App
 import qualified Rib.Parser.Pandoc as Pandoc
 
 -- | Route corresponding to each generated static page.
@@ -59,7 +60,16 @@ instance IsRoute Route where
 -- provided by Rib to do the actual generation of your static site.
 main :: IO ()
 main = withUtf8 $ do
-  Rib.runConfig [reldir|content|] [reldir|dest|] parseConfig generateSite
+  execParser opts >>= \(config, ribCmd) ->
+    Rib.runWith [reldir|content|] [reldir|dest|] (generateSite config) ribCmd
+  where
+    opts =
+      info
+        (cliParser <**> helper)
+        (fullDesc <> progDesc "My static site generator")
+
+cliParser :: Parser (Config, Rib.App.Command)
+cliParser = (,) <$> parseConfig <*> Rib.App.commandParser
 
 parseConfig :: Parser Config
 parseConfig = do

The benefit here is that it composes Rib's CLI parser (Rib.App.commandParser); the user has complete freedom as to how to define their CLI arguments. If we add runConfig, then the API will become more framework like. The compose approach has other benefits like you can customize the CLI in a fashion that runConfig doesn't allow; for eg., move the whole rib CLI to a sub-command (neuron does this).

---

In regards to nomenclature, this is more about being able to customize the CLI, rather than any configuration. The main entry point is under user's control; and they can do whatever they want, before delegating to rib. Rib shouldn't have to specify any particular configuration mechanism. Whether they read from the environment, CLI arguments or config files - it would be up to the user.

[srid]

However, playing devil's advocate - it might be worth allowing custom user config in the CliConfig of #147, as CliConfig is stored in Shake via addShakeExtra anyway (to be retrieved via getShakeExtra from anywhere in the Action monad).

Something like CliConfig custom = CliConfig { ..., userConfig :: custom }.

It would allow retrieval of that custom config via Shake's getShakeExtra as well, which is just nicer, i.e., to be able to access the config from anywhere in the Action monad.

EDIT: Ah, but you can store multiple kinds of values by invoking addShakeExtra more than once. So this can be done in userland too.

[kalhauge]

All valid points!

It would however be nice to have these common work patterns explained in the documentation.

I do see that you have made a lot of changes, so I think this pull request is obsolete :)

[srid]

It would however be nice to have these common work patterns explained in the documentation.

Yes, I've been meaning to create a 'rib guide' site similar to neuron.srid.ca. The project board for that is here: https://github.com/srid/rib/projects/2