| Copyright | (c) Harley Eades 2026 |
|---|---|
| Maintainer | harley.eades@gmail.com |
| Safe Haskell | Safe |
| Language | Haskell2010 |
Configuration.Cfv
Description
A CFV file is a sequence of configuration variable declarations.
A valid variable declarations consist of one of the following:
- Strings:
name = '...';orname = "...";declares a string. The escapes\\, \', \", \n, \t, \r, \0are recognized; raw newlines are allowed. - Commands:
name = `cmd`runscmdin the user's shell and uses its stdout as the value. Like shell command substitution, trailing newlines are stripped.cmdis everything up to the next backtick (there is no escape for a backtick; use$(...)for nested substitution). The command runs in the current working directory with the calling process's environment and a closed standard input. - Secrets: A declaration may be prefixed with
secret(secret name = ...) to mark its value as a secret. When nosecretattribute labels a declaration it is assumed to be non-sensitive (public). Note thatsecretis only a keyword when a variable name follows it, sosecret = 'x';still declares a public variable calledsecret.
Parsing a CFV file returns a list of Binding which is simply a pair
( of a variable name ( VarName, Var)String ) and a variable ( Var ). The latter
labels a variable's value with an attribute which currently consist of Public
and Secret. After parsing you are free to use these variable declarations in
any way you wish.
This API does place one restriction on the declarations attributed
with sercret. The default Show instance does not convert a secret variable's
value to a string, but simply translates it to Secret (). This makes printing
the contents of a CFV file to a log or the screen safe.
Synopsis
- type Binding = (VarName, Var)
- data Var = Var VarAttr VarValue
- varAttr :: Var -> VarAttr
- revealVar :: Var -> Text
- data VarAttr
- parseCfvFile :: FilePath -> IO (Either CfvError [Binding])
- parseCfvFileWith :: ShellConfig -> FilePath -> IO (Either CfvError [Binding])
- parseEvalCfv :: [Char] -> Text -> IO (Either CfvError [Binding])
- parseEvalCfvWith :: ShellConfig -> [Char] -> Text -> IO (Either CfvError [Binding])
- data ShellConfig = ShellConfig {
- shellProgram :: Maybe FilePath
- shellFlags :: [String]
- defaultShellConfig :: ShellConfig
- data CfvError
- data SyntaxError = SyntaxError {}
- data ErrorKind
- data Item
- data Position = Position {}
- data CommandError = CommandError {}
- data CommandProblem
- renderCfvError :: CfvError -> Text
Parsing and evaluating
A variable's final value (after any command has been run) together with its attribute.
The Show instance never prints a secret value, so a list of bindings can
be logged safely:
[("name",Public "x"),("key",Secret ())]Security level for variables.
parseCfvFile :: FilePath -> IO (Either CfvError [Binding]) Source #
Read, parse and evaluate a .cfv file using defaultShellConfig.
Returns the variables in source order; a variable declared more than once
appears more than once (so lookup finds the first declaration). Commands
run one at a time in file order, and the first failure aborts the whole
operation.
Never throws for extension, read, decode, parse or command problems; they are
all returned as CfvError. (To throw instead:
either E.throwIO pure =<< parseCfvFile p.)
parseCfvFileWith :: ShellConfig -> FilePath -> IO (Either CfvError [Binding]) Source #
Like parseCfvFile with an explicit shell configuration.
parseEvalCfv :: [Char] -> Text -> IO (Either CfvError [Binding]) Source #
Like parseCfvFile, but doesn't read from a file. Useful for testing.
parseEvalCfvWith :: ShellConfig -> [Char] -> Text -> IO (Either CfvError [Binding]) Source #
Like parseEvalCfv but with an explicit shell configuration.
Shell configuration
data ShellConfig Source #
Shell configuration.
Constructors
| ShellConfig | |
Fields
| |
Instances
| Show ShellConfig Source # | |
Defined in Configuration.Cfv.Shell Methods showsPrec :: Int -> ShellConfig -> ShowS # show :: ShellConfig -> String # showList :: [ShellConfig] -> ShowS # | |
| Eq ShellConfig Source # | |
Defined in Configuration.Cfv.Shell | |
defaultShellConfig :: ShellConfig Source #
Use $SHELL as a login shell: $SHELL -l -c cmd. A login shell picks up
the user's profile (PATH additions and so on). Add "-i" to the flags if
you also need what the shell's interactive rc file sets up (aliases,
functions).
Errors
Everything that can go wrong when processing a CFV file.
Constructors
| InvalidExtension FilePath | The file name does not end in |
| FileReadError FilePath IOException | The file could not be opened or read. |
| FileDecodeError FilePath UnicodeException | The file's contents are not valid UTF-8. |
| FileSyntaxError SyntaxError | The contents do not parse. |
| FileCommandError CommandError Text VarAttr Position | A backtick command could not be run, or failed. (Only produced by functions that run commands.) |
Instances
| Exception CfvError Source # | |
Defined in Configuration.Cfv.Parser Methods toException :: CfvError -> SomeException # fromException :: SomeException -> Maybe CfvError # displayException :: CfvError -> String # | |
| Show CfvError Source # | |
| Eq CfvError Source # | |
data SyntaxError Source #
A problem with the text itself, with a location.
Constructors
| SyntaxError | |
Fields
| |
Instances
| Exception SyntaxError Source # | |
Defined in Configuration.Cfv.Parser Methods toException :: SyntaxError -> SomeException # fromException :: SomeException -> Maybe SyntaxError # displayException :: SyntaxError -> String # | |
| Show SyntaxError Source # | |
Defined in Configuration.Cfv.Parser Methods showsPrec :: Int -> SyntaxError -> ShowS # show :: SyntaxError -> String # showList :: [SyntaxError] -> ShowS # | |
| Eq SyntaxError Source # | |
Defined in Configuration.Cfv.Parser | |
The specific kind of syntax error.
Constructors
| UnexpectedInput (Maybe Item) [Item] | Found this (if known), but expected one of these. |
| ReservedWord Text | A Haskell keyword (or a lone |
| InvalidEscape (Maybe Char) | A backslash followed by a character that is not a known escape.
Position: the backslash. |
| UnterminatedString Char | A string literal with no closing quote (carries the quote character). Position: the opening quote. |
| UnterminatedCommand | A backtick command with no closing backtick. Position: the opening backtick. |
| OtherFailure Text | Anything else; should not occur with the current grammar. |
Something the parser found or expected.
Constructors
| Literal Text | Specific text, such as |
| Description Text | A named construct, such as |
| EndOfFile |
A location in the source. Line and column are 1-based; the offset is the 0-based character offset from the start of the input.
data CommandError Source #
A backtick command that could not produce a value.
For a Configuration.Cfv.AST.Secret variable anything that could contain or reveal the secret is
withheld: the command text (which may embed it) and the details of the
command's output (see CommandProblem).
Constructors
| CommandError | |
Fields | |
Instances
| Show CommandError Source # | |
Defined in Configuration.Cfv.Shell Methods showsPrec :: Int -> CommandError -> ShowS # show :: CommandError -> String # showList :: [CommandError] -> ShowS # | |
| Eq CommandError Source # | |
Defined in Configuration.Cfv.Shell | |
data CommandProblem Source #
Errors produced by running a command on the shell.
Constructors
| NoShell | No shell configured and |
| ShellLaunchFailed FilePath IOException | The shell could not be started (not found, not executable, ...). |
| NonZeroExit Int Text | The command exited with this status (negative: killed by that signal)
and this standard error output, trimmed. The output is |
| OutputNotUtf8 UnicodeException | The command's standard output is not valid UTF-8. The exception names
the offending byte, so it is |
Instances
| Show CommandProblem Source # | |
Defined in Configuration.Cfv.Shell Methods showsPrec :: Int -> CommandProblem -> ShowS # show :: CommandProblem -> String # showList :: [CommandProblem] -> ShowS # | |
| Eq CommandProblem Source # | |
Defined in Configuration.Cfv.Shell Methods (==) :: CommandProblem -> CommandProblem -> Bool # (/=) :: CommandProblem -> CommandProblem -> Bool # | |