From 1e24cb6653acc36998d4c688ac51cdb72d70d25f Mon Sep 17 00:00:00 2001 From: Konstantin Kuminsky Date: Fri, 20 Dec 2024 19:50:31 -0500 Subject: [PATCH 1/6] More detailed info on block scalars --- .../rst/reference_appendices/YAMLSyntax.rst | 118 ++++++++++++------ 1 file changed, 83 insertions(+), 35 deletions(-) diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index b445dfe3da1..cee94a23004 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -18,15 +18,13 @@ is used in practice. YAML Basics ----------- -For Ansible, nearly every YAML file starts with a list. -Each item in the list is a list of key/value pairs, commonly -called a "hash" or a "dictionary". So, we need to know how -to write lists and dictionaries in YAML. +All YAML files (regardless of their association with Ansible) can optionally begin with ``---`` and end with ``...``. +This is part of the YAML format and indicates the start and end of a document. -There's another small quirk to YAML. All YAML files (regardless of their association with Ansible or not) can optionally -begin with ``---`` and end with ``...``. This is part of the YAML format and indicates the start and end of a document. +One of the most common structures that can be found in a yaml file is a list. +Each item of a list tarts with a ``"- "`` (a dash and a space) and must be at the same indentation level: -All members of a list are lines beginning at the same indentation level starting with a ``"- "`` (a dash and a space): +.. note:: Indentation is the amount of white spaces from the start of a line. Correct indentation is important for yaml documents to be readable by Ansible. .. code:: yaml @@ -38,7 +36,7 @@ All members of a list are lines beginning at the same indentation level starting - Mango ... -A dictionary is represented in a simple ``key: value`` form (the colon must be followed by a space): +Another common structure is a dictionary which consists of one or more key/value pairs: ``key: value`` (the colon must be followed by a space): .. code:: yaml @@ -48,7 +46,7 @@ A dictionary is represented in a simple ``key: value`` form (the colon must be f job: Developer skill: Elite -More complicated data structures are possible, such as lists of dictionaries, dictionaries whose values are lists or a mix of both: +Dictionaries and lists can be combined into more complex data structures. As an example, below is a lists of dictionaries: .. code:: yaml @@ -68,7 +66,7 @@ More complicated data structures are possible, such as lists of dictionaries, di - fortran - erlang -Dictionaries and lists can also be represented in an abbreviated form if you really want to: +Dictionaries and lists can also be written in a short form called "Flow collections": .. code:: yaml @@ -76,11 +74,10 @@ Dictionaries and lists can also be represented in an abbreviated form if you rea martin: {name: Martin D'vloper, job: Developer, skill: Elite} fruits: ['Apple', 'Orange', 'Strawberry', 'Mango'] -These are called "Flow collections". .. _truthiness: -Ansible doesn't really use these too much, but you can also specify a :ref:`boolean value ` (true/false) in several forms: +If a value corresponding to a key is a :ref:`boolean value ` (true/false) it can be written in several forms: .. code:: yaml @@ -90,12 +87,31 @@ Ansible doesn't really use these too much, but you can also specify a :ref:`bool likes_emacs: TRUE uses_cvs: false -Use lowercase 'true' or 'false' for boolean values in dictionaries if you want to be compatible with default yamllint options. +Use lowercase 'true' or 'false' to be compatible with default yamllint options. -Values can span multiple lines using ``|`` or ``>``. Spanning multiple lines using a "Literal Block Scalar" ``|`` will include the newlines and any trailing spaces. -Using a "Folded Block Scalar" ``>`` will fold newlines to spaces; it is used to make what would otherwise be a very long line easier to read and edit. -In either case the indentation will be ignored. -Examples are: +Values can be written as multiple lines using "Block Scalars". + +"Folded Block Scalar" ``>`` will replace carriage returns at the end of each line with spaces. Carriage returns can be added by leaving an empty line. +For example the following: + +.. code:: yaml + + fold_newlines: > + this is really a + single line of text + despite appearances + + this is going to be a + second line of text + +will result in below (note additional new line at the end): + +.. code:: text + + this is really a single line of text despite appearances\n + this is going to be a second line of text\n + +"Literal Block Scalar" ``|`` will keep carriage returns and any trailing spaces (again, note additional new line at the end): .. code:: yaml @@ -104,32 +120,66 @@ Examples are: will appear these three lines of poetry - fold_newlines: > - this is really a - single line of text - despite appearances + and one more line -While in the above ``>`` example all newlines are folded into spaces, there are two ways to enforce a newline to be kept: +becomes + +.. code:: text + + exactly as you see\n + will appear these three\n + lines of poetry\n + \n + and one more line\n + +To avoid a new line at the end add ``-`` after block scalar. For example: .. code:: yaml - fold_some_newlines: > - a - b + include_newlines: |- + exactly as you see + will appear these three + lines of poetry + + and one more line + +becomes + +.. code:: text - c - d - e - f + exactly as you see\n + will appear these three\n + lines of poetry\n + \n + and one more line -Alternatively, it can be enforced by including newline ``\n`` characters: +Note that in all examples above the indentation and the amount of new lines at the end were ignored. +To keep all additional new lines at the end use ``+`` after block scalar. For example: .. code:: yaml - fold_same_newlines: "a b\nc d\n e\nf\n" + include_newlines: |+ + exactly as you see + will appear these three + lines of poetry + \n + and one more line + \n + \n -Let's combine what we learned so far in an arbitrary YAML example. -This really has nothing to do with Ansible, but will give you a feel for the format: +becomes + +.. code:: text + + exactly as you see\n + will appear these three\n + lines of poetry\n + \n + and one more line\n + \n + \n + +An example below combines what we learned so far and gives a feel of the format: .. code:: yaml @@ -153,8 +203,6 @@ This really has nothing to do with Ansible, but will give you a feel for the for 3 A-Levels BSc in the Internet of Things -That's all you really need to know about YAML to start writing `Ansible` playbooks. - Gotchas ------- From 06c86a0c720524046173f2bcf54101172d5559de Mon Sep 17 00:00:00 2001 From: Konstantin <89620064+kk-at-redhat@users.noreply.github.com> Date: Thu, 17 Apr 2025 15:55:22 -0400 Subject: [PATCH 2/6] Update docs/docsite/rst/reference_appendices/YAMLSyntax.rst Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> --- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index cee94a23004..d7e433f2968 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -22,7 +22,7 @@ All YAML files (regardless of their association with Ansible) can optionally beg This is part of the YAML format and indicates the start and end of a document. One of the most common structures that can be found in a yaml file is a list. -Each item of a list tarts with a ``"- "`` (a dash and a space) and must be at the same indentation level: +Each item of a list starts with a ``"- "`` (a dash and a space) and must be at the same indentation level: .. note:: Indentation is the amount of white spaces from the start of a line. Correct indentation is important for yaml documents to be readable by Ansible. From 20ac95d46e8377d22d26e44bc9c159653c62dc72 Mon Sep 17 00:00:00 2001 From: Konstantin <89620064+kk-at-redhat@users.noreply.github.com> Date: Thu, 17 Apr 2025 15:56:21 -0400 Subject: [PATCH 3/6] Update docs/docsite/rst/reference_appendices/YAMLSyntax.rst Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> --- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index d7e433f2968..dfd41e9c59e 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -24,7 +24,7 @@ This is part of the YAML format and indicates the start and end of a document. One of the most common structures that can be found in a yaml file is a list. Each item of a list starts with a ``"- "`` (a dash and a space) and must be at the same indentation level: -.. note:: Indentation is the amount of white spaces from the start of a line. Correct indentation is important for yaml documents to be readable by Ansible. +.. note:: Indentation is the amount of whitespace from the start of a line. Correct indentation is important for YAML documents to be valid. .. code:: yaml From fda4e69d210a6678bfbcc3d7ca5532118d53faa6 Mon Sep 17 00:00:00 2001 From: Konstantin <89620064+kk-at-redhat@users.noreply.github.com> Date: Thu, 17 Apr 2025 15:56:31 -0400 Subject: [PATCH 4/6] Update docs/docsite/rst/reference_appendices/YAMLSyntax.rst Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> --- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index dfd41e9c59e..3c795054c72 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -111,7 +111,7 @@ will result in below (note additional new line at the end): this is really a single line of text despite appearances\n this is going to be a second line of text\n -"Literal Block Scalar" ``|`` will keep carriage returns and any trailing spaces (again, note additional new line at the end): +"Literal Block Scalar" ``|`` will keep carriage returns and any trailing spaces (again, followed by one newline): .. code:: yaml From d2a303b150d01f587ec1d67a5a798ba16ecbcae8 Mon Sep 17 00:00:00 2001 From: Konstantin <89620064+kk-at-redhat@users.noreply.github.com> Date: Thu, 17 Apr 2025 15:59:13 -0400 Subject: [PATCH 5/6] Update docs/docsite/rst/reference_appendices/YAMLSyntax.rst Co-authored-by: Sloane Hertel <19572925+s-hertel@users.noreply.github.com> --- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index 3c795054c72..4687073bb02 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -104,7 +104,7 @@ For example the following: this is going to be a second line of text -will result in below (note additional new line at the end): +will result in two lines of text followed by one newline: .. code:: text From db1b8febb98152965804056fc8e4548549086b6b Mon Sep 17 00:00:00 2001 From: Konstantin <89620064+kk-at-redhat@users.noreply.github.com> Date: Thu, 17 Apr 2025 18:27:05 -0400 Subject: [PATCH 6/6] Term string values is more appropriate than lines --- docs/docsite/rst/reference_appendices/YAMLSyntax.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst index 4687073bb02..55677944423 100644 --- a/docs/docsite/rst/reference_appendices/YAMLSyntax.rst +++ b/docs/docsite/rst/reference_appendices/YAMLSyntax.rst @@ -89,7 +89,7 @@ If a value corresponding to a key is a :ref:`boolean value Use lowercase 'true' or 'false' to be compatible with default yamllint options. -Values can be written as multiple lines using "Block Scalars". +Values can be written as multiple string values using "Block Scalars". "Folded Block Scalar" ``>`` will replace carriage returns at the end of each line with spaces. Carriage returns can be added by leaving an empty line. For example the following: