-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Tools to parse and evaluate the Puppet DSL.
--   
--   This is a set of libraries designed to work with the Puppet DSL. It
--   can be used to parse .pp files, compile and interpret them, evaluate
--   the templates. It is still very experimental but is already pretty
--   useful when working with the manifests.
@package language-puppet
@version 0.1.5


-- | Types used when parsing the Puppet DSL. A good knowledge of the Puppet
--   language in required to understand them.
module Puppet.DSL.Types
data Parameters
Parameters :: [(Expression, Expression)] -> Parameters

-- | This type is used to differenciate the distinct top level types that
--   are exposed by the DSL.
data TopLevelType

-- | This is for node entries.
TopNode :: TopLevelType

-- | This is for defines.
TopDefine :: TopLevelType

-- | This is for classes.
TopClass :: TopLevelType

-- | This one is special. It represents top level statements that are not
--   part of a node, define or class. It is defined as spurious because it
--   is not what you are supposed to be. Also the caching system doesn't
--   like them too much right now.
TopSpurious :: TopLevelType

-- | This function returns the <a>TopLevelType</a> of a statement if it is
--   either a node, class or define. It returns Nothing otherwise.
convertTopLevel :: Statement -> Either Statement (TopLevelType, String, Statement)

-- | The <a>Value</a> type represents a Puppet value. It is the terminal in
--   a puppet <a>Expression</a>
data Value

-- | String literal.
Literal :: String -> Value

-- | An interpolable string, represented as a <a>Value</a> list.
Interpolable :: [Value] -> Value

-- | A Puppet Regexp. This is very hackish as it alters the behaviour of
--   some functions (such as conditional values).
PuppetRegexp :: String -> Value
Double :: Double -> Value
Integer :: Integer -> Value

-- | Reference to a variable. The string contains what is acutally typed in
--   the manifest.
VariableReference :: String -> Value
Empty :: Value
ResourceReference :: String -> Expression -> Value
PuppetArray :: [Expression] -> Value
PuppetHash :: Parameters -> Value
FunctionCall :: String -> [Expression] -> Value

-- | This is special and quite hackish too.
Undefined :: Value
data Virtuality
Normal :: Virtuality
Virtual :: Virtuality
Exported :: Virtuality

-- | The actual puppet statements
data Statement

-- | This holds the node name and list of statements. | This holds the
--   variable name and the expression that it represents.
Node :: String -> ![Statement] -> SourcePos -> Statement
VariableAssignment :: String -> Expression -> SourcePos -> Statement
Include :: String -> SourcePos -> Statement
Import :: String -> SourcePos -> Statement
Require :: String -> SourcePos -> Statement

-- | This holds the resource type, name, parameter list and virtuality.
Resource :: String -> Expression -> ![(Expression, Expression)] -> Virtuality -> SourcePos -> Statement

-- | This is a resource default declaration, such as File {owner =&gt;
--   'root'; }. It holds the resource type and the list of default
--   parameters.
ResourceDefault :: String -> ![(Expression, Expression)] -> SourcePos -> Statement

-- | This works like <a>Resource</a>, but the <a>Expression</a> holds the
--   resource name.
ResourceOverride :: String -> Expression -> ![(Expression, Expression)] -> SourcePos -> Statement

-- | The pairs hold on the left a value that is resolved as a boolean, and
--   on the right the list of statements that correspond to this. This will
--   be generated by if/then/else statement, but also by the case
--   statement.
ConditionalStatement :: ![(Expression, [Statement])] -> SourcePos -> Statement

-- | The class declaration holds the class name, the optional name of the
--   class it inherits from, a list of parameters with optional default
--   values, and the list of statements it contains.
ClassDeclaration :: String -> (Maybe String) -> ![(String, Maybe Expression)] -> ![Statement] -> SourcePos -> Statement

