add grouping, masking, and stopping (#8)

* remove weeder
* add grouping, masking, and stopping
* add parent GitHub.Workflow.Command module and docs
* release 0.0.1.0

.github/workflows/ci.yml

@@ -34,10 +34,6 @@ jobs:
         uses: freckle/stack-action@v5
         with:
           stack-arguments: --stack-yaml ${{ matrix.stack-yaml }}
-      - if: ${{ matrix.stack-yaml == 'stack.yaml' }}
-        uses: freckle/weeder-action@v2
-        with:
-          ghc-version: ${{ steps.stack.outputs.compiler-version }}
 
   lint:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -1,4 +1,13 @@
-## [_Unreleased_](https://github.com/freckle/github-workflow-commands/compare/v0.0.0.0...main)
+## [_Unreleased_](https://github.com/freckle/github-workflow-commands/compare/v0.0.1.0...main)
+
+## [v0.0.1.0](https://github.com/freckle/github-workflow-commands/compare/v0.0.0.0...v0.0.1.0)
+
+Additions:
+
+- Re-exporting overview module `GitHub.Workflow.Command`, which is now the
+  primary module for users to import and find documentation
+- Class `MonadCommand` which is now the recommended way to execute commands
+- Support for `group`, `add-mask`, `stop-commands` commands
 
 ## [v0.0.0.0](https://github.com/freckle/github-workflow-commands/tree/v0.0.0.0)
 

README.lhs

@@ -19,16 +19,16 @@ import Text.Markdown.Unlit ()
 -->
 
 ```haskell
-import qualified GitHub.Workflow.Command.Annotation as GH
-import Control.Lens
+import qualified GitHub.Workflow.Command as GH
+import Control.Lens ((&), (?~))
 ```
 
 An annotation is at minimum just a string.
 
 ```haskell
 example1 :: IO ()
 example1 =
-  GH.printByteStringLn $
+  GH.executeCommand $
     GH.error "Something failed."
 ```
 
@@ -47,15 +47,15 @@ someLocation =
 ```haskell
 example2 :: IO ()
 example2 =
-  GH.printByteStringLn $
+  GH.executeCommand $
     GH.warning "Something seems amiss here."
       & GH.location ?~ someLocation
 ```
 
 <!--
 ```haskell
 main :: IO ()
-main = example1 >> example2
+main = GH.suspendCommands $ example1 >> example2
 ```
 -->
 

github-workflow-commands.cabal

@@ -5,7 +5,7 @@ cabal-version: 1.18
 -- see: https://github.com/sol/hpack
 
 name:           github-workflow-commands
-version:        0.0.0.0
+version:        0.0.1.0
 synopsis:       GitHub Actions workflow commands
 description:    For printing workflow commands in GitHub Actions.
                 .
@@ -29,6 +29,7 @@ source-repository head
 
 library
   exposed-modules:
+      GitHub.Workflow.Command
       GitHub.Workflow.Command.Annotation
       GitHub.Workflow.Command.Annotation.Commands.Debug
       GitHub.Workflow.Command.Annotation.Commands.Error
@@ -43,6 +44,10 @@ library
       GitHub.Workflow.Command.Annotation.Position.Extent
       GitHub.Workflow.Command.Annotation.Position.Line
       GitHub.Workflow.Command.Annotation.Properties
+      GitHub.Workflow.Command.Execution
+      GitHub.Workflow.Command.Grouping
+      GitHub.Workflow.Command.Masking
+      GitHub.Workflow.Command.Stopping
       GitHub.Workflow.Command.Syntax
       GitHub.Workflow.Command.Syntax.Command
       GitHub.Workflow.Command.Syntax.Key
@@ -76,7 +81,8 @@ library
       TypeFamilies
   ghc-options: -fwrite-ide-info -Weverything -Wno-all-missed-specialisations -Wno-missed-specialisations -Wno-missing-exported-signatures -Wno-missing-import-lists -Wno-missing-local-signatures -Wno-monomorphism-restriction -Wno-safe -Wno-unsafe
   build-depends:
-      base <5
+      MonadRandom
+    , base <5
     , bytestring
     , containers
     , lens

library/GitHub/Workflow/Command.hs

@@ -0,0 +1,99 @@
+-- | Programs run by GitHub Actions can use workflow commands to communicate with the runner.
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions Workflow commands for GitHub Actions>
+module GitHub.Workflow.Command
+  ( -- * Executing commands
+    MonadCommand (..)
+  , PrintCommands (..)
+
+    -- * Commands
+  , ToCommand (..)
+
+    -- ** Setting a debug message
+  , Debug (..)
+  , debug
+
+    -- ** Setting a notice message
+  , Notice (..)
+  , notice
+
+    -- ** Setting a warning message
+  , Warning (..)
+  , warning
+
+    -- ** Setting an error message
+  , Error (..)
+  , error
+
+    -- ** Grouping log lines
+  , group
+  , GroupStart (..)
+  , GroupEnd (..)
+
+    -- ** Masking a value in a log
+  , AddMask (..)
+
+    -- ** Stopping and starting workflow commands
+  , suspendCommands
+  , stopCommands
+  , resumeCommands
+  , SuspendToken
+
+    -- * Location
+  , Location (..)
+  , HasLocationMaybe (..)
+
+    -- ** File
+  , File (..)
+  , inFile
+  , file
+
+    -- ** Position
+  , Position (..)
+  , position
+  , Extent (..)
+  , extent
+  , Columns (..)
+  , line
+  , startColumn
+  , endColumn
+  , Line (..)
+  , atLine
+  , Column (..)
+  , atColumn
+
+    -- * Anatomy of a command
+  , Command
+
+    -- ** Name
+  , Name (..)
+  , HasName (..)
+
+    -- ** Message
+  , Message (..)
+  , HasMessage (..)
+
+    -- ** Properties
+  , Properties
+  , HasProperties (..)
+  , Key (..)
+  , Value (..)
+  ) where
+
+import GitHub.Workflow.Command.Annotation.Commands.Debug
+import GitHub.Workflow.Command.Annotation.Commands.Error
+import GitHub.Workflow.Command.Annotation.Commands.Notice
+import GitHub.Workflow.Command.Annotation.Commands.Warning
+import GitHub.Workflow.Command.Annotation.File
+import GitHub.Workflow.Command.Annotation.Location
+import GitHub.Workflow.Command.Annotation.Position
+import GitHub.Workflow.Command.Annotation.Position.Column
+import GitHub.Workflow.Command.Annotation.Position.Columns
+import GitHub.Workflow.Command.Annotation.Position.Extent
+import GitHub.Workflow.Command.Annotation.Position.Line
+import GitHub.Workflow.Command.Execution
+import GitHub.Workflow.Command.Grouping
+import GitHub.Workflow.Command.Masking
+import GitHub.Workflow.Command.Stopping
+import GitHub.Workflow.Command.Syntax

library/GitHub/Workflow/Command/Annotation.hs

@@ -48,6 +48,7 @@ module GitHub.Workflow.Command.Annotation
   , atColumn
 
     -- * Output
+  , MonadCommand (..)
   , ToCommand (..)
   , toCommand
   , ToByteString (..)
@@ -66,11 +67,7 @@ import GitHub.Workflow.Command.Annotation.Position.Columns
 import GitHub.Workflow.Command.Annotation.Position.Extent
 import GitHub.Workflow.Command.Annotation.Position.Line
 import GitHub.Workflow.Command.Annotation.Properties
-import GitHub.Workflow.Command.Syntax
-  ( FromMessage (..)
-  , Message (..)
-  , ToByteString (..)
-  , ToCommand (..)
-  , printByteStringLn
-  , toCommand
-  )
+import GitHub.Workflow.Command.Execution
+import GitHub.Workflow.Command.Syntax.Command
+import GitHub.Workflow.Command.Syntax.Message
+import GitHub.Workflow.Command.Syntax.ToByteString

library/GitHub/Workflow/Command/Annotation/Commands/Debug.hs

@@ -16,6 +16,10 @@ import GitHub.Workflow.Command.Syntax
   )
 import GitHub.Workflow.Command.Syntax qualified as Syntax
 
