From b33dee75db1af625f7163c7610484451be67c92a Mon Sep 17 00:00:00 2001
From: Jacob Lagares Pozo <jlagarespo@protonmail.com>
Date: Thu, 1 Dec 2022 23:57:09 +0100
Subject: [PATCH] Write documentation and bump version number.

---
 advlib.cabal        |  5 ++++-
 package.yaml        |  5 ++++-
 readme              |  1 +
 src/Advent.hs       | 20 ++++++++++++++++----
 src/Advent/Input.hs |  3 +++
 5 files changed, 28 insertions(+), 6 deletions(-)
 create mode 100644 readme
 create mode 100644 src/Advent/Input.hs

diff --git a/advlib.cabal b/advlib.cabal
index a1d03e8..8a6bb3e 100644
--- a/advlib.cabal
+++ b/advlib.cabal
@@ -5,16 +5,19 @@ cabal-version: 2.2
 -- see: https://github.com/sol/hpack
 
 name:           advlib
-version:        0.1.0.0
+version:        0.2.0.0
 description:    Advent of code boilerplate.
 author:         Jacob Lagares Pozo
 maintainer:     jlagarespo@protonmail.com
 license:        Unlicense
 build-type:     Simple
+extra-source-files:
+    readme
 
 library
   exposed-modules:
       Advent
+      Advent.Input
       Advent.List
   other-modules:
       Paths_advlib
diff --git a/package.yaml b/package.yaml
index 89dd0ba..7fa5ef1 100644
--- a/package.yaml
+++ b/package.yaml
@@ -1,9 +1,12 @@
 name: advlib
-version: 0.1.0.0
+version: 0.2.0.0
 license: Unlicense
 author: "Jacob Lagares Pozo"
 maintainer: "jlagarespo@protonmail.com"
 
+extra-source-files:
+- readme
+
 description: Advent of code boilerplate.
 
 dependencies:
diff --git a/readme b/readme
new file mode 100644
index 0000000..866d425
--- /dev/null
+++ b/readme
@@ -0,0 +1 @@
+A simple library to help you acquire your Advent of Code input. See haddock docs for usage.
diff --git a/src/Advent.hs b/src/Advent.hs
index bbf895e..9dd5563 100644
--- a/src/Advent.hs
+++ b/src/Advent.hs
@@ -1,5 +1,7 @@
+-- | The 'AOC_SESSION' environment variable must be set to the "session" cookie that
+-- adventofcode.com gives you upon logging in.
 {-# LANGUAGE FlexibleContexts #-}
-module Advent (runAdvent, getDay, cacheAllDays) where
+module Advent (Advent, runAdvent, getDay, cacheAllDays) where
 
 import Control.Concurrent (threadDelay)
 
@@ -29,7 +31,12 @@ import System.IO (BufferMode(NoBuffering), hSetBuffering, stdout)
 import Data.Version (showVersion)
 import Paths_advlib (version)
 
-runAdvent :: MonadIO m => ReaderT Manager m b -> m b
+-- | The 'Advent' monad carries all the necessary information to communicate with the Advent of Code
+-- website.
+type Advent = ReaderT Manager
+
+-- | Run an 'Advent' monad 'f' in a MonadIO context.
+runAdvent :: MonadIO m => Advent m b -> m b
 runAdvent f = do
   liftIO $ hSetBuffering stdout NoBuffering
   man <- liftIO $ newManager tlsManagerSettings
@@ -62,6 +69,7 @@ download url = do
     past = UTCTime (ModifiedJulianDay 56200) (secondsToDiffTime 0)
     future = UTCTime (ModifiedJulianDay 562000) (secondsToDiffTime 0)
 
+-- | Retrieve the input for 'day' from 'year'.
 getDay :: (MonadReader Manager m, MonadIO m, MonadThrow m) => Int -> Int -> m String
 getDay year day = do
   cached <- liftIO $ doesFileExist dayCache
@@ -75,8 +83,8 @@ getDay year day = do
       pure day
 
   where
-    cacheDir   = "aocache/"
-    dayCache   = cacheDir <> show year <> "." <> show day
+    cacheDir = "aocache/"
+    dayCache = cacheDir <> show year <> "." <> show day
 
     retreiveDay = do
       day <- download $ "https://adventofcode.com/" <> show year <> "/day/" <> show day <> "/input"
@@ -101,5 +109,9 @@ getDay year day = do
         liftIO $ threadDelay 1000000
         countdown dest
 
+-- | Download and cache all days from all years. Not recommended in general since 'getDay' will
+-- already download the appropriate files whenever necessary. You may use this function if, for
+-- example, you're not going to have internet access in the future, and would like to cache all the
+-- days in advance for offline use.
 cacheAllDays :: (MonadReader Manager m, MonadIO m, MonadThrow m) => m ()
 cacheAllDays = sequence_ [getDay year day | year <- [2015..2021], day <- [1..25]]
diff --git a/src/Advent/Input.hs b/src/Advent/Input.hs
new file mode 100644
index 0000000..3fce748
--- /dev/null
+++ b/src/Advent/Input.hs
@@ -0,0 +1,3 @@
+module Advent.Input where
+
+-- TODO: Fully automatic input format detection and parsing.
-- 
2.11.4.GIT