-- | The define declaration is like the <a>ClassDeclaration</a> except it
--   can't inherit from anything.
DefineDeclaration :: String -> ![(String, Maybe Expression)] -> ![Statement] -> SourcePos -> Statement

-- | This is the resource collection syntax (&lt;&lt;| |&gt;&gt;). It holds
--   the conditional expression, and an eventual list of overrides. This is
--   important as the same token conveys two distinct Puppet concepts :
--   resource collection and resource overrides.
ResourceCollection :: String -> !Expression -> ![(Expression, Expression)] -> SourcePos -> Statement

-- | Same as <a>ResourceCollection</a>, but for &lt;| |&gt;.
VirtualResourceCollection :: String -> !Expression -> ![(Expression, Expression)] -> SourcePos -> Statement
DependenceChain :: !(String, Expression) -> !(String, Expression) -> SourcePos -> Statement
MainFunctionCall :: String -> ![Expression] -> SourcePos -> Statement

-- | This is a magic statement that is used to hold the spurious top level
--   statements that comes in the same file as the correct top level
--   statement that is stored in the second field. The first field contains
--   pairs of filenames and statements. This is designed so that the
--   interpreter can know whether it has already been evaluated.
TopContainer :: ![(String, Statement)] -> !Statement -> Statement

-- | Expressions will be described with a and b being the first and second
--   field of the constructor.
data Expression

-- | a[b]
LookupOperation :: !Expression -> !Expression -> Expression

-- | a in b
IsElementOperation :: !Expression -> !Expression -> Expression

-- | a + b
PlusOperation :: !Expression -> !Expression -> Expression

-- | a - b
MinusOperation :: !Expression -> !Expression -> Expression

-- | a / b
DivOperation :: !Expression -> !Expression -> Expression

-- | a * b
MultiplyOperation :: !Expression -> !Expression -> Expression

-- | a &lt;&lt; b
ShiftLeftOperation :: !Expression -> !Expression -> Expression

-- | a &gt;&gt; b
ShiftRightOperation :: !Expression -> !Expression -> Expression

-- | a &amp; b
AndOperation :: !Expression -> !Expression -> Expression

-- | a | b
OrOperation :: !Expression -> !Expression -> Expression

-- | a == b
EqualOperation :: !Expression -> !Expression -> Expression

-- | a != b
DifferentOperation :: !Expression -> !Expression -> Expression

-- | a &gt; b
AboveOperation :: !Expression -> !Expression -> Expression

-- | a &gt;= b
AboveEqualOperation :: !Expression -> !Expression -> Expression

-- | a &lt;= b
UnderEqualOperation :: !Expression -> !Expression -> Expression

-- | a &lt; b
UnderOperation :: !Expression -> !Expression -> Expression

-- | a =~ b (b should be a <a>PuppetRegexp</a>)
RegexpOperation :: !Expression -> !Expression -> Expression

-- | a !~ b
NotRegexpOperation :: !Expression -> !Expression -> Expression

-- | ! a
NotOperation :: !Expression -> Expression

-- | <ul>
--   <li>a</li>
--   </ul>
NegOperation :: !Expression -> Expression

-- | a ? b (b should be a <a>PuppetHash</a>)
ConditionalValue :: !Expression -> !Expression -> Expression

-- | <a>Value</a> terminal
Value :: Value -> Expression

-- | Resolved resource reference
ResolvedResourceReference :: String -> String -> Expression

-- | True expression, this could have been better to use a <a>Value</a>
BTrue :: Expression

-- | False expression
BFalse :: Expression

-- | Not used anymore.
Error :: String -> Expression
instance Show TopLevelType
instance Ord TopLevelType
instance Eq TopLevelType
instance Show Virtuality
instance Ord Virtuality
instance Eq Virtuality
instance Show Expression
instance Ord Expression
instance Eq Expression
instance Show Value
instance Ord Value
instance Eq Value
instance Show Parameters
instance Ord Parameters
instance Eq Parameters
instance Show Statement
instance Ord Statement
instance Eq Statement

