Puppet Strings has two flags to the generate action that can be used to emit JSON data:
--emit-json <file>: Emits the JSON data to the given file.--emit-json-stdout: Emits the JSON data to STDOUT.
At the top level, there are five arrays in the JSON document:
| Document Key | Description |
|---|---|
| puppet_classes | The list of Puppet classes that were parsed. |
| defined_types | The list of defined types that were parsed. |
| resource_types | The list of resource types that were parsed. |
| providers | The list of resource providers that were parsed. |
| puppet_functions | The list of Puppet functions (3.x, 4.x and Puppet language) that were parsed. |
Each entry in the puppet_classes list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the Puppet class. |
| file | The file defining the Puppet class. |
| line | The line where the Puppet class is defined. |
| inherits | The name of the Puppet class the class inherits from. |
| docstring | The DocString object for the class (see below). |
| defaults | The map of parameter names to default values. |
| source | The Puppet source code for the class. |
Each entry in the defined_types list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the defined type. |
| file | The file defining the defined type. |
| line | The line where the defined type is defined. |
| docstring | The DocString object for the defined type (see below). |
| defaults | The map of parameter names to default values. |
| source | The Puppet source code for the defined type. |
Each entry in the resource_types list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the resource type. |
| file | The file defining the resource type. |
| line | The line where the resource type is defined. |
| docstring | The DocString object for the resource type (see below). |
| properties | The list of properties for the resource type (see below). |
| parameters | The list of parameters for the resource type (see below). |
| features | The list of features for the resource type (see below). |
Each entry in the properties list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the property. |
| description | The description of the property. |
| values | The array of acceptable string values for the property. |
| aliases | The map of new values aliased to existing values. |
| isnamevar | True if the property is a namevar or false if not. |
| default | The default value for the property. |
Each entry in the parameters list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the parameter. |
| description | The description of the parameter. |
| values | The array of acceptable string values for the parameter. |
| aliases | The map of new values aliased to existing values. |
| isnamevar | True if the parameter is a namevar or false if not. |
| default | The default value for the parameter. |
Each entry in the features list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the feature. |
| description | The description of the feature. |
Each entry in the providers list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the provider. |
| type_name | The name of the resource type of the provider. |
| file | The file defining the provider. |
| line | The line where the provider is defined. |
| docstring | The DocString object for the provider (see below). |
| confines | The string map of confines for the provider. |
| features | The list of features implemented by the provider. |
| defaults | The list of lists of "default for" for the provider. |
| commands | The string map of commands for the provider. |
Each entry in the puppet_functions list is an object with the following attributes:
| Attribute Key | Description |
|---|---|
| name | The name of the function. |
| file | The file defining the provider. |
| line | The line where the provider is defined. |
| type | The function type (e.g. ruby3x, ruby4x, puppet). |
| signatures | A list of Puppet signatures of the function, including overloads if present. |
| docstring | The DocString object for the function (see below). |
| defaults | The map of parameter names to default values. |
| source | The source code for the function. |
The signatures key is a function-specific list containing an object for each signature of a
function. Each object includes the signature itself, as well as each of its param and return
tags. Puppet 4.x functions with overloads will contain multiple signatures, while other function
types will contain only one.
Each signature is represented as an object with the following attributes:
| Attribute Key | Description |
|---|---|
| signature | The signature of the function. |
| docstring | The DocString object describing the signature, which includes text, param and return tags. |
For the above types, their docstrings are represented as an object with the following attributes:
| Attribute Key | Description |
|---|---|
| text | The textual part of the DocString. |
| tags | The array of tag objects, if any are present. |
Each entry in the tags list is an object with the following properties:
| Attribute Key | Description |
|---|---|
| tag_name | The name of the tag (e.g. param, return, etc.). |
| text | The descriptive text of the tag. |
| types | The array of types associated with the tag. |
| name | The name associated with the tag (e.g. parameter name). |
For Puppet 4.x functions with overloads, overload tags will contain three additional attributes:
| Attribute Key | Description |
|---|---|
| signature | The Puppet signature of the overload. |
| docstring | The DocString object describing the overload. |
| defaults | The map of parameter names to default values. |
An example JSON document describing a Puppet class, defined type, resource type, provider, and Puppet functions:
{
"puppet_classes": [
{
"name": "foo",
"file": "site.pp",
"line": 5,
"inherits": "foo::bar",
"docstring": {
"text": "A simple class.",
"tags": [
{
"tag_name": "param",
"text": "First param.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "Second param.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "Third param.",
"types": [
"String"
],
"name": "param3"
}
]
},
"defaults": {
"param3": "hi"
},
"source": "class foo(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}"
}
],
"defined_types": [
{
"name": "dt",
"file": "site.pp",
"line": 12,
"docstring": {
"text": "A simple defined type.",
"tags": [
{
"tag_name": "param",
"text": "First param.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "Second param.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "Third param.",
"types": [
"String"
],
"name": "param3"
}
]
},
"defaults": {
"param3": "hi"
},
"source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}"
}
],
"resource_types": [
{
"name": "database",
"file": "database.rb",
"line": 43,
"docstring": {
"text": "An example database server resource type."
},
"properties": [
{
"name": "ensure",
"description": "What state the database should be in.",
"values": [
"present",
"absent",
"up",
"down"
],
"aliases": {
"up": "present",
"down": "absent"
},
"default": "up"
},
{
"name": "file",
"description": "The database file to use."
},
{
"name": "log_level",
"description": "The log level to use.",
"values": [
"debug",
"warn",
"error"
],
"default": "warn"
}
],
"parameters": [
{
"name": "address",
"description": "The database server name.",
"isnamevar": true
},
{
"name": "encryption_key",
"description": "The encryption key to use."
},
{
"name": "encrypt",
"description": "Whether or not to encrypt the database.",
"values": [
"true",
"false",
"yes",
"no"
],
"default": "false"
}
],
"features": [
{
"name": "encryption",
"description": "The provider supports encryption."
}
]
}
],
"providers": [
{
"name": "linux",
"type_name": "database",
"file": "linux.rb",
"line": 33,
"docstring": {
"text": "An example provider on Linux."
},
"confines": {
"kernel": "Linux",
"osfamily": "RedHat"
},
"features": [
"implements_some_feature",
"some_other_feature"
],
"defaults": [
[
[
"kernel",
"Linux"
]
],
[
[
"osfamily",
"RedHat",
],
[
"operatingsystemmajrelease",
"7"
]
]
],
"commands": {
"foo": "/usr/bin/foo"
}
}
],
"puppet_functions": [
{
"name": "func",
"file": "site.pp",
"line": 20,
"type": "puppet",
"signatures": [
{
"signature": "func(Integer $param1, Any $param2, String $param3 = hi)",
"docstring": {
"text": "A simple function.",
"tags": [
{
"tag_name": "param",
"text": "First param.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "Second param.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "Third param.",
"types": [
"String"
],
"name": "param3"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
}
}
],
"docstring": {
"text": "A simple function.",
"tags": [
{
"tag_name": "param",
"text": "First param.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "Second param.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "Third param.",
"types": [
"String"
],
"name": "param3"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
},
"defaults": {
"param3": "hi"
},
"source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}"
},
{
"name": "func3x",
"file": "func3x.rb",
"line": 1,
"type": "ruby3x",
"signatures": [
{
"signature": "func3x(String $first, Any $second)",
"docstring": {
"text": "An example 3.x function.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"String"
],
"name": "first"
},
{
"tag_name": "param",
"text": "The second parameter.",
"types": [
"Any"
],
"name": "second"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
}
}
],
"docstring": {
"text": "An example 3.x function.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"String"
],
"name": "first"
},
{
"tag_name": "param",
"text": "The second parameter.",
"types": [
"Any"
],
"name": "second"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
},
"source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend"
},
{
"name": "func4x",
"file": "func4x.rb",
"line": 11,
"type": "ruby4x",
"signatures": [
{
"signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
"docstring": {
"text": "The first overload.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "The second parameter.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "The third parameter.",
"types": [
"Optional[Array[String]]"
],
"name": "param3"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
}
},
{
"signature": "func4x(Boolean $param, Callable &$block)",
"docstring": {
"text": "The second overload.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Boolean"
],
"name": "param"
},
{
"tag_name": "param",
"text": "The block parameter.",
"types": [
"Callable"
],
"name": "&block"
},
{
"tag_name": "return",
"text": "Returns a string.",
"types": [
"String"
]
}
]
}
}
],
"docstring": {
"text": "An example 4.x function.",
"tags": [
{
"tag_name": "overload",
"signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
"docstring": {
"text": "The first overload.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Integer"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "The second parameter.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "The third parameter.",
"types": [
"Optional[Array[String]]"
],
"name": "param3"
},
{
"tag_name": "return",
"text": "Returns nothing.",
"types": [
"Undef"
]
}
]
},
"name": "func4x"
},
{
"tag_name": "overload",
"signature": "func4x(Boolean $param, Callable &$block)",
"docstring": {
"text": "The second overload.",
"tags": [
{
"tag_name": "param",
"text": "The first parameter.",
"types": [
"Boolean"
],
"name": "param"
},
{
"tag_name": "param",
"text": "The block parameter.",
"types": [
"Callable"
],
"name": "&block"
},
{
"tag_name": "return",
"text": "Returns a string.",
"types": [
"String"
]
}
]
},
"name": "func4x"
}
]
},
"source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return [Undef] Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n end\n\n # The second overload.\n # @param param The first parameter.\n # @param block The block parameter.\n # @return [String] Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n end\nend"
}
]
}