module Puppet::Pops

The Pops language system. This includes the parser, evaluator, AST model, and Binder.

@todo Explain how a user should use this to parse and evaluate the puppet

language.

@note Warning: Pops is still considered experimental, as such the API may

change at any time.

@api public

Adaptable is a mix-in module that adds adaptability to a class. This means that an adapter can associate itself with an instance of the class and store additional data/have behavior.

This mechanism should be used when there is a desire to keep implementation concerns separate. In Ruby it is always possible to open and modify a class or instance to teach it new tricks, but it is however not possible to do this for two different versions of some service at the same time. The Adaptable pattern is also good when only a few of the objects of some class needs to have extra information (again possible in Ruby by adding instance variables dynamically). In fact, the implementation of Adaptable does just that; it adds an instance variable named after the adapter class and keeps an instance of this class in this slot.

@note the implementation details; the fact that an instance variable is used to keep the adapter

instance data should not
be exploited as the implementation of _being adaptable_ may change in the future.

@api private

The Adapters module contains adapters for Documentation, Origin, SourcePosition, and Loader.

Defines classes to deal with issues, and message formatting and defines constants with Issues. @api public

Loader

A Loader is responsible for loading “entities” (“instantiable and executable objects in the puppet language” which are type, hostclass, definition, function, and bindings.

The main method for users of a Loader is the `load` or `load_typed methods`, which returns a previously loaded entity of a given type/name, and searches and loads the entity if not already loaded.

private entities


TODO: handle loading of entities that are private. Suggest that all calls pass an origin_loader (the loader where request originated (or symbol :public). A module loader has one (or possibly a list) of what is considered to represent private loader - i.e. the dependency loader for a module. If an entity is private it should be stored with this status, and an error should be raised if the origin_loader is not on the list of accepted “private” loaders. The private loaders can not be given at creation time (they are parented by the loader in question). Another alternative is to check if the origin_loader is a child loader, but this requires bidirectional links between loaders or a search if loader with private entity is a parent of the origin_loader).

@api public

LoaderPaths

The central loader knowledge about paths, what they represent and how to instantiate from them. Contains helpers (*smart paths*) to deal with lazy resolution of paths.

TODO: Currently only supports loading of functions (2 kinds)

to boot.

The TypeDefinitionInstantiator instantiates a type alias or a type definition

This class is the backing implementation of the Puppet function 'lookup'. See puppet/functions/lookup.rb for documentation.

Factory is a helper class that makes construction of a Pops Model much more convenient. It can be viewed as a small internal DSL for model constructions. For usage see tests using the factory.

@todo All those uppercase methods … they look bad in one way, but stand out nicely in the grammar…

decide if they should change into lower case names (some of the are lower case)...

An implementation of the interface Puppet::Resource that adapts the 3.x compiler and catalog expectations on a resource instance. This instance is backed by a pcore representation of the resource type an instance of this ruby class.

This class must inherit from Puppet::Resource because of the class expectations in existing logic.

This implementation does not support

@abstract base class for PObjectType and other types that implements lazy evaluation of content @api private

This class provides parsing of Type Specification from a string into the Type Model that is produced by the TypeFactory.

The Type Specifications that are parsed are the same as the stringified forms of types produced by the {TypeCalculator TypeCalculator}.

@api public

Provides utility methods

Constants

DOUBLE_COLON
EMPTY_ARRAY
EMPTY_HASH
EMPTY_STRING
MAX_INTEGER
MIN_INTEGER
USCORE