module Puppet.DSL.Printer

-- | This shows the parsed AST a bit like the original syntax.
showAST :: [Statement] -> String

-- | Useful for displaying a map of variables.
showVarMap :: Map String (Expression, SourcePos) -> String

module Puppet.Interpreter.Types

-- | This is the potentially unsolved list of resources in the catalog.
type Catalog = [CResource]
type Facts = Map String ResolvedValue

-- | Relationship link type.
data LinkType
RNotify :: LinkType
RRequire :: LinkType
RBefore :: LinkType
RRegister :: LinkType

-- | The list of resolved values that are used to define everything in a
--   <a>FinalCatalog</a> and in the resolved parts of a <a>Catalog</a>.
--   They are to be compared with the <a>Value</a>s.
data ResolvedValue
ResolvedString :: !String -> ResolvedValue
ResolvedRegexp :: !String -> ResolvedValue
ResolvedInt :: !Integer -> ResolvedValue
ResolvedDouble :: !Double -> ResolvedValue
ResolvedBool :: !Bool -> ResolvedValue
ResolvedRReference :: !String -> !ResolvedValue -> ResolvedValue
ResolvedArray :: ![ResolvedValue] -> ResolvedValue
ResolvedHash :: ![(String, ResolvedValue)] -> ResolvedValue
ResolvedUndefined :: ResolvedValue

-- | This type holds a value that is either from the ASL or fully resolved.
type GeneralValue = Either Expression ResolvedValue

-- | This type holds a value that is either from the ASL or a fully
--   resolved String.
type GeneralString = Either Expression String

-- | This describes the resources before the final resolution. This is
--   required as they must somehow be collected while the <a>Statement</a>s
--   are interpreted, but the necessary <a>Expression</a>s are not yet
--   available. This is because in Puppet the <a>Statement</a> order should
--   not alter the catalog's content.
--   
--   The relations are not stored here, as they are pushed into a separate
--   internal data structure by the interpreter.
data CResource
CResource :: Int -> GeneralString -> String -> [(GeneralString, GeneralValue)] -> Virtuality -> SourcePos -> CResource

-- | Resource ID, used in the Puppet YAML.
crid :: CResource -> Int

-- | Resource name.
crname :: CResource -> GeneralString

-- | Resource type.
crtype :: CResource -> String

-- | Resource parameters.
crparams :: CResource -> [(GeneralString, GeneralValue)]

-- | Resource virtuality.
crvirtuality :: CResource -> Virtuality

-- | Source code position of the resource definition.
pos :: CResource -> SourcePos

-- | Resource identifier, made of a type, name pair.
type ResIdentifier = (String, String)

-- | Resource relation, made of a <a>LinkType</a>, <a>ResIdentifier</a>
--   pair.
type Relation = (LinkType, ResIdentifier)

-- | This is a fully resolved resource that will be used in the
--   <a>FinalCatalog</a>.
data RResource
RResource :: !Int -> !String -> !String -> !Map String ResolvedValue -> ![Relation] -> !SourcePos -> RResource

-- | Resource ID.
rrid :: RResource -> !Int

-- | Resource name.
rrname :: RResource -> !String

-- | Resource type.
rrtype :: RResource -> !String

-- | Resource parameters.
rrparams :: RResource -> !Map String ResolvedValue

-- | Resource relations.
rrelations :: RResource -> ![Relation]

-- | Source code position of the resource definition.
rrpos :: RResource -> !SourcePos
type FinalCatalog = Map ResIdentifier RResource
type ScopeName = String

-- | Type of update/override, so they can be applied in the correct order.
--   This part is probably not behaving like vanilla puppet, as it turns
--   out this are many fairly acceptable behaviours and the correct one is
--   not documented.
data RelUpdateType
UNormal :: RelUpdateType
UOverride :: RelUpdateType
UDefault :: RelUpdateType
UPlus :: RelUpdateType