+-- | Prints a debug message to the log
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-debug-message Setting a debug message>
 newtype Debug = Debug
   { message :: Message
   }

library/GitHub/Workflow/Command/Annotation/Commands/Error.hs

@@ -18,6 +18,13 @@ import GitHub.Workflow.Command.Syntax
   )
 import GitHub.Workflow.Command.Syntax qualified as Syntax
 
+-- | Creates an error message and prints the message to the log
+--
+-- The message can be associated with a particular file in your repository,
+-- and optionally also a position within the file. See 'HasLocationMaybe'.
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-error-message Setting an error message>
 data Error = Error
   { message :: Message
   , properties :: Properties

library/GitHub/Workflow/Command/Annotation/Commands/Notice.hs

@@ -18,6 +18,13 @@ import GitHub.Workflow.Command.Syntax
   )
 import GitHub.Workflow.Command.Syntax qualified as Syntax
 
+-- | Creates a notice message and prints the message to the log
+--
+-- The message can be associated with a particular file in your repository,
+-- and optionally also a position within the file. See 'HasLocationMaybe'.
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-notice-message Setting a notice message>
 data Notice = Notice
   { message :: Message
   , properties :: Properties

library/GitHub/Workflow/Command/Annotation/Commands/Warning.hs

@@ -18,6 +18,13 @@ import GitHub.Workflow.Command.Syntax
   )
 import GitHub.Workflow.Command.Syntax qualified as Syntax
 
