Skip to content

Commit

Permalink
Mark nestedtext code as nestedtext in documentation.
Browse files Browse the repository at this point in the history
  • Loading branch information
Ken Kundert authored and Ken Kundert committed Oct 19, 2020
1 parent eb926f8 commit ef31142
Show file tree
Hide file tree
Showing 4 changed files with 44 additions and 17 deletions.
4 changes: 3 additions & 1 deletion README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,9 @@ easily understood and used by both programmers and non-programmers.

*NestedText* is convenient for configuration files, address books, account
information and the like. Here is an example of a file that contains a few
addresses::
addresses:

.. code-block:: nestedtext
# Contact information for our officers
Expand Down
32 changes: 21 additions & 11 deletions doc/basic_syntax.rst
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,12 @@ format>`.
Dictionaries
============

A dictionary is an ordered collection of name/value pairs::
A dictionary is an ordered collection of name/value pairs:

.. code-block:: nestedtext
name 1: value 1
name 2: value 2
...
A dictionary item is introduced by a key followed by a colon at the start of
a line. The key is a string and must be quoted if it contains characters that
Expand All @@ -40,11 +41,12 @@ A dictionary is all adjacent dictionary items at the same indentation level.
Lists
=====

A list is an ordered collection of values::
A list is an ordered collection of values:

.. code-block:: nestedtext
- value 1
- value 2
...
A list item is introduced with a dash at the start of a line. The value of
a list item may be a rest-of-line string, a multiline string, a list, or
Expand All @@ -64,22 +66,28 @@ Strings
There are two types of strings: rest-of-line strings and multiline strings.
Rest-of-line strings are simply all the remaining characters on the line,
including any leading or trailing white space. They can contain any character
other than newline::
other than newline:

.. code-block:: nestedtext
code : input signed [7:0] level
regex : [+-]?([0-9]*[.])?[0-9]+\s*\w*
math : -b + sqrt(b**2 - 4*a*c)
unicode: José and François
Multi-line strings are specified on lines prefixed with the greater-than
symbol. The content of each line starts after the first space that follows
the greater-than symbol::
symbol. The content of each line starts after the first space that follows the
greater-than symbol:

.. code-block:: nestedtext
> This is the first line of a multiline string, it is indented.
> This is the second line, it is not indented.
You can include empty lines in the string simply by specifying the
greater-than symbol alone on a line::
You can include empty lines in the string simply by specifying the greater-than
symbol alone on a line:

.. code-block:: nestedtext
>
> “The worth of a man to his society can be measured by the contribution he
Expand All @@ -103,7 +111,7 @@ Lines that begin with a hash as the first non-space character, or lines that are
empty or consist only of spaces and tabs are comment lines and are ignored.
Indentation is not significant on comment lines.

::
.. code-block:: nestedtext
# this line is ignored
Expand All @@ -117,7 +125,9 @@ A value for a dictionary or list item may be a rest-of-line string or it may be
a nested dictionary, list or a multiline string. Indentation is used to
indicate nesting. Indentation increases to indicate the beginning of a new
nested object, and indentation returns to a prior level to indicate its end. In
this way, data can be nested to an arbitrary depth::
this way, data can be nested to an arbitrary depth:

.. code-block:: nestedtext
# Contact information for our officers
Expand Down
21 changes: 17 additions & 4 deletions doc/examples.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ This example shows how to use pydantic_ to validate and parse a *NestedText*
file. The file in this case specifies deployment settings for a web server:

.. literalinclude:: ../examples/deploy.nt
:language: nestedtext

Below is the code to parse this file. Note that basic types like integers,
strings, Booleans, and lists are specified using standard type annotations.
Expand All @@ -22,8 +23,11 @@ built-in support for validating email addresses, which we can take advantage of
here:

.. literalinclude:: ../examples/deploy_pydantic.py
:language: python

This produces the following data structure:

This produces the following data structure::
.. code-block:: python
{'allowed_hosts': ['www.example.com'],
'database': {'engine': 'django.db.backends.mysql',
Expand All @@ -44,15 +48,19 @@ file. The input file is the same as in the previous example, i.e. deployment
settings for a web server:

.. literalinclude:: ../examples/deploy.nt
:language: nestedtext

Below is the code to parse this file. Note how the structure of the data is
specified using basic Python objects. The :func:`Coerce()` function is
necessary to have voluptuous convert string input to the given type; otherwise
it would simply check that the input matches the given type:

.. literalinclude:: ../examples/deploy_voluptuous.py
:language: python

This produces the following data structure::
This produces the following data structure:

.. code-block:: python
{'allowed_hosts': ['www.example.com'],
'database': {'engine': 'django.db.backends.mysql',
Expand Down Expand Up @@ -100,7 +108,9 @@ Cryptocurrency holdings

This example implements a command-line utility that displays the current value
of cryptocurrency holdings. The program starts by reading a settings file held
in ``~/.config/cc`` that in this case holds::
in ``~/.config/cc`` that in this case holds:

.. code-block:: nestedtext
holdings:
- 5 BTC
Expand Down Expand Up @@ -147,6 +157,7 @@ part of the package is shown here. Here is a configuration file that Odin might
use to generate packets for his wife and kids:

.. literalinclude:: ../examples/postmortem.nt
:language: nestedtext

Notice that *estate docs* is defined at the top level. It is not a *PostMortem*
setting; it simply defines a value that will be interpolated into a setting
Expand Down Expand Up @@ -175,7 +186,9 @@ if needed. In this example, simple functions are passed in that perform
validation and coercion as needed. This is a more flexible approach and allows
better control of the error messages.

Here are the processed settings::
Here are the processed settings:

.. code-block:: python
{'my gpg ids': ['odin@norse-gods.com'],
'name template': '{name}-{now:YYMMDD}',
Expand Down
4 changes: 3 additions & 1 deletion doc/file_format.rst
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,9 @@ The *NestedText* format follows a small number of simple rules. Here they are.
or greater-than symbol (``>``) when followed immediately by a space or
newline. Once the first of one of these pairs has been found in the
unquoted portion of the line, any subsequent occurrences of any of the
line-type tags are treated as simple text. For example::
line-type tags are treated as simple text. For example:

.. code-block:: nestedtext
- And the winner is: {winner}
Expand Down

0 comments on commit ef31142

Please sign in to comment.