-- | A data type to hold defaults values
data ResDefaults
RDefaults :: String -> [(GeneralString, GeneralValue)] -> SourcePos -> ResDefaults
ROverride :: String -> GeneralString -> [(GeneralString, GeneralValue)] -> SourcePos -> ResDefaults

-- | The most important data structure for the interpreter. It stores its
--   internal state.
data ScopeState
ScopeState :: ![[ScopeName]] -> !Map String (GeneralValue, SourcePos) -> !Map String SourcePos -> ![ResDefaults] -> !Int -> !SourcePos -> !Map (TopLevelType, String) Statement -> (TopLevelType -> String -> IO (Either String Statement)) -> ![String] -> ![CResource -> CatalogMonad Bool] -> ![([(LinkType, GeneralValue, GeneralValue)], (String, GeneralString), RelUpdateType, SourcePos)] -> (String -> String -> [(String, GeneralValue)] -> IO (Either String String)) -> ScopeState

-- | The list of scopes. It works like a stack, and its initial value must
--   be <tt>[["::"]]</tt>. It is a stack of lists of strings. These lists
--   can be one element wide (usual case), or two elements (inheritance),
--   so that variables could be assigned to both scopes.
curScope :: ScopeState -> ![[ScopeName]]

-- | The list of known variables. It should be noted that the interpreter
--   tries to resolve them as soon as it can, so that it can store their
--   current scope.
curVariables :: ScopeState -> !Map String (GeneralValue, SourcePos)

-- | The list of classes that have already been included, along with the
--   place where this happened.
curClasses :: ScopeState -> !Map String SourcePos

-- | List of defaults to apply. All defaults are applied at the end of the
--   interpretation of each top level statement.
curDefaults :: ScopeState -> ![ResDefaults]

-- | Stores the value of the current <a>crid</a>.
curResId :: ScopeState -> !Int

-- | Current position of the evaluated statement. This is mostly used to
--   give useful error messages.
curPos :: ScopeState -> !SourcePos

-- | List of "top levels" that have been parsed inside another top level.
--   Their behaviour is curently non canonical as the scoping rules are
--   unclear.
nestedtoplevels :: ScopeState -> !Map (TopLevelType, String) Statement

-- | This is a function that, given the type of a top level statement and
--   its name, should return it.
getStatementsFunction :: ScopeState -> TopLevelType -> String -> IO (Either String Statement)

-- | List of warnings.
getWarnings :: ScopeState -> ![String]

-- | A bit complicated, this stores the collection functions. These are
--   functions that determine whether a resource should be collected or
--   not.
curCollect :: ScopeState -> ![CResource -> CatalogMonad Bool]

-- | This stores unresolved relationships, because the original string name
--   can't be resolved. Fieds are [ ( [dstrelations], srcresource, type,
--   pos ) ]
unresolvedRels :: ScopeState -> ![([(LinkType, GeneralValue, GeneralValue)], (String, GeneralString), RelUpdateType, SourcePos)]

-- | Function that takes a filename, the current scope and a list of
--   variables. It returns an error or the computed template.
computeTemplateFunction :: ScopeState -> String -> String -> [(String, GeneralValue)] -> IO (Either String String)

-- | The monad all the interpreter lives in. It is <a>ErrorT</a> with a
--   state.
type CatalogMonad = ErrorT String (StateT ScopeState IO)
generalizeValueE :: Expression -> GeneralValue
generalizeValueR :: ResolvedValue -> GeneralValue
generalizeStringE :: Expression -> GeneralString
generalizeStringS :: String -> GeneralString
instance Show LinkType
instance Ord LinkType
instance Eq LinkType
instance Show ResolvedValue
instance Eq ResolvedValue
instance Ord ResolvedValue
instance Show CResource
instance Show RResource
instance Ord RResource
instance Eq RResource
instance Show RelUpdateType
instance Ord RelUpdateType
instance Eq RelUpdateType
instance Show ResDefaults
instance Ord ResDefaults
instance Eq ResDefaults