+-- | Creates a warning message and prints the message to the log
+--
+-- The message can be associated with a particular file in your repository,
+-- and optionally also a position within the file. See 'HasLocationMaybe'.
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-a-warning-message Setting a warning message>
 data Warning = Warning
   { message :: Message
   , properties :: Properties

library/GitHub/Workflow/Command/Execution.hs

@@ -0,0 +1,35 @@
+module GitHub.Workflow.Command.Execution
+  ( MonadCommand (..)
+  , PrintCommands (..)
+  ) where
+
+import Control.Applicative (Applicative)
+import Control.Monad (Monad)
+import Control.Monad.IO.Class (MonadIO, liftIO)
+import Data.Function ((.))
+import Data.Functor (Functor)
+import GitHub.Workflow.Command.Syntax
+import System.IO (IO)
+
+-- | Monadic context in which GitHub workflow commands may be executed
+--
+-- * For the most basic uses, use the 'IO' instance, which prints commands to 'System.IO.stdout'.
+--
+-- * For custom monads that support 'MonadIO', you may derive 'MonadCommand' via 'PrintCommands'
+--   to get the same behavior that 'IO' exhibits.
+--
+-- * A program that wishes to accommodate running in both GitHub and non-GitHub contexts
+--   may wish to define a more sophisicated 'MonadCommand' instance that prints GitHub
+--   workflow commands only when the @GITHUB_ACTIONS@ environment variable is present,
+--   and otherwise takes some other more context-appropriate action.
+class Monad m => MonadCommand m where
+  executeCommand :: ToCommand a => a -> m ()
+
+instance MonadCommand IO where
+  executeCommand = printByteStringLn . toCommand
+
+newtype PrintCommands m a = PrintCommands (m a)
+  deriving newtype (Functor, Applicative, Monad, MonadIO)
+
+instance MonadIO m => MonadCommand (PrintCommands m) where
+  executeCommand = liftIO . executeCommand

library/GitHub/Workflow/Command/Grouping.hs

@@ -0,0 +1,42 @@
+module GitHub.Workflow.Command.Grouping
+  ( group
+  , GroupStart (..)
+  , GroupEnd (..)
+  ) where
+
+import Control.Applicative ((*>), (<*))
+import Control.Lens ((.~))
+import Data.Function ((.))
+import Data.Text (Text)
+import GitHub.Workflow.Command.Execution
+import GitHub.Workflow.Command.Syntax
+
+-- | Creates an expandable group in the log
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#grouping-log-lines Grouping log lines>
+group
+  :: MonadCommand m
+  => Text
+  -- ^ Group title
+  -> m a
+  -- ^ Anything printed within this action will be
+  --   nested inside an expandable entry in the log
+  -> m a
+group title x =
+  executeCommand GroupStart {title}
+    *> x
+    <* executeCommand GroupEnd
+
+-- | Starts a 'group'
+newtype GroupStart = GroupStart {title :: Text}
+
+instance ToCommand GroupStart where
+  addToCommand GroupStart {title} =
+    (name .~ "group") . (message .~ Message title)
+
+-- | Ends a 'group'
+data GroupEnd = GroupEnd
+
+instance ToCommand GroupEnd where
+  addToCommand GroupEnd = name .~ "endgroup"

library/GitHub/Workflow/Command/Masking.hs

@@ -0,0 +1,21 @@
+module GitHub.Workflow.Command.Masking
+  ( AddMask (..)
+  ) where
+
+import Control.Lens ((.~))
+import Data.Function ((.))
+import Data.Text (Text)
+import GitHub.Workflow.Command.Syntax
+
+-- | Prevents a string or variable from being printed in the log
+--
+-- GitHub documentation:
+-- <https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#masking-a-value-in-a-log Masking a value in a log>
+newtype AddMask = AddMask
+  { value :: Text
+  -- ^ An environment variable or string
+  }
+
+instance ToCommand AddMask where
+  addToCommand AddMask {value} =
+    (name .~ "add-mask") . (message .~ Message value)