env-guard 0.2 → 0.2.1

raw patch · 7 files changed

+119/−66 lines, 7 filesdep −doctestdep ~basePVP: major bump suggested

API removals or changes: PVP suggests a major version bump

Dependencies removed: doctest

Dependency ranges changed: base

API changes (from Hackage documentation)

Files

• CHANGELOG.md +22/−4
• LICENSE +1/−1
• README.md +58/−7
• env-guard.cabal +15/−17
• src/System/Environment/Guard.hs +7/−1
• src/System/Environment/Guard/Lifted.hs +16/−15
• test/doctest/Main.hs +0/−21

@@ -1,14 +1,32 @@ # Revision history for env-guard -## 0.2 -- 2022-07-02+All notable changes to this project will be documented in this file. -* Rename `guardExpected` functions to `guardEquals` to better match ExpectEnv type.+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),+and this project adheres to the [Haskell Package Versioning Policy](https://pvp.haskell.org/). -## 0.1.1 -- 2022-07-01+## [0.2.1] -- 2025-07-17+### Changed+* Fixed `Show ExpectEnv` instance constructor name.+* Explicitly Re-export `ExpectEnv` data constructors from+  `System.Environment.Guard`.+* Doctests use cabal external command, hence no longer part of test suite.+  Therefore `--enable-tests` will no longer incur a GHC dependency. +## [0.2] -- 2022-07-02+### Changed+* Rename `guardExpected` functions to `guardEquals` to better match ExpectEnv type.++## [0.1.1] -- 2022-07-01+### Added * Add higher-level `withGuard` combinator. * Add "OrElse" pattern. -## 0.1 -- 2022-06-29+## [0.1] -- 2022-06-29  * First version. Released on an unsuspecting world.++[0.2.1]: https://github.com/tbidne/env-guard/compare/0.2..0.2.1+[0.2]: https://github.com/tbidne/env-guard/compare/0.1.1..0.2+[0.1.1]: https://github.com/tbidne/env-guard/compare/0.1..0.1.1+[0.1]: https://github.com/tbidne/env-guard/releases/tag/0.1

@@ -1,6 +1,6 @@ MIT License -Copyright (c) 2022 Thomas Bidne+Copyright (c) 2022-2025 Thomas Bidne  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal

@@ -3,14 +3,65 @@ # env-guard  [![Hackage](https://img.shields.io/hackage/v/env-guard)](https://hackage.haskell.org/package/env-guard)+[![ci](http://img.shields.io/github/actions/workflow/status/tbidne/env-guard/ci.yaml?branch=main)](https://github.com/tbidne/env-guard/actions/workflows/ci.yaml) [![MIT](https://img.shields.io/github/license/tbidne/env-guard?color=blue)](https://opensource.org/licenses/MIT) -[![nix](https://img.shields.io/github/workflow/status/tbidne/env-guard/nix/main?label=nix%209.2&&logo=nixos&logoColor=85c5e7&labelColor=2f353c)](https://github.com/tbidne/env-guard/actions/workflows/nix_ci.yaml)-[![stack](https://img.shields.io/github/workflow/status/tbidne/env-guard/stack/main?label=stack%2019&logoColor=white&labelColor=2f353c)](https://github.com/tbidne/env-guard/actions/workflows/stack_ci.yaml)-[![style](https://img.shields.io/github/workflow/status/tbidne/env-guard/style/main?label=style&logoColor=white&labelColor=2f353c)](https://github.com/tbidne/env-guard/actions/workflows/style_ci.yaml)+</div> -[![8.10](https://img.shields.io/github/workflow/status/tbidne/env-guard/8.10/main?label=8.10&logo=haskell&logoColor=904d8c&labelColor=2f353c)](https://github.com/tbidne/env-guard/actions/workflows/ghc_8-10.yaml)-[![9.0](https://img.shields.io/github/workflow/status/tbidne/env-guard/9.0/main?label=9.0&logo=haskell&logoColor=904d8c&labelColor=2f353c)](https://github.com/tbidne/env-guard/actions/workflows/ghc_9-0.yaml)-[![9.2](https://img.shields.io/github/workflow/status/tbidne/env-guard/9.2/main?label=9.2&logo=haskell&logoColor=904d8c&labelColor=2f353c)](https://github.com/tbidne/env-guard/actions/workflows/ghc_9-2.yaml)+# Introduction -</div>+This package is used to guard `IO` actions behind an environment variable.++# Examples++## Simple++```haskell+guardSet :: String -> IO a -> IO (Maybe a)++-- Run function if env var AppEnv is set (to anything).+guardSet "AppEnv" runProd+```++```haskell+guardEquals :: String -> String -> IO a -> IO (Maybe a)++-- Run function if env var AppEnv is set to "prod" (case-insensitive).+guardEquals "AppEnv" "prod" runProd+```++```haskell+guardPredicate :: String -> (String -> Bool) -> IO a -> IO (Maybe a)++-- Run function if env var AppEnv's value satisfies the predicate.+guardPredicate "AppEnv" (\s -> s == "staging" || s == "dev") runTests+```++## Higher-Level Combinators++```haskell+-- withGuard uses the 'ExpectEnv' type to determine which of the above three+-- functions to call.+withGuard :: String -> ExpectEnv -> IO a -> IO (Maybe a)++-- equivalent to 'guardSet "BUILD_DOCS" buildDocs'.+withGuard "BUILD_DOCS" ExpectEnvSet buildDocs++-- equivalent to 'guardEquals "BUILD_DOCS" "true" buildDocs'.+withGuard "BUILD_DOCS" (ExpectEnvEquals "true") buildDocs+```++```haskell+-- guardOrElse runs one of two IO actions, depending on the success of the env+-- variable lookup.+guardOrElse :: String -> ExpectEnv -> IO a -> IO e -> IO (Either e a)++-- Runs runA if DO_A is set; otherwise runs runB.+guardOrElse "DO_A" ExpectEnvSet runA runB++-- guardOrElse' specialized to the same type.+guardOrElse' :: String -> ExpectEnv -> IO a -> IO a -> IO a++-- Runs runTests if RUN_TESTS is set; otherwise prints a message.+guardOrElse' "RUN_TESTS" ExpectEnvSet runTests (putStrLn "*** Tests Disabled ***")+```

@@ -1,10 +1,19 @@ cabal-version:      2.4 name:               env-guard-version:            0.2+version:            0.2.1 license:            MIT license-file:       LICENSE-tested-with:        GHC ==8.10.7 || ==9.0.2 || ==9.2.3-copyright:          2022 Thomas Bidne+tested-with:+  GHC ==8.10.7+   || ==9.0.2+   || ==9.2.8+   || ==9.4.8+   || ==9.6.6+   || ==9.8.4+   || ==9.10.2+   || ==9.12.2++copyright:          2022-2025 Thomas Bidne author:             Thomas Bidne maintainer:         tbidne@protonmail.com homepage:           https://github.com/tbidne/env-guard/@@ -18,9 +27,8 @@   result.  category:           System, Environment-extra-source-files:-  CHANGELOG.md-  README.md+extra-source-files: README.md+extra-doc-files:    CHANGELOG.md  source-repository head   type:     git@@ -31,16 +39,6 @@     System.Environment.Guard     System.Environment.Guard.Lifted -  build-depends:    base >=4.14.0.0 && <4.17+  build-depends:    base >=4.14.0.0 && <4.22   hs-source-dirs:   src-  default-language: Haskell2010--test-suite doctest-  type:             exitcode-stdio-1.0-  main-is:          Main.hs-  build-depends:-    , base-    , doctest  >=0.16.3 && <0.21--  hs-source-dirs:   test/doctest   default-language: Haskell2010

@@ -28,7 +28,13 @@   ) where -import System.Environment.Guard.Lifted (ExpectEnv)+import System.Environment.Guard.Lifted+  ( ExpectEnv+      ( ExpectEnvEquals,+        ExpectEnvPredicate,+        ExpectEnvSet+      ),+  ) import System.Environment.Guard.Lifted qualified as Lifted  -- $setup