-- | This is a helper module for the <a>Puppet.Daemon</a> module
module Puppet.Init
data Prefs
Prefs :: FilePath -> FilePath -> FilePath -> Int -> Int -> Prefs

-- | The path to the manifests.
manifest :: Prefs -> FilePath

-- | The path to the modules.
modules :: Prefs -> FilePath

-- | The path to the template.
templates :: Prefs -> FilePath

-- | Size of the compiler pool.
compilepoolsize :: Prefs -> Int

-- | Size of the parser pool.
parsepoolsize :: Prefs -> Int

-- | Generates the <a>Prefs</a> structure from a single path.
--   
--   <pre>
--   genPrefs "/etc/puppet"
--   </pre>
genPrefs :: String -> Prefs

-- | Generates <a>Facts</a> from pairs of strings.
--   
--   <pre>
--   genFacts [("hostname","test.com")]
--   </pre>
genFacts :: [(String, String)] -> Facts
instance Show Prefs

module Puppet.Printers
showRes :: CResource -> IO ()
showRRes :: RResource -> IO ()
showFCatalog :: FinalCatalog -> String


-- | These are the function and data types that are used to define the
--   Puppet native types.
module Puppet.NativeTypes.Helpers
type PuppetTypeName = String

-- | This is a function type than can be bound. It is the type of all
--   subsequent validators.
type PuppetTypeValidate = RResource -> Either String RResource
data PuppetTypeMethods
PuppetTypeMethods :: PuppetTypeValidate -> Set String -> PuppetTypeMethods
puppetvalidate :: PuppetTypeMethods -> PuppetTypeValidate
puppetfields :: PuppetTypeMethods -> Set String
faketype :: PuppetTypeName -> (PuppetTypeName, PuppetTypeMethods)
defaulttype :: PuppetTypeName -> (PuppetTypeName, PuppetTypeMethods)

-- | This helper will validate resources given a list of fields. It will
--   run <a>checkParameterList</a> and then <a>addDefaults</a>.
defaultValidate :: Set String -> PuppetTypeValidate

-- | This validator checks that no unknown parameters have been set (except
--   tag)
checkParameterList :: Set String -> PuppetTypeValidate

-- | This validator always accept the resources, but add the default
--   parameters (such as title and name).
addDefaults :: PuppetTypeValidate

-- | This checks that a given parameter is a string. If it is a
--   <a>ResolvedInt</a> or <a>ResolvedBool</a> it will convert them to
--   strings.
string :: String -> PuppetTypeValidate

-- | Makes sure that the parameter, if defined, has a value among this
--   list.
values :: [String] -> String -> PuppetTypeValidate

-- | This fills the default values of unset parameters.
defaultvalue :: String -> String -> PuppetTypeValidate
insertparam :: RResource -> String -> ResolvedValue -> RResource

-- | Checks that a given parameter, if set, is a <a>ResolvedInt</a>. If it
--   is a <a>ResolvedString</a> it will attempt to parse it.
integer :: String -> PuppetTypeValidate

-- | Helper that takes a list of stuff and will generate a validator.
parameterFunctions :: [(String, [String -> PuppetTypeValidate])] -> PuppetTypeValidate


-- | This module holds the <i>native</i> Puppet resource types.
module Puppet.NativeTypes

-- | The map of native types. They are described in
--   <a>Puppet.NativeTypes.Helpers</a>.
nativeTypes :: Map PuppetTypeName PuppetTypeMethods


