The `puppetresources` command is a command line utility that let you interactively compute catalogs on your local computer.It is much faster than its ruby counterpart, and has been designed for giving assistance to the Puppet catalog writer.

There are 4 different modes:

* `--node` will display all resources on screen in a nice user-friendly colored fashion.* `--all` displays statitics and optionally shows dead code.* `--parse` only goes as far as parsing. No interpretation.* `--showcontent` to display file content.

Catalog is not computed exactly the same way Puppet does. Some good practices are enforced. A strict and more permissive mode are provided.

=== Command line arguments

`-p` or `--puppetdir`::

This argument is mandatory except in `parse` mode. It must point to the base of the puppet directory (the directory that contains the `modules` and `manifests` directories).

`-o` or `--node`::

Enable the `node mode`. This let you specify the name of the node you wish to compute the catalog for.

`-a` or `--all`::

Enable the `stats mode`. If you specify `allnodes` it will compute the catalogs for all nodes that are specified in `site.pp` (this will not work for regexp-specified or the default nodes). You can also specify a list of nodes separated by a comma.+Combined with `--deadcode`, it will display the list of puppet files that have not been used.+This is useful as automated tests, to check a change didn't break something. You might want to run this option with `+RTS -N`.

`-t` or `--type`::

Filters the resources of the resulting catalog by type. Using PCRE regex is supported.

`-n` or `--name`::

Filters the resources of the resulting catalog by name. Using PCRE regex is supported.

`-c` or `--showcontent`::

If `-n` is the exact name of a file type resource defined in the catalog, this will display the file content nicely. Useful for debugging templates.+Example: `puppetresources -p . -o mynodename -n '/etc/motd' --showcontent`

`--loglevel` or `-v`::

Possible values are : DEBUG, INFO, NOTICE, WARNING, ERROR

`--pdburl`::

Expects the url of a live PuppetDB.

`--pdbfile`::

Expects a path to a *fake* PuppetDB, represented as a YAML file on disk. This option is pretty slow but can be invaluable to test exported resources tricks.

`--hiera`::

Expects the path to the `hiera.yaml` file.

`--ignoredmodules`::

Expects a list of comma-separated modules. The interpreter will not try to parse and evaluate the defined types and classes from this module. This is useful for using modules that use badpractices forbidden by `puppetresources`.

`--commitdb`::

When this flag is set, exported resources, catalogs and facts are saved in the PuppetDB. This is useful in conjunction with `--pdbfile`.

`--checkExported`::

When this flag is set, exported resources are saved in the PuppetDB. This is useful in conjunction with `--pdbfile`.

`-j` or `--JSON`::

Displays the catalog as a Puppet-compatible JSON file, that can then be used with `puppet apply`.

`--strict`::

Enable strict check.Strict is less permissive than vanilla Puppet.It is meant to prevent some pitfalls by enforcing good practices.For instance it refuses to - silently ignore/convert `undef` variables - lookup an hash with an unknown key and return `undef`.

`--noextratests`::

Disable the extra tests from `Puppet.OptionalTests`.

`--parse`::

Enable `parse mode`. Specify the puppet file to be parsed. Variables are not resolved. No interpretation.

`--version`::

Output version information and exist.

=== Settings defaults using a yaml file

Defaults for some of these options can be set using a `/yourworkingdirectory/tests/defaults.yaml` file. For instance `OptionalTests` is checking that all users and groups are known. Because some of these users and groups might be defined outside puppet, a list of known ones is used internally. This can be overridden in that file using the key `knownusers` and `knowngroups`.

Please look at https://github.com/bartavelle/language-puppet/blob/master/tests/defaults.yaml[the template file] for a list of possible defaults.

== pdbQuery

The `pdbquery` command will work with different implementations of PuppetDB (the official one with its HTTP API, the file-based backend and dummy ones). It can be used to:

* export data from production PuppetDB to a file (in order to debug some issue with `puppetresources`).* query a Puppetdb

Here is a list of command line arguments :

`-l` or `--location`::

The URL of the PuppetDB when working with a remote PuppetDB, a file path when working with the file-based test implementation.

