packages feed

core-program 0.6.2.2 → 0.6.3.0

raw patch · 4 files changed

+60/−8 lines, 4 filesPVP: major bump suggested

API removals or changes: PVP suggests a major version bump

API changes (from Hackage documentation)

- Core.Program: Context :: MVar Rope -> Int -> Bool -> Version -> Config -> [Exporter] -> Parameters -> MVar ExitCode -> MVar Time -> MVar Verbosity -> TQueue (Maybe Rope) -> TQueue (Maybe Datum) -> Maybe Forwarder -> TVar (Set ThreadId) -> MVar Datum -> MVar τ -> Context τ
- Core.Program: Datum :: Maybe Span -> Rope -> Maybe Rope -> Time -> Maybe Trace -> Maybe Span -> Maybe Int64 -> Map JsonKey JsonValue -> Datum
- Core.Program: Debug :: Verbosity
- Core.Program: Exporter :: Rope -> (Config -> Config) -> (forall τ. Context τ -> IO Forwarder) -> Exporter
- Core.Program: Forwarder :: ([Datum] -> IO ()) -> Forwarder
- Core.Program: Internal :: Verbosity
- Core.Program: None :: None
- Core.Program: Output :: Verbosity
- Core.Program: Program :: ReaderT (Context τ) IO α -> Program τ α
- Core.Program: Span :: Rope -> Span
- Core.Program: Trace :: Rope -> Trace
- Core.Program: Verbose :: Verbosity
- Core.Program: [$sel:applicationDataFrom:Context] :: Context τ -> MVar τ
- Core.Program: [$sel:attachedMetadataFrom:Datum] :: Datum -> Map JsonKey JsonValue
- Core.Program: [$sel:codenameFrom:Exporter] :: Exporter -> Rope
- Core.Program: [$sel:commandLineFrom:Context] :: Context τ -> Parameters
- Core.Program: [$sel:currentDatumFrom:Context] :: Context τ -> MVar Datum
- Core.Program: [$sel:currentScopeFrom:Context] :: Context τ -> TVar (Set ThreadId)
- Core.Program: [$sel:durationFrom:Datum] :: Datum -> Maybe Int64
- Core.Program: [$sel:exitSemaphoreFrom:Context] :: Context τ -> MVar ExitCode
- Core.Program: [$sel:initialConfigFrom:Context] :: Context τ -> Config
- Core.Program: [$sel:initialExportersFrom:Context] :: Context τ -> [Exporter]
- Core.Program: [$sel:outputChannelFrom:Context] :: Context τ -> TQueue (Maybe Rope)
- Core.Program: [$sel:parentIdentifierFrom:Datum] :: Datum -> Maybe Span
- Core.Program: [$sel:programNameFrom:Context] :: Context τ -> MVar Rope
- Core.Program: [$sel:serviceNameFrom:Datum] :: Datum -> Maybe Rope
- Core.Program: [$sel:setupActionFrom:Exporter] :: Exporter -> forall τ. Context τ -> IO Forwarder
- Core.Program: [$sel:setupConfigFrom:Exporter] :: Exporter -> Config -> Config
- Core.Program: [$sel:spanIdentifierFrom:Datum] :: Datum -> Maybe Span
- Core.Program: [$sel:spanNameFrom:Datum] :: Datum -> Rope
- Core.Program: [$sel:spanTimeFrom:Datum] :: Datum -> Time
- Core.Program: [$sel:startTimeFrom:Context] :: Context τ -> MVar Time
- Core.Program: [$sel:telemetryChannelFrom:Context] :: Context τ -> TQueue (Maybe Datum)
- Core.Program: [$sel:telemetryForwarderFrom:Context] :: Context τ -> Maybe Forwarder
- Core.Program: [$sel:telemetryHandlerFrom:Forwarder] :: Forwarder -> [Datum] -> IO ()
- Core.Program: [$sel:terminalColouredFrom:Context] :: Context τ -> Bool
- Core.Program: [$sel:terminalWidthFrom:Context] :: Context τ -> Int
- Core.Program: [$sel:traceIdentifierFrom:Datum] :: Datum -> Maybe Trace
- Core.Program: [$sel:verbosityLevelFrom:Context] :: Context τ -> MVar Verbosity
- Core.Program: [$sel:versionFrom:Context] :: Context τ -> Version
- Core.Program: configure :: Version -> τ -> Config -> IO (Context τ)
- Core.Program: data Context τ
- Core.Program: data Datum
- Core.Program: data Exporter
- Core.Program: data Forwarder
- Core.Program: data None
- Core.Program: data Verbosity
- Core.Program: emptyDatum :: Datum
- Core.Program: fmapContext :: (τ1 -> τ2) -> Context τ1 -> IO (Context τ2)
- Core.Program: getContext :: Program τ (Context τ)
- Core.Program: handleCommandLine :: Context τ -> IO (Context τ)
- Core.Program: handleTelemetryChoice :: Context τ -> IO (Context τ)
- Core.Program: handleVerbosityLevel :: Context τ -> IO (MVar Verbosity)
- Core.Program: isNone :: None -> Bool
- Core.Program: newtype Program τ α
- Core.Program: newtype Span
- Core.Program: newtype Trace
- Core.Program: subProgram :: Context τ -> Program τ α -> IO α
- Core.Program: unProgram :: Program τ α -> ReaderT (Context τ) IO α
- Core.Program: unSpan :: Span -> Rope
- Core.Program: unTrace :: Trace -> Rope
+ Core.Program.Execute: changeProgram :: υ -> Program υ α -> Program τ α

Files

core-program.cabal view
@@ -5,7 +5,7 @@ -- see: https://github.com/sol/hpack  name:           core-program-version:        0.6.2.2+version:        0.6.3.0 synopsis:       Opinionated Haskell Interoperability description:    A library to help build command-line programs, both tools and                 longer-running daemons.@@ -22,12 +22,12 @@ bug-reports:    https://github.com/aesiniath/unbeliever/issues author:         Andrew Cowie <istathar@gmail.com> maintainer:     Andrew Cowie <istathar@gmail.com>-copyright:      © 2018-2022 Athae Eredh Siniath and Others+copyright:      © 2018-2023 Athae Eredh Siniath and Others license:        MIT license-file:   LICENSE build-type:     Simple tested-with:-    GHC == 8.10.7, GHC == 9.2.4+    GHC == 8.10.7, GHC == 9.2.5  source-repository head   type: git
lib/Core/Program.hs view
@@ -1,4 +1,4 @@-{-# OPTIONS_HADDOCK not-home #-}+{-# OPTIONS_HADDOCK not-home, prune #-}  -- actually, they're there to group implementation too, but hey. @@ -20,8 +20,7 @@       -- |       -- A top-level Program type giving you unified access to logging, concurrency,       -- and more.-        module Core.Program.Context-    , module Core.Program.Execute+      module Core.Program.Execute     , module Core.Program.Threads     , module Core.Program.Unlift     , module Core.Program.Metadata@@ -49,7 +48,6 @@ where  import Core.Program.Arguments-import Core.Program.Context import Core.Program.Exceptions import Core.Program.Execute import Core.Program.Logging
lib/Core/Program/Context.hs view
@@ -310,7 +310,8 @@ getContext :: Program τ (Context τ) getContext = do     context <- ask-    return context+    pure context+{-# INLINABLE getContext #-}  {- | Run a subprogram from within a lifted @IO@ block.
lib/Core/Program/Execute.hs view
@@ -77,6 +77,7 @@     , getConsoleWidth     , getApplicationState     , setApplicationState+    , changeProgram        -- * Useful actions     , outputEntire@@ -117,6 +118,7 @@     ( MVar     , modifyMVar_     , newEmptyMVar+    , newMVar     , putMVar     , readMVar     , tryPutMVar@@ -581,6 +583,57 @@     liftIO $ do         let v = applicationDataFrom context         modifyMVar_ v (\_ -> pure user)++{- |+Sometimes you need to change the type of the application state from what is+present at the top-level when the program starts.++While the original intent of providing an initial value of type @τ@ to+'configure' was that your application state would be available at startup, an+alternative pattern is to form the application state as the first actions that+your program takes in the 'Program' @τ@ monad. This is especially common if you+are processing command-line options. In that case, you may find it useful to+initialize the program at type 'None', say, and then change to the 'Program'+@υ@ monad you intend to run through the actual program with once the full+settings object is available. You can do that using this function.++For example:++@+main :: 'IO' ()+main = do+    context <- 'Core.Program.Execute.configure' \"1.0\" 'None' ('simpleConfig' ...)+    'Core.Program.Execute.executeWith' context program1++program1 :: 'Program' 'None' ()+program1 = do+    -- do things to form top-level application state+    let settings =+            Settings+                { ...+                }+    +    'changeProgram' settings program2++program2 :: 'Program' Settings ()+program2 = do+    -- now carry on with application logic+    ...+@++This allows your code do do 'queryOptionValue' and the like in @program1@ and+then, once all the settings and initialization is complete, you can switch to+the actual type you intend to run at in @program2@.++@since 0.6.3+-}+changeProgram :: υ -> Program υ α -> Program τ α+changeProgram user' program = do+    context1 <- ask+    liftIO $ do+        u <- newMVar user'+        let context2 = context1 {applicationDataFrom = u}+        subProgram context2 program  {- | Write the supplied @Bytes@ to the given @Handle@. Note that in contrast to