Mirrors/Plex-Meta-Manager
2
0
Fork 0
mirror of https://github.com/meisnate12/Plex-Meta-Manager synced 2024-12-21 18:33:06 +00:00
Code Issues Projects Releases Packages Wiki Activity
Plex-Meta-Manager/docs/home/guides/yaml.md

257 lines
8.7 KiB
Markdown
Raw Normal View History

[183] finalize wiki for 1.18.0
2022-11-03 19:44:01 +00:00
# YAML Tutorial
All of Plex Meta Manager's Config, Metadata, Overlay, and Playlist Files are written in the YAML data structure.
This tutorial will help you understand the specific parts of the files.
## Example YAML File We're working with
```yaml
libraries:
Movies:
metadata_path:
- pmm: basic
- pmm: imdb
overlay_path:
- pmm: ribbon
template_variables:
use_metacritic: false
use_common: false
TV Shows:
metadata_path:
- pmm: basic
- pmm: imdb
overlay_path:
- pmm: ribbon
settings:
cache: true
cache_expiration: 60
asset_directory:
- config/movie assets
- config/tv assets
```
## Basic YAML Syntax
A YAML format primarily uses 3 node types:
1. Dictionaries/Mappings:
The content of a mapping node is an unordered set of key/value node pairs, with the restriction that each of the keys is unique. YAML places no further restrictions on the nodes.
2. Lists/Arrays:
The content of a list node is an ordered series of zero or more nodes. In particular, a sequence may contain the same node more than once. It could even contain itself.
3. Literals (Strings, numbers, boolean, etc.):
The content of a scalar node is an opaque datum that can be presented as a series of zero or more Unicode characters.
Let us try and identify where these appear in the sample YAML file we saw earlier.
```yaml
# Strats with a top level Dictionary with keys `libraries` and `settings`
libraries: # Value is a Dictionary with keys `Movies` and `TV Shows`
Movies: # Value is a Dictionary with keys `metadata_path` and `overlay_path`
metadata_path: # Value is a List with two Items
- pmm: basic # List Item is a Dictionary with one key pair whose value is a String Literal
- pmm: imdb # List Item is a Dictionary with one key pair whose value is a String Literal
overlay_path: # Value is a List with one Item
- pmm: ribbon # List Item is a Dictionary with keys `pmm` and `template_variables` with `pmm`'s value a String Literal
template_variables: # Value is a Dictionary with keys `use_metacritic` and `use_common`
use_metacritic: false # Value is a Boolean Literal
use_common: false # Value is a Boolean Literal
TV Shows: # Value is a Dictionary with keys `metadata_path` and `overlay_path`
metadata_path: # Value is a List with two Items
- pmm: basic # List Item is a Dictionary with one key pair whose value is a String Literal
- pmm: imdb # List Item is a Dictionary with one key pair whose value is a String Literal
overlay_path: # Value is a List with one Item
- pmm: ribbon # List Item is a Dictionary with one key pair whose value is a String Literal
settings: # Value is a Dictionary with keys `cache` and `cache_expiration`
cache: true # Value is a Boolean Literal
cache_expiration: 60 # Value is a Number Literal
asset_directory: # Value is a List with two Items
- config/movie assets # List Item is a String Literal
- config/tv assets # List Item is a String Literal
```
## Indentation
A YAML file relies on whitespace and indentation to indicate nesting. The number of spaces used for indentation doesn’t matter as long as they are consistent.
**It is critical to note that tab characters cannot be used for indentation in YAML files; only spaces can be used.**
```yaml
libraries: # Nesting Level 1
Movies: # Nesting Level 2
metadata_path: # Nesting Level 3
- pmm: basic # Nesting Level 4
- pmm: imdb # Nesting Level 4
overlay_path: # Nesting Level 3
- pmm: ribbon # Nesting Level 4
template_variables: # Nesting Level 5
use_metacritic: false # Nesting Level 6
use_common: false # Nesting Level 6
TV Shows: # Nesting Level 2
metadata_path: # Nesting Level 3
- pmm: basic # Nesting Level 4
- pmm: imdb # Nesting Level 4
overlay_path: # Nesting Level 3
- pmm: ribbon # Nesting Level 4
settings: # Nesting Level 1
cache: true # Nesting Level 2
cache_expiration: 60 # Nesting Level 2
```
## Dictionaries
Dictionaries are used to associate key/value pairs that are unordered. Dictionaries can be nested by increasing the indentation, or new dictionaries can be created at the same level by resolving the previous one.
```yaml
cache: true
cache_expiration: 60
```
The "keys" are `cache` and `cache_expiration` and the "values" are `true` and `60` respectively.
### In-Line Dictionaries
you can represent a dictionary on a single line by using `{` and `}`
```yaml
settings:
cache: true
cache_expiration: 60
```
is equivalent to
```yaml
settings: {cache: true, cache_expiration: 60}
```
## Lists
Lists in YAML are represented by using the hyphen (-) and space. They are ordered and can be embedded inside a map using indentation.
```yaml
asset_directory:
- config/movie assets
- config/tv assets
```
The first item in the list is `config/movie assets` and the second is `config/tv assets`.
### In-Line Lists
you can represent a dictionary on a single line by using `{` and `}`
```yaml
settings:
asset_directory:
- config/movie assets
- config/tv assets
```
is equivalent to
```yaml
settings:
asset_directory: [config/movie assets, config/tv assets]
```
## Literals
Literals can come in multiple types:
* String: any sequence of characters
* Number: any representation of a number
* Boolean: `true` or `false`
### String Literals
The string literals do not require to be quoted. It is only important to quote them when they contain a value that can be mistaken as a special character.
Here is an example where the string has to be quoted as `&` and `:` are special characters.
YAML Special Characters: `{`, `}`, `[`, `]`, `,`, `&`, `:`, `*`, `#`, `?`, `|`. `-`, `<`. `>`, `=`, `!`, `%`, `@`, `\`
There are many occurrences of these special characters where quotes are not needed but if the YAML fails to load it could easily be because one of these are unquoted.
```yaml
message1: YAML & JSON # breaks as a & is a special character
message2: "YAML & JSON" # Works as the string is quoted
message3: YAML: Let's Get Started # breaks as a : is a special character
message4: "YAML: Let's Get Started" # Works as the string is quoted
```
#### Multiline Strings
Strings can be interpreted as multiline using the pipe (`|`) character.
```yaml
message: |
this is
a real multiline
message
```
This would be read as `this is\na real multiline\nmessage`
## Comments
YAML file also supports comments, unlike JSON. A comment starts with #.
```yaml
# Strats with a top level Dictionary with keys `libraries` and `settings`
libraries: # Value is a Dictionary with keys `Movies` and `TV Shows`
```
Everything after `#` on a line is ignored.
## Anchors and Alias
With a lot of configuration, configuration files can become quite large.
In YAML files, anchors (`&`) and aliases (`*`) are used to avoid duplication. When writing large configurations in YAML, it is common for a specific configuration to be repeated. For example, the vars config is repeated for all three services in the following YAML snippet.
```yaml
libraries:
Movies:
metadata_path:
- pmm: basic
- pmm: imdb
overlay_path:
- pmm: ribbon
template_variables:
use_metacritic: false
use_common: false
TV Shows:
metadata_path:
- pmm: basic
- pmm: imdb
overlay_path:
- pmm: ribbon
```
As more and more things are repeated for large configuration files, this becomes tedious.
Anchors and aliases allow us to rewrite the same snippet without having to repeat any configuration.
Anchors (`&`) are used to define a chunk of configuration, and aliases (`*`) are used to refer to that chunk at a different part of the configuration.
```yaml
libraries:
Movies:
metadata_path: &metadata_path # Anchor called metadata_path
- pmm: basic
- pmm: imdb
overlay_path:
- pmm: ribbon
template_variables:
use_metacritic: false
use_common: false
TV Shows:
metadata_path: *metadata_path # Alias to call the above section
overlay_path:
- pmm: ribbon
```
Reference in a new issue Copy permalink