@@ -28,8 +28,9 @@ where  import Control.Monad (void)-import Control.Monad.IO.Class (MonadIO (..))+import Control.Monad.IO.Class (MonadIO (liftIO)) import Data.Char (toLower)+import GHC.Show (appPrec) import System.Environment (lookupEnv)  -- $setup@@ -61,12 +62,12 @@   showsPrec _ ExpectEnvSet = showString "ExpectEnvSet"   showsPrec i (ExpectEnvEquals s) =     showParen-      (i >= 11)-      (showString "ExpectEnvEquals " . showsPrec 11 s)+      (i >= appPrec)+      (showString "ExpectEnvEquals " . showsPrec appPrec s)   showsPrec i (ExpectEnvPredicate _) =     showParen-      (i >= 11)-      (showString "ExpectEnvEquals " . showString "_")+      (i >= appPrec)+      (showString "ExpectEnvPredicate " . showString "<function>")  -- | Guards an action behind an environment variable according to -- the given expectation.@@ -81,7 +82,7 @@ -- Just () -- -- @since 0.1.1-withGuard :: MonadIO m => String -> ExpectEnv -> m a -> m (Maybe a)+withGuard :: (MonadIO m) => String -> ExpectEnv -> m a -> m (Maybe a) withGuard var expect m =   case expect of     ExpectEnvSet -> guardSet var m@@ -91,7 +92,7 @@ -- | Variant of 'withGuard' that ignores the return value. -- -- @since 0.1.1-withGuard_ :: MonadIO m => String -> ExpectEnv -> m a -> m ()+withGuard_ :: (MonadIO m) => String -> ExpectEnv -> m a -> m () withGuard_ var expect = void . withGuard var expect  -- | @guardOrElse var expect m1 m2@ is equivalent to@@ -107,7 +108,7 @@ -- -- @since 0.1.1 guardOrElse ::-  MonadIO m =>+  (MonadIO m) =>   -- | The environment variable.   String ->   -- | The expectation.@@ -144,7 +145,7 @@ -- -- @since 0.1.1 guardOrElse' ::-  MonadIO m =>+  (MonadIO m) =>   -- | The environment variable.   String ->   -- | The expectation.@@ -176,13 +177,13 @@ -- Just True -- -- @since 0.1-guardSet :: MonadIO m => String -> m a -> m (Maybe a)+guardSet :: (MonadIO m) => String -> m a -> m (Maybe a) guardSet var = guardPredicate var (const True)  -- | Variant of 'guardSet' that ignores the return value. -- -- @since 0.1-guardSet_ :: MonadIO m => String -> m a -> m ()+guardSet_ :: (MonadIO m) => String -> m a -> m () guardSet_ var = void . guardSet var  -- | @'guardEquals' var expected io@ runs @io@ iff@@ -209,19 +210,19 @@ -- Just True -- -- @since 0.2-guardEquals :: MonadIO m => String -> String -> m a -> m (Maybe a)+guardEquals :: (MonadIO m) => String -> String -> m a -> m (Maybe a) guardEquals var expected = guardPredicate var (eqCaseInsensitive expected)  -- | Variant of 'guardEquals_' that ignores the return value. -- -- @since 0.2-guardEquals_ :: MonadIO m => String -> String -> m a -> m ()+guardEquals_ :: (MonadIO m) => String -> String -> m a -> m () guardEquals_ var expected = void . guardEquals var expected  -- | Variant of 'guardPredicate' that ignores the return value. -- -- @since 0.1-guardPredicate_ :: MonadIO m => String -> (String -> Bool) -> m a -> m ()+guardPredicate_ :: (MonadIO m) => String -> (String -> Bool) -> m a -> m () guardPredicate_ var p = void . guardPredicate var p  -- | This is the most general way to check an environment variable.@@ -245,7 +246,7 @@ -- Just True -- -- @since 0.1-guardPredicate :: MonadIO m => String -> (String -> Bool) -> m a -> m (Maybe a)+guardPredicate :: (MonadIO m) => String -> (String -> Bool) -> m a -> m (Maybe a) guardPredicate var p io =   liftIO (lookupEnv var)     >>= \case

@@ -1,21 +0,0 @@-module Main (main) where--import System.Environment (lookupEnv)-import Test.DocTest (doctest)-import Prelude--main :: IO ()-main = do-  shouldRun <- lookupEnv "RUN_DOCTEST"-  case shouldRun of-    Just _ -> doctest args-    _ -> putStrLn "*** Doctests Disabled ***"-  where-    args = files--files :: [String]-files =-  [ "-isrc",-    "src/System/Environment/Guard.hs",-    "src/System/Environment/Guard/Lifted.hs"-  ]