-- | This module exports the <a>getCatalog</a> function, that computes
--   catalogs from parsed manifests. The behaviour of this module is
--   probably non canonical on many details. The problem is that most of
--   Puppet behaviour is undocumented or extremely vague. It might be
--   possible to delve into the source code or to write tests, but ruby is
--   unreadable and tests are boring.
--   
--   Here is a list of known discrepencies with Puppet :
--   
--   <ul>
--   <li>Variables coming from an inherited class can only be referenced
--   using the scope of the child class.</li>
--   <li>Resources references using the <a>| |</a> syntax are not yet
--   supported.</li>
--   </ul>
module Puppet.Interpreter.Catalog
getCatalog :: (TopLevelType -> String -> IO (Either String Statement)) -> (String -> String -> [(String, GeneralValue)] -> IO (Either String String)) -> String -> Facts -> IO (Either String FinalCatalog, [String])


-- | This module exports the functions that will be useful to parse the
--   DSL. They should be able to parse everything you throw at them. The
--   Puppet language is extremely irregular, and most valid constructs are
--   not documented in the official language guide. This parser has been
--   created by parsing the author's own large manifests and the public
--   Wikimedia ones.
--   
--   Things that are known to not to be properly supported are :
--   
--   <ul>
--   <li>"plussignement" such as foo +&gt; bar. How to handle this is far
--   from being obvious, as its actual behaviour is not documented.</li>
--   </ul>
module Puppet.DSL.Parser

-- | <tt>parse p filePath input</tt> runs a parser <tt>p</tt> over Identity
--   without user state. The <tt>filePath</tt> is only used in error
--   messages and may be the empty string. Returns either a
--   <a>ParseError</a> (<a>Left</a>) or a value of type <tt>a</tt>
--   (<a>Right</a>).
--   
--   <pre>
--   main    = case (parse numbers "" "11, 2, 43") of
--              Left err  -&gt; print err
--              Right xs  -&gt; print (sum xs)
--   
--   numbers = commaSep integer
--   </pre>
parse :: Stream s Identity t => Parsec s () a -> SourceName -> s -> Either ParseError a
mparser :: ParsecT String u Identity [Statement]

-- | This is a parser for Puppet <a>Expression</a>s.
exprparser :: ParsecT String u Identity Expression

module Puppet.DSL.Loader

-- | Helper function that takes a filename and parses its content in the
--   <a>ErrorT</a> monad.
parseFile :: FilePath -> ErrorT String IO [Statement]

module Puppet.Daemon

-- | This is a high level function, that will initialize the parsing and
--   interpretation infrastructure from the <a>Prefs</a> structure, and
--   will return a function that will take a node name, <a>Facts</a> and
--   return either an error or the <a>FinalCatalog</a>.
--   
--   It will internaly initialize several threads that communicate with
--   channels. It should scale well, althrough it hasn't really been tested
--   yet. It should cache the ASL of every .pp file, and could use a bit of
--   memory. As a comparison, it fits in 60 MB with the author's manifests,
--   but really breathes when given 300 MB of heap space. In this
--   configuration, even if it spawns a ruby process for every template
--   evaluation, it is way faster than the puppet stack.
--   
--   It is recommended to ask for as many parser and interpreter threads as
--   there are CPUs.
--   
--   Known bugs :
--   
--   <ul>
--   <li>It might be buggy when top level statements that are not
--   class<i>define</i>nodes are altered, or when files loaded with require
--   are changed.</li>
--   <li>Exported resources are not yet supported.</li>
--   <li>The catalog is not computed exactly the same way Puppet does. Take
--   a look at <a>Puppet.Interpreter.Catalog</a> for a list of
--   differences.</li>
--   <li>Parsing incompatibilities are listed in
--   <a>Puppet.DSL.Parser</a>.</li>
--   <li>There might be race conditions because file status are checked
--   before they are opened. This means the program might end with an
--   exception when the file is not existent. This will need fixing.</li>
--   </ul>
initDaemon :: Prefs -> IO (String -> Facts -> IO (Either String FinalCatalog))
instance Show DaemonStats