h$m      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~             None  ;<=>?  ?><=;None Safe-Inferred$ !"#$%&'()*+,-./012345678:9$:9 $#-8(+*%)0'&"!654321/.7, Nonex    !"#$%&'()*+,-./012345678:9;<=>?None ; @ core-programInformation about the version number of this piece of software and other related metadata related to the project it was built from. This is supplied to your program when you call  ?. This value is used if the user requests it by specifying the  --version option on the command-line.>Simply providing an overloaded string literal such as version "1.0" will give you a @ with that value: ,{-# LANGUAGE OverloadedStrings #-} main ::  () main = do context <-   "1.0"  ( ... *For more complex usage you can populate a @ object using the D8 splice below. You can then call various accessors like C to access individual fields.D core-programThis is a splice which includes key built-time metadata, including the number from the version field from your project's .cabal, file (as written by hand or generated from  package.yaml).While we generally discourage the use of Template Haskell by beginners (there are more important things to learn first) it is a way to execute code at compile time and that is what what we need in order to have the version number extracted from the .cabal file rather than requiring the user to specify (and synchronize) it in multiple places.To use this, enable the Template Haskell language extension in your Main.hs file. Then use the special $( ... )> "insert splice here" syntax that extension provides to get a @5 object with the desired metadata about your project: -{-# LANGUAGE TemplateHaskell #-} version :: @ version = $(D ) main ::  () main = do context <-   version  ( ... (Using Template Haskell slows down compilation of this file, but the upside of this technique is that it avoids linking the Haskell build machinery into your executable, saving you about 10 MB in the size of the resultant binary)@BCAD@DCABNone 59H core-programDifferent ways parsing a simple or complex command-line can fail.I core-programSomething was wrong with the way the user specified [usually a short] option.J core-programUser specified an option that doesn't match any in the supplied configuration.K core-program1Arguments are mandatory, and this one is missing.L core-program+Arguments are present we weren't expecting.M core-programIn a complex configuration, user specified a command that doesn't match any in the configuration.N core-program:In a complex configuration, user didn't specify a command.O core-programIn a complex configuration, usage information was requested with --help., either globally or for the supplied command.P core-program.Display of the program version requested with  --version.Q core-programResult of having processed the command-line and the environment. You get at the parsed command-line options and arguments by calling  within a  block.Each option and mandatory argument parsed from the command-line is either standalone (in the case of switches and flags, such as --quiet) or has an associated value. In the case of options the key is the name of the option, and for arguments it is the implicit name specified when setting up the program. For example, in: 2$ ./submit --username=gbmh GraceHopper_Resume.pdf the option has parameter name "username " and value "gmbh"; the argument has parameter name "filename" (assuming that is what was declared in the \ entry) and a value being the Admiral's CV. This would be returned as: Q  [("username","gbmh"), ("filename","GraceHopper_Resume.pdf")] [] &The case of a complex command such as git or stack, you get the specific mode chosen by the user returned in the first position: $ missiles launch --all would be parsed as: Q ( "launch") [("all",Empty)] [] W core-programIndividual parameters read in off the command-line can either have a value (in the case of arguments and options taking a value) or be empty (in the case of options that are just flags).Z core-programDeclaration of an optional switch or mandatory argument expected by a program.[ takes a long name for the option, a short single character abbreviation if offered for convenience, whether or not the option takes a value (and what label to show in help output) and a description for use when displaying usage via --help.\ indicates a mandatory argument and takes the long name used to identify the parsed value from the command-line, and likewise a description for --help output.1By convention option and argument names are both  lower case. If the identifier is two or more words they are joined with a hyphen. Examples:  [ [ "quiet" ( 'q') Y* "Keep the noise to a minimum." , [ "dry-run"  (X "TIME") "Run a simulation of what would happen at the specified time." , \< "username" "The user to delete from the system." ] By convention a  description is one or more complete sentences each of which ends with a full stop. For options that take values, use  upper case5 when specifying the label to be used in help output.] is special; it indicates that you are expecting a variable number of additional, non-mandatory arguments. This is used for programs which take a list of files to process, for example. It'll show up in the help with the description you supply alongside.  [ ... , ] "The files you wish to delete permanently." , ... ] ^ declares an environment variable that, if present, will be read by the program and stored in its runtime context. By convention these are  upper case. If the identifier is two or more words they are joined with an underscore:  [ ... , ^ "CRAZY_MODE" "Specify how many crazies to activate." , ... ] _ core-programDescription of the command-line structure of a program which has "commands" (sometimes referred to as "subcommands") representing different modes of operation. This is familiar from tools like git and docker.b core-programThe setup for parsing the command-line arguments of your program. You build a Config with simple or complex, and pass it to  .c core-program:The name of an option, command, or agument (omitting the "--" prefix in the case of options). This identifier will be used to generate usage text in response to --help and by you later when retreiving the values of the supplied parameters after the program has initialized.Turn on OverloadedStrings+ when specifying configurations, obviously.e core-programThe description of an option, command, or environment variable (for use when rendering usage information in response to --help on the command-line).f core-program-Single letter "short" options (omitting the "-" prefix, obviously).g  core-programA completely empty configuration, without the default debugging and logging options. Your program won't process any command-line options or arguments, which would be weird in most cases. Prefer simple.h  core-programDeclare a simple (as in normal) configuration for a program with any number of optional parameters and mandatory arguments. For example: main ::  () main = do context <-   "1.0"  (h [ [ "host" ( 'h') Y [| Specify an alternate host to connect to when performing the frobnication. The default is "localhost". |] , [ "port" ( 'p') Y [| Specify an alternate port to connect to when frobnicating. |] , [ "dry-run"  (X "TIME") [| Perform a trial run at the specified time but don't actually do anything. |] , [ "quiet" ( 'q') Y [<| Supress normal output. |] , \ "filename" [| The file you want to frobnicate. |] ])  context program 3which, if you build that into an executable called snippet and invoke it with --help, would result in: $ ./snippet --help Usage: snippet [OPTIONS]  filename Available options: -h, --host Specify an alternate host to connect to when performing the frobnication. The default is "localhost". -p, --port Specify an alternate port to connect to when frobnicating. --dry-run= TIME Perform a trial run at the specified time but don't actually do anything. -q, --quiet Supress normal output. -v, --verbose Turn on informational messages. The logging stream will go to standard output on your terminal. --debug Turn on debug level logging. Implies --verbose. Required arguments:  filename( The file you want to frobnicate. $ | For information on how to use the multi-line string literals shown here, see  in Core.Text.Utilities.i  core-programDeclare a complex configuration (implying a larger tool with various "[sub]commands" or "modes"} for a program. You can specify global options applicable to all commands, a list of commands, and environment variables that will be honoured by the program. Each command can have a list of local options and arguments as needed. For example:  program :: * MusicAppStatus () program = ... main ::  () main = do context <-   ( version)  (complex [ ` [ [ "station-name"  (X "NAME") [| Specify an alternate radio station to connect to when performing actions. The default is "BBC Radio 1". |] , ^ "PLAYER_FORCE_HEADPHONES" [| If set to 1, override the audio subsystem to force output to go to the user's headphone jack. |] ] , a( "play" "Play the music." [ [ "repeat"  Y [| Request that they play the same song over and over and over again, simulating the effect of listening to a Top 40 radio station. |] ] , a "rate" "Vote on whether you like the song or not." [ [ "academic"  Y [| The rating you wish to apply, from A+ to F. This is the default, so there is no reason whatsoever to specify this. But some people are obsessive, compulsive, and have time on their hands. |] , [ "numeric"  Y [| Specify a score as a number from 0 to 100 instead of an academic style letter grade. Note that negative values are not valid scores, despite how vicerally satisfying that would be for music produced in the 1970s. |] , [ "unicode" ( 'c') Y [| Instead of a score, indicate your rating with a single character. This allows you to use emoji, so that you can rate a piece '', as so many songs deserve. |] , \ "score" [| The rating you wish to apply. |] ] ])  context program is a program with one global option (in addition to the default ones) [and an environment variable] and two commands: play, with one option; and rate, with two options and a required argument. It also is set up to carry its top-level application state around in a type called MusicAppStatus (implementing  and so initialized here with . This is a good pattern to use given we are so early in the program's lifetime). one two -- continue, doing something with both results. For a variant that ingores the return values and just waits for both see  below. (this wraps async's $) core-program-Fork two threads and wait for both to finish.This is the same as calling  and  twice, except that if either sub-program fails with an exception the other program which is still running will be cancelled and the original exception is then re-thrown. (this wraps async's %) core-programFork two threads and race them against each other. This blocks until one or the other of the threads finishes. The return value will be   if the first program (one) completes first, and   if it is the second program (two) which finishes first. The sub program which is still running will be cancelled with an exception.  result <-  one two case result of Left a -> do -- one finished first Right b -> do -- two finished first For a variant that ingores the return value and just races the threads see  below. (this wraps async's &) core-programFork two threads and race them against each other. When one action completes the other will be cancelled with an exception. This is useful for enforcing timeouts:   ( sleepThread 300) (do -- We expect this to complete within 5 minutes. performAction )  (this wraps async's ')  (None\I core-programInstall signal handlers for SIGINT and SIGTERM that set the exit semaphore so that a Program's [minimal] cleanup can occur.None ?l  core-programWrite the supplied text to stdout."This is for normal program output.   "Beginning now"  core-programCall : on the supplied argument and write the resultant text to stdout.(This is the equivalent of  from base) core-programPretty print the supplied argument and write the resultant text to stdout4. This will pass the detected terminal width to the  function, resulting in appopriate line wrapping when rendering your value.  core-programNote a significant event, state transition, status; also used as a heading for subsequent debugging messages. This:   "Starting..." will result in 13:05:55Z (00.112) Starting... appearing on stdout. The output string is current time in UTC, and time elapsed since startup shown to the nearest millisecond (our timestamps are to nanosecond precision, but you don't need that kind of resolution in in ordinary debugging).  core-programEmit a diagnostic message warning of an off-nominal condition. They are best used for unexpected conditions or places where defaults are being applied (potentially detrimentally). ) warn "You left the lights on again" Warnings are worthy of note if you are looking into the behaviour of the system, and usually@but not always@indicate a problem. That problem may not need to be rectified, certainly not immediately.(DO NOT PAGE OPERATIONS STAFF ON WARNINGS.For example, see Core.Program.Execute's ) function, a wrapper action which allows you to restart a loop when combined with !*. trap_ swollows exceptions but does not do  so silently, instead using  to log a warning as an information message. You don't need to do anything about the warning right away; after all the point is to allow your program to continue. If it is happening unexpectly or frequently, however, the issue bears investigation and the warning severity message will give you a starting point for diagnosis.  core-programReport an anomoly or condition critical to the ongoing health of the program.  critical "Unable to do hostname lookups" -- Yup, it was DNS. It's always DNS. The term "critical" generally means the program is now in an unexpected or invalid state, that further processing is incorrect, and that the program is likely about to crash. The key is to get the message out to the informational channel as quickly as possible before it does.;For example, an uncaught exception bubbling to the top the  monad will be logged as a  severity message and forceibly output to the console before the program exits. Your program is crashing, but at least you have a chance to find about why before it does.You're not going to page your operations staff on these either, but if they're happening in a production service and it's getting restarted a lot as a result you're probably going to be hearing about it. core-programOutput a debugging message formed from a label and a value. This is like event above but for the (rather common) case of needing to inspect or record the value of a variable when debugging code. This:  setProgramName "hello" name <- getProgramName  "programName" name will result in &13:05:58Z (03.141) programName = hello appearing on stdout, assuming these actions executed about three seconds after program start. core-programConvenience for the common case of needing to inspect the value of a general variable which has a  instance core-programConvenience for the common case of needing to inspect the value of a general variable for which there is a  instance and so can pretty print the supplied argument to the log. This will pass the detected terminal width to the  function, resulting in appopriate line wrapping when rendering your value (if logging to something other than console the default width of 80 will be applied).None  core-programTrap any exceptions coming out of the given Program action, and discard them. The one and only time you want this is inside an endless loop:  forever $ do trap_ ( bracket obtainResource releaseResource useResource ) This function really will swollow expcetions, which means that you'd better have handled any synchronous checked errors already with a =% and/or have released resources with < or ; as shown above.An info level message will be sent to the log channel indicating that an uncaught exception was trapped along with a debug level message showing the exception text, if any. core-program=Embelish a program with useful behaviours. See module header Core.Program.Execute< for a detailed description. Internally this function calls / with an appropriate default when initializing. core-programEmbelish a program with useful behaviours, supplying a configuration for command-line options & argument parsing and an initial value for the top-level application state, if appropriate. core-programSafely exit the program with the supplied exit code. Current output and debug queues will be flushed, and then the process will terminate. core-programChange the verbosity level of the program's logging output. This changes whether event and the 9 family of functions emit to the logging stream; they do not affect 2ing to the terminal on the standard output stream. core-programOverride the program name used for logging, etc. At least, that was the idea. Nothing makes use of this at the moment. :/ core-programGet the program name as invoked from the command-line (or as overridden by ). core-program5Retreive the current terminal's width, in characters.'If you are outputting an object with a +,: instance then you may not need this; you can instead use wrteR which is aware of the width of your terminal and will reflow (in as much as the underlying type's Render instance lets it). core-programGet the user supplied application state as originally supplied to . and modified subsequntly by replacement with . ! state <- getApplicationState  core-program5Update the user supplied top-level application state.  let state' = state { answer = 42 } setApplicationState state'  core-programWrite the supplied Bytes to the given Handle. Note that in contrast to $ we don't output a trailing newline.  output h b Do not use this to output to stdout0 as that would bypass the mechanism used by the *, event, and * functions to sequence output correctly. If you wish to write to the terminal use:   ( b) (which is not unsafe, but will lead to unexpected results if the binary blob you pass in is other than UTF-8 text). core-program,Read the (entire) contents of the specified Handle. core-programExecute an external child process and wait for its output and result. The command is specified first and and subsequent arguments as elements of the list. This helper then logs the command being executed to the debug output, which can be useful when you're trying to find out what exactly what program is being invoked.Keep in mind that this isn't invoking a shell; arguments and their values have to be enumerated separately:   ["/usr/bin/ssh", "-l", "admin", "203.0.113.42", "\'remote command here\'"] having to write out the individual options and arguments and deal with escaping is a bit of an annoyance but that's  execvp(3) for you.The return tuple is the exit code from the child process, its entire stdout and its entire stderr, if any. Note that this is not a streaming interface, so if you're doing something that returns huge amounts of output you'll want to use something like  io-streams instead. (this wraps  typed-process's ) core-programReset the start time (used to calculate durations shown in event- and debug-level logging) held in the Context to zero. This is useful if you want to see the elapsed time taken by a specific worker rather than seeing log entries relative to the program start time which is the default.If you want to start time held on your main program thread to maintain a count of the total elapsed program time, then fork a new thread for your worker and reset the timer there.   forkThread $ do  ... then times output in the log messages will be relative to that call to , not the program start. core-programPause the current thread for the given number of seconds. For example, to delay a second and a half, do:   1.5  (this wraps base's ) core-programRetrieve the values of parameters parsed from options and arguments supplied by the user on the command-line..The command-line parameters are returned in a , mapping from from the option or argument name to the supplied value. You can query this map directly: program = do params <-  let result =  "silence" (paramterValuesFrom params) case result of  ->  () # quiet = case quiet of X _ -> ? NotQuiteRight -- complain that flag doesn't take value Y -> 4 "You should be quiet now" -- much better ... which is pattern matching to answer "was this option specified by the user?" or "what was the value of this [mandatory] argument?", and then "if so, did the parameter have a value?"=This is available should you need to differentiate between a Value and an Empty W6, but for many cases as a convenience you can use the , , and  functions below. core-programArguments are mandatory, so by the time your program is running a value has already been identified. This retreives the value for that parameter. program = do file <-  "filename" ...  core-programIn other applications, you want to gather up the remaining arguments on the command-line. You need to have specified ] in the configuration. program = do files <-  ...  core-programLook to see if the user supplied a valued option and if so, what its value was. Use of the  LambdaCase; extension might make accessing the parameter a bit eaiser: program = do count <-  "count"  \case  ->  0  value ->  value ...  core-programReturns True if the option is present, and False if it is not. program = do overwrite <-  "overwrite" ...  core-programLook to see if the user supplied the named environment variable and if so, return what its value was. core-programRetreive the sub-command mode selected by the user. This assumes your program was set up to take sub-commands via i.  mode <- queryCommandName  core-programIllegal internal state resulting from what should be unreachable code or otherwise a programmer error.&& None  core-program>This gives you a function that you can use within your lifted  actions to return to the  monad.The type signature of this function is a bit involved, but the example below shows that the lambda gives you a function+ as its argument (we recommend you name it  runProgram for consistency) which gives you a way to run a subprogram, be that a single action like writing to terminal or logging, or a larger action in a do-notation block: main :: IO () main =  $ do  $ \runProgram -> do -- in IO monad, lifted -- (just as if you had used liftIO) ... runProgram $ do -- now unlifted, back to Program monad ... Think of this as  with an escape hatch.This function is named : because it is a convenience around the following pattern:  context <- % liftIO $ do ... > context $ do -- now in Program monad ...  None  core-program+Watch for changes to a given list of files.Before continuing we insert a 100ms pause to allow whatever the editor was to finish its write and switcheroo sequence.None@BCADHPONMLKIJQRVUSTWXYZ^][\_`abcdefghijklmnop<-./-01-23-24-56-.7-.8-9:-;<-;=-;>-;?-@A-@B-@C-@D-@E-FG-;HIJKIJLIJMIJMNOPNQRNQSNQTNQUNQVNQWNQXNQYNQZNO[NO\NO]NO^NO_NO`NOaNObNOcNOdNOeNOfNOgNOhNOiNOjNOkNOlNOmNOnNOoNOpNOqNOrNOsNOtuvwuvxuvyuvzuv{|}~          )  -------(--5-,---+core-program-0.4.0.0-DktGYuBpyU86lkhR4Kvk8zCore.System.BaseCore.System.ExternalCore.System.PrettyCore.Program.MetadataCore.Program.ArgumentsCore.Program.Execute Core.ProgramCore.Program.LoggingCore.Program.UnliftCore.Program.ThreadsCore.Program.Notify Core.System configureNonesimplegetCommandLineProgramCore.Program.Context executeWith fromPackageexecutesetVerbosityLevelgetApplicationStatesetApplicationStateCore.Telemetry.Observability beginTrace usingTrace encloseSpanControl.Concurrent.AsyncasyncControl.ConcurrentforkIO Control.MonadmapM_mapM concurrently concurrently_racerace_Core.Program.Signaltrap_foreverCore.Text.UntilitiesRenderbaseGHC.IO.Handle.FDstdoutGHC.IO.Handle.TypesHandleControl.Monad.IO.ClassliftIOMonadIO System.IOwithFilestderrstdin GHC.IO.HandlehFlushGHC.Exception.TypedisplayException fromException toException Exception GHC.IO.IOMode ReadWriteMode AppendMode WriteModeReadModeIOMode GHC.IO.UnsafeunsafePerformIO SomeException,chronologique-0.3.1.3-LTfwgbGF6eG4NQ2d3RAO1wChrono.TimeStampgetCurrentTimeNanoseconds unTimeStamp TimeStamp)prettyprinter-1.7.1-BauxLiNvN3EiJKyXe93SMPrettyprinter.InternalDocPrettyprinter.Symbols.Asciicommarbracelbracerbracketlbracketrparenlparendquotesquote unAnnotateannotateenclose punctuatefillCatvcathcatsepfillSepvsephsep concatWith<+>indenthangflatAltgrouphardline softline'softlineline'linenestemptyDocprettyPretty.safe-exceptions-0.1.7.2-JneZS63Oo6PChwawONXlrZControl.Exception.Safefinallybracketcatch impureThrowthrowVersionprojectNameFromprojectSynopsisFromversionNumberFrom$fIsStringVersion $fShowVersion$fLiftLiftedRepVersionInvalidCommandLine InvalidOption UnknownOptionMissingArgumentUnexpectedArgumentsUnknownCommandNoCommandFound HelpRequestVersionRequest ParameterscommandNameFromparameterValuesFromremainingArgumentsFromenvironmentValuesFromParameterValueValueEmptyOptionsOptionArgument RemainingVariableCommandsGlobalCommandConfigLongName Description ShortName blankConfig simpleConfig complexConfig appendOptionemptyParametersbaselineOptionsparseCommandLineextractValidEnvironments buildUsage buildVersion$fTextualLongName$fPrettyLongName $fKeyLongName$fIsStringParameterValue$fExceptionInvalidCommandLine$fShowInvalidCommandLine$fEqInvalidCommandLine$fShowParameters$fEqParameters$fShowParameterValue$fEqParameterValue$fShowLongName$fIsStringLongName $fEqLongName$fHashableLongName $fOrdLongNameBoom VerbosityOutputVerboseDebugContext$sel:programNameFrom:Context$sel:terminalWidthFrom:Context$sel:versionFrom:Context$sel:initialConfigFrom:Context!$sel:initialExportersFrom:Context$sel:commandLineFrom:Context$sel:exitSemaphoreFrom:Context$sel:startTimeFrom:Context$sel:verbosityLevelFrom:Context$sel:outputChannelFrom:Context!$sel:telemetryChannelFrom:Context#$sel:telemetryForwarderFrom:Context$sel:currentDatumFrom:Context $sel:applicationDataFrom:Context Forwarder#$sel:telemetryHandlerFrom:ForwarderExporter$sel:codenameFrom:Exporter$sel:setupConfigFrom:Exporter$sel:setupActionFrom:ExporterTraceSpanDatum$sel:spanIdentifierFrom:Datum$sel:spanNameFrom:Datum$sel:serviceNameFrom:Datum$sel:spanTimeFrom:Datum$sel:traceIdentifierFrom:Datum$sel:parentIdentifierFrom:Datum$sel:durationFrom:Datum$sel:attachedMetadataFrom:Datum emptyDatumunSpanunTrace fmapContextisNone unProgram getContext subProgramhandleCommandLinehandleVerbosityLevelhandleTelemetryChoiceThreadunThread forkThread waitThread waitThread_concurrentThreadsconcurrentThreads_ raceThreads raceThreads_Severity SeverityNoneSeverityCritical SeverityWarn SeverityInfo SeverityDebugSeverityInternal putMessageformatLogMessagewritewriteSwriteRinfowarncriticalisEventisDebugdebugdebugSdebugRinternal loopForever terminategetVerbosityLevelsetProgramNamegetProgramNamegetConsoleWidth outputEntire inputEntire execProcess resetTimer sleepThread queryArgumentlookupArgumentqueryRemainingqueryOptionValuelookupOptionValuequeryOptionFlaglookupOptionFlagqueryEnvironmentValuelookupEnvironmentValuequeryCommandNameinvalid$fExceptionProcessProblem$fShowProcessProblem withContext waitForChangeghc-prim GHC.TypesIO GHC.MaybeNothingJust(core-text-0.3.5.0-BET7DwaAMQo2YDHRHVVVFvCore.Text.UtilitiesquoteGHC.BasememptyMonoid"async-2.2.4-GvKzLuO4KJh3ZF8PcBWxUxAsyncreturn Data.EitherLeftRightsetupSignalHandlersGHC.ShowshowprintrenderShowCore.Text.RopeintoRope,typed-process-0.2.7.0-8MDAm4hkgNqHNt1ikOYwkqSystem.Process.Typed readProcess GHC.Conc.IO threadDelay(core-data-0.3.0.2-5RgCcVPhMFy85FGUDAWRvECore.Data.StructuresMaplookupKeyValue>>=pure