* External Lua plugins are not a thing anymore * `validate_numeric` function * Preliminary implementation of variable captures in regexp matches * Ready for GHC 8 and corresponding stackage nightly * Fixed a deadlock when template code called the `template` or `inline_template` functions. It just stops now :( * `assert_private` function * `join_keys_to_values` function * Several resource collector misbehaviour * Case expressions can now have multiple matchers of any kind as the same selector

* The `regsubst` function now works with arrays. * The `file` variable is resolved in templates. * Support for `function_x` calls in templates. * Expressions such as (-1) are now supported. * Selectors recognize the undef token now. * Fixed a bug with parsing lines starting with `::`. * Sanitize resource names in some missing instances to fix bugs

* Support for the `$settings` variables. * Support for the `to_yaml` function in templates. * Settings can now be altered in the default YAML file. * Defaults and overriden facts are now controlled in the YAML file too.

* New `dumpinfos` debug function. * The interpreter can now run in a strict or permissive mode. * The new `-a` option accepts a comma separated list of nodes for gathering stats. * The new `--noextratests` option disable optional tests from `Puppet.OptionalTests`. * Implementation of `member()` from stdlib (see issue #100 for details) * Exported/virtual custom types are not expanded. This is a huge bug. * Class/define parameters that are explicitely set as undefined are now overriden by * Empty resource groups are now rejected. * An existing resource can now be realized. * Hiera config interpolation logs decrease from WARN to NOTICE * Remove option `--nousergrouptest` * Ease the use of the puppetresources command options. See the README file for changes.

* Support for the `join` function. * Support for filtering json puppetresources output (fix issue #64) * Support for `cmpversion` in the templates. * The various chaining modes have been implemented. * Support for the `is_bool` function (Pierre Radermecker) * Support for `concat` and `concat::fragment` (Pierre Radermecker) * Fix array value extrapolation in string (issue #35) * ${var} without quotes will now be rejected by the parser (issue #78) * `README` moved to asciidoc (Pierre Radermecker)

* Support for Debian distribution detection in facter. * Support for the "~>" operator. * Support for mixed-case resource references. * Added the `grep` function. * Better support for --ignoremodules. * Fixed parsing of standalone `$` characters in strings.

* Overhauled the dependency check system * Added an option to skip the user and group checks * Added an option to ignore some modules * Added `vagrant`, `nagios`, `www-data`, `postgres` and `nginx` to the list of known users. * Fixed how resource relationships were resolved with notify and before. * Fixed a problem where inheritance whould be used with `::` prefix. * The `defined` function now works with classes. * All numbers are now strings in templates.

* Hacky support for `scope.get_hash`. * New stuff from the new parser (adding hashes, arrays, etc.). * Wrote a pure evaluation function, for unit tests and prisms. * `Num` and `Fractional` instances for `Expression`. * Numbers are now internally stored as numbers, just like the new parser does. * Add support for "structured facts". * New stdlib functions: `is_hash`, `has_key`, `size`, `values`. * Puppetresources does not fail tests for file sources starting with `file://`. * Escaped characters were not properly handled in the parser. * Properly catch division by 0 (!!!!). * Got rid of the orphan instances ... code is now a lot uglier. * Fixed settings of "title" and "name" in classes. The original puppet version * Fixed associativity priority between `=~` and `and`.

* The scope tracking system has been improved. It is now possible to know * is_virtual fact * new stdlib functions: flatten, str2bool, validate_absolute_path * Hiera support * JSON output that is compatible with "puppet apply" * New addfacts command for the pdbquery utility * Support for the classes variable in templates * Support for @instance variables in inline_template * Support for scope['key'] syntax in templates * Support for facts overriding with puppetresources * Deserialization problems with puppetDBs * Fixed several bugs with imported resources * Bug with relationships overrides that got stored as parameters * Importing several exported resources from the same class now works * Templates with an invalid encoding could crash the process * Yaml parse errors of the puppetdb file now throw errors

* Map/each/filter functions with lambdas (not really tested) * Rewrite of the PuppetDB API * The whole scope stack is kept with each Resource, for easier debugging * Inclusion of three PuppetDB backends : dummy (no effect), TestDB (stored * This is a hack : variables declared in a parent (inheritance) can now be

* Big refactor of the PuppetDB API. * New "fake" PuppetDB used for testing * Support of the caller_module_name variable. * Support for a dumpvariable() function. * More details stored in the resource types, and in error messages. * User native type * Removal of the MissingH, filepath, monad-loop and directory dependency * Puppet booleans are now handled at parse stage * inline_template function * fqdn_rand now puppet perfect (at least for 32 bit max values) * Now depends on the built-in bytestring library that comes with * Aliases should now work as expected ... I wish! * regexp_subs now works in a PCRE manner * Destination dependency can now be a variable resolving in an array.

* The defaults system was pretty much broken, it should be better now. * Basic testing framework started. * create_resources now supports the defaults system. * defined() function works for resource references. * in operator implemented for hashes. * Multithreading works. * The ruby <> daemon communication is now over ByteStrings. * The toRuby function has been optimized, doubling the overall speed for * Various internal changes.

* Various details have been modified since the official language * Better handling of collector conditions. * Solves bug with interpolable strings that are not resolved when first * Amending attributes with a collector. * Stdlib functions : chomp * Resource pretty printer now aligns =>. * Case statements with regexps.

* Basic native template function. * Added anchor as a native type for now. A better fix will be to just parse * Tentative defined() implementation. Will not work for resource references. * Functions md5, sha1, lowcase, upcase, split. * String comparison is not case insensitive. * Variable scope for inherited classes should now work. * Support for the $module_name variable (probably a bit buggy). * Proper location of a "define not found" error. * Parsing bug for single quoted strings and slashes. * Bug where a resource name is a variable that is actually an array. * Array indexing. * Top level variables are now supported in Erb. * Removed the title parameter from the catalog printing functions. * Used hslint a bit.