kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
puppet-strings/JSON.md

803 lines
27 KiB
Markdown
Raw Permalink Normal View History

(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
Puppet Strings JSON Data
========================
(maint) update various documentation This updates various docs in the project. * Get rid of MAINTAINERS * Update JSON.md with tasks and plans * Fix some weirndess in the README * Polish CONTRIBUTING.md
2018-04-25 08:06:42 +00:00
Puppet Strings can generate JSON to STDOUT with the `--format` option:
```shell
puppet strings generate --format json
```
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
Document Schema
===============
(maint) update various documentation This updates various docs in the project. * Get rid of MAINTAINERS * Update JSON.md with tasks and plans * Fix some weirndess in the README * Polish CONTRIBUTING.md
2018-04-25 08:06:42 +00:00
At the top level, there are seven arrays in the JSON document:
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
| 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. |
(maint) update various documentation This updates various docs in the project. * Get rid of MAINTAINERS * Update JSON.md with tasks and plans * Fix some weirndess in the README * Polish CONTRIBUTING.md
2018-04-25 08:06:42 +00:00
| puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. |
| puppet_tasks | The list of Puppet tasks that were parsed. |
| puppet_plans | The list of Puppet plans that were parsed. |
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
Puppet Classes
--------------
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. |
Defined Types
-------------
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. |
Resource Types
--------------
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. |
Providers
---------
Each entry in the `providers` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ---------------------------------------------------- |
| name | The name of the provider. |
(PDOC-95) Properly group and display multiple provider `defaultfor`s Prior to this commit, strings did not properly handle providers which had multiple related `defaultfor`s. In code, these are written as comma-separated constraints. This commit updates strings' puppet provider handler, as well as the template which generates HTML for `defaultfor` statements. Note that it was necessary to make a breaking change to the JSON schema to accomodate multiple AND'ed defaults. Previously, provider defaults were contained in a single key-value map. Now, they are contained in an array of key-value lists, which allows multiple constraints to be associated with each other.
2016-10-11 19:45:17 +00:00
| type_name | The name of the resource type of the provider. |
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
| 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. |
(PDOC-95) Properly group and display multiple provider `defaultfor`s Prior to this commit, strings did not properly handle providers which had multiple related `defaultfor`s. In code, these are written as comma-separated constraints. This commit updates strings' puppet provider handler, as well as the template which generates HTML for `defaultfor` statements. Note that it was necessary to make a breaking change to the JSON schema to accomodate multiple AND'ed defaults. Previously, provider defaults were contained in a single key-value map. Now, they are contained in an array of key-value lists, which allows multiple constraints to be associated with each other.
2016-10-11 19:45:17 +00:00
| defaults | The list of lists of "default for" for the provider. |
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
| commands | The string map of commands for the provider. |
Puppet Functions
----------------
Each entry in the `puppet_functions` list is an object with the following attributes:
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
| Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- |
| name | The name of the function. |
(maint) update various documentation This updates various docs in the project. * Get rid of MAINTAINERS * Update JSON.md with tasks and plans * Fix some weirndess in the README * Polish CONTRIBUTING.md
2018-04-25 08:06:42 +00:00
| file | The file defining the function. |
| line | The line where the function is defined. |
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
| 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. |
(maint) update various documentation This updates various docs in the project. * Get rid of MAINTAINERS * Update JSON.md with tasks and plans * Fix some weirndess in the README * Polish CONTRIBUTING.md
2018-04-25 08:06:42 +00:00
Puppet Tasks
------------
Each entry in the `puppet_tasks` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- |
| name | The name of the task. |
| file | The file defining the task. |
| line | The line where the task is defined. |
| docstring | The *DocString* object for the task (see below). |
| source | The source code for the task. |
| supports_noop | Whether the task supports noop mode |
| input_method | Maps to the `input_method` key in the task json |
Puppet Plans
------------
Each entry in the `puppet_plans` list is an object with the following attributes:
| Attribute Key | Description |
| ------------- | ----------------------------------------------------------------------------- |
| name | The name of the plan. |
| file | The file defining the plan. |
| line | The line where the plan is defined. |
| docstring | The *DocString* object for the plan (see below). |
| defaults | The map of parameter names to default values. |
| source | The source code for the plan. |
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
Signature Objects
-----------------
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. |
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
DocString Objects
-----------------
For the above types, their docstrings are represented as an object with the following attributes:
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
| Attribute Key | Description |
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
| ------------- | --------------------------------------------------- |
| 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. |
Example JSON Document
---------------------
An example JSON document describing a Puppet class, defined type, resource type, provider, and Puppet functions:
```json
{
"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"
],
(PDOC-95) Properly group and display multiple provider `defaultfor`s Prior to this commit, strings did not properly handle providers which had multiple related `defaultfor`s. In code, these are written as comma-separated constraints. This commit updates strings' puppet provider handler, as well as the template which generates HTML for `defaultfor` statements. Note that it was necessary to make a breaking change to the JSON schema to accomodate multiple AND'ed defaults. Previously, provider defaults were contained in a single key-value map. Now, they are contained in an array of key-value lists, which allows multiple constraints to be associated with each other.
2016-10-11 19:45:17 +00:00
"defaults": [
[
[
"kernel",
"Linux"
]
],
[
[
"osfamily",
"RedHat",
],
[
"operatingsystemmajrelease",
"7"
]
]
],
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
"commands": {
"foo": "/usr/bin/foo"
}
}
],
"puppet_functions": [
{
"name": "func",
"file": "site.pp",
"line": 20,
"type": "puppet",
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
"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"
]
}
]
}
}
],
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
"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",
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
"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"
]
}
]
}
}
],
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
"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",
(PDOC-125) Update JSON schema to reflect addition of `signatures`
2016-11-14 19:26:35 +00:00
"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"
]
}
]
}
}
],
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
"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"
}
(maint) update various documentation This updates various docs in the project. * Get rid of MAINTAINERS * Update JSON.md with tasks and plans * Fix some weirndess in the README * Polish CONTRIBUTING.md
2018-04-25 08:06:42 +00:00
],
"puppet_tasks": [
{
"name": "(stdin)",
"file": "(stdin)",
"line": 0,
"docstring": {
"text": "Allows you to backup your database to local file.",
"tags": [
{
"name": "database",
"tag_name": "param",
"text": "Database to connect to",
"types": [
"Optional[String[1]]"
]
},
{
"name": "user",
"tag_name": "param",
"text": "The user",
"types": [
"Optional[String[1]]"
]
},
{
"name": "password",
"tag_name": "param",
"text": "The password",
"types": [
"Optional[String[1]]"
]
},
{
"name": "sql",
"tag_name": "param",
"text": "Path to file you want backup to",
"types": [
"String[1]"
]
}
]
},
"source": "{\n \"description\": \"Allows you to backup your database to local file.\",\n \"input_method\": \"stdin\",\n \"parameters\": {\n \"database\": {\n \"description\": \"Database to connect to\",\n \"type\": \"Optional[String[1]]\"\n },\n \"user\": {\n \"description\": \"The user\",\n \"type\": \"Optional[String[1]]\"\n },\n \"password\": {\n \"description\": \"The password\",\n \"type\": \"Optional[String[1]]\"\n },\n \"sql\": {\n \"description\": \"Path to file you want backup to\",\n \"type\": \"String[1]\"\n }\n }\n}\n",
"supports_noop": false,
"input_method": "stdin"
}
],
"puppet_plans": [
{
"name": "plann",
"file": "(stdin)",
"line": 5,
"docstring": {
"text": "A simple plan.",
"tags": [
{
"tag_name": "param",
"text": "First param.",
"types": [
"String"
],
"name": "param1"
},
{
"tag_name": "param",
"text": "Second param.",
"types": [
"Any"
],
"name": "param2"
},
{
"tag_name": "param",
"text": "Third param.",
"types": [
"Integer"
],
"name": "param3"
}
]
},
"defaults": {
"param3": "1"
},
"source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}"
}
(PDOC-63) Update README and JSON files. This commit updates the README and JSON documentation files to make them consistent with the refactoring work.
2016-09-15 22:45:44 +00:00
]
}
```