cfv
Copyright(c) Harley Eades 2026
Maintainerharley.eades@gmail.com
Safe HaskellSafe
LanguageHaskell2010

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 = '...'; or name = "..."; declares a string. The escapes \\, \', \", \n, \t, \r, \0 are recognized; raw newlines are allowed.
  • Commands: name = `cmd` runs cmd in the user's shell and uses its stdout as the value. Like shell command substitution, trailing newlines are stripped. cmd is 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 no secret attribute labels a declaration it is assumed to be non-sensitive (public). Note that secret is only a keyword when a variable name follows it, so secret = 'x'; still declares a public variable called secret.

Parsing a CFV file returns a list of Binding which is simply a pair (VarName, Var) of a variable name ( 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

Parsing and evaluating

type Binding = (VarName, Var) Source #

A variable binding: a name, attribute, and a value.

data Var Source #

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 ())]

Constructors

Var VarAttr VarValue 

Instances

Instances details
Show Var Source # 
Instance details

Defined in Configuration.Cfv.AST

Methods

showsPrec :: Int -> Var -> ShowS #

show :: Var -> String #

showList :: [Var] -> ShowS #

Eq Var Source # 
Instance details

Defined in Configuration.Cfv.AST

Methods

(==) :: Var -> Var -> Bool #

(/=) :: Var -> Var -> Bool #

varAttr :: Var -> VarAttr Source #

The variable's attribute.

revealVar :: Var -> Text Source #

The variable's value, secret or not.

data VarAttr Source #

Security level for variables.

Constructors

Public

The default; has no syntax.

Secret

Declared with a secret prefix.

Instances

Instances details
Show VarAttr Source # 
Instance details

Defined in Configuration.Cfv.AST

Eq VarAttr Source # 
Instance details

Defined in Configuration.Cfv.AST

Methods

(==) :: VarAttr -> VarAttr -> Bool #

(/=) :: VarAttr -> VarAttr -> Bool #

Ord VarAttr Source # 
Instance details

Defined in Configuration.Cfv.AST

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

Instances details
Show ShellConfig Source # 
Instance details

Defined in Configuration.Cfv.Shell

Eq ShellConfig Source # 
Instance details

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

data CfvError Source #

Everything that can go wrong when processing a CFV file.

Constructors

InvalidExtension FilePath

The file name does not end in .cfv (checked before anything is read).

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

Instances details
Exception CfvError Source # 
Instance details

Defined in Configuration.Cfv.Parser

Show CfvError Source # 
Instance details

Defined in Configuration.Cfv.Parser

Eq CfvError Source # 
Instance details

Defined in Configuration.Cfv.Parser

data SyntaxError Source #

A problem with the text itself, with a location.

Constructors

SyntaxError 

Fields

data ErrorKind Source #

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 _) was used as a variable name. Position: start of the word.

InvalidEscape (Maybe Char)

A backslash followed by a character that is not a known escape. Position: the backslash. Nothing (character withheld) inside the value of a Secret declaration.

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.

Instances

Instances details
Show ErrorKind Source # 
Instance details

Defined in Configuration.Cfv.Parser

Eq ErrorKind Source # 
Instance details

Defined in Configuration.Cfv.Parser

data Item Source #

Something the parser found or expected.

Constructors

Literal Text

Specific text, such as ";".

Description Text

A named construct, such as "variable name".

EndOfFile 

Instances

Instances details
Show Item Source # 
Instance details

Defined in Configuration.Cfv.Parser

Methods

showsPrec :: Int -> Item -> ShowS #

show :: Item -> String #

showList :: [Item] -> ShowS #

Eq Item Source # 
Instance details

Defined in Configuration.Cfv.Parser

Methods

(==) :: Item -> Item -> Bool #

(/=) :: Item -> Item -> Bool #

Ord Item Source # 
Instance details

Defined in Configuration.Cfv.Parser

Methods

compare :: Item -> Item -> Ordering #

(<) :: Item -> Item -> Bool #

(<=) :: Item -> Item -> Bool #

(>) :: Item -> Item -> Bool #

(>=) :: Item -> Item -> Bool #

max :: Item -> Item -> Item #

min :: Item -> Item -> Item #

data Position Source #

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.

Constructors

Position 

Instances

Instances details
Show Position Source # 
Instance details

Defined in Configuration.Cfv.Parser

Eq Position Source # 
Instance details

Defined in Configuration.Cfv.Parser

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).

Instances

Instances details
Show CommandError Source # 
Instance details

Defined in Configuration.Cfv.Shell

Eq CommandError Source # 
Instance details

Defined in Configuration.Cfv.Shell

data CommandProblem Source #

Errors produced by running a command on the shell.

Constructors

NoShell

No shell configured and SHELL is unset or empty.

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 Nothing for a '@Configuration.Cfv.AST.Secret' variable.

OutputNotUtf8 UnicodeException

The command's standard output is not valid UTF-8. The exception names the offending byte, so it is Nothing for a '@Configuration.Cfv.AST.Secret' variable.

renderCfvError :: CfvError -> Text Source #

Converts a error into a Text that is appropriate for logging.