Mdoc.hs

-- |
--
-- Module      : Env.Mdoc
-- Copyright   : (c) 2026 Patrick Brisbin
-- License     : AGPL-3
-- Maintainer  : pbrisbin@gmail.com
-- Stability   : experimental
-- Portability : POSIX
--
-- A small, semi-representative, not type-checked example:
--
-- @
-- -- This input parser
-- parser :: Parser Error Options
-- parser = Option
--   \<$> var str \"FOO\" (help "Use foo")
--   \<*> switch \"DEBUG\" (help "Log more verbosely")
-- @
--
-- @
-- .\" Generates this mandoc source
-- .Sh ENVIRONMENT
-- The following environment variables affect the execution of
-- .Nm
-- :
-- .Bl -tag -width \"DEBUG\"
-- .It Cm DEBUG
-- Use foo
-- .It Cm FOO
-- Log more verbosely
-- @
--
-- Which renders something like:
--
-- @
-- ENVIRONMENT
--   The following environment variables affect the execution of thing:
--
--   DEBUG Log more verbosely
--
--   FOO   Use foo
-- @
--
-- For something more complete, see "Mdoc.GenSpec".
module Env.Mdoc
  ( addToMan1
  ) where

import Mdoc.Prelude

import Env.Internal.Free
import Env.Internal.Parser
import Mdoc.Gen.Described
import Mdoc.Gen.EnvVar
import Mdoc.Gen.Man1
import Mdoc.Gen.Optionality
import Mdoc.Optics

-- | Add environment variables to a 'Man1'
addToMan1 :: Parser e a -> Man1 -> Man1
addToMan1 p m = m & field @"environment" <>~ envs
 where
  envs = foldAlt varToEnvVar $ unParser p

varToEnvVar :: VarF e a -> [Described EnvVar]
varToEnvVar v =
  [ Described
      { item = EnvVar {names = pure $ varfName v, argument = Nothing}
      , optionality = maybe Required Defaulted (varfHelpDef v)
      , multiple = False
      , helpLines = nonEmpty . lines =<< varfHelp v
      }
  ]