Need help with nestedtext?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

KenKundert
245 Stars 6 Forks MIT License 354 Commits 0 Opened issues

Description

Human Readable and Writable Data Interchange Format

Services available

!
?

Need anything else?

Contributors list

NestedText: A Human Friendly Data Format

.. image:: https://pepy.tech/badge/nestedtext/month :target: https://pepy.tech/project/nestedtext

.. image:: https://img.shields.io/readthedocs/nestedtext.svg :target: https://nestedtext.readthedocs.io/en/latest/?badge=latest

.. image:: https://github.com/KenKundert/nestedtext/actions/workflows/build.yaml/badge.svg :target: https://github.com/KenKundert/nestedtext/actions/workflows/build.yaml

.. image:: https://coveralls.io/repos/github/KenKundert/nestedtext/badge.svg?branch=master :target: https://coveralls.io/github/KenKundert/nestedtext?branch=master

.. image:: https://img.shields.io/pypi/v/nestedtext.svg :target: https://pypi.python.org/pypi/nestedtext

.. image:: https://img.shields.io/pypi/pyversions/nestedtext.svg :target: https://pypi.python.org/pypi/nestedtext

| Authors: Ken & Kale Kundert | Version: 3.1.0 | Released: 2021-07-23 | Documentation:

nestedtext.org 
. | Please post all questions, suggestions, and bug reports to:
Github 
. |

NestedText is a file format for holding structured data to be entered, edited, or viewed by people. It organizes into a nested collection of dictionaries, lists, and strings without the need for quoting or escaping. It is similar to JSON, YAML, and TOML but without the complexity and risk of YAML and the syntactic clutter of JSON and TOML. NestedText is both simple and natural.
Only a small number of concepts and rules must be kept in mind when creating it.
It is created, modified, and viewed with a text editor and easily understood and used by 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:

.. code-block:: nestedtext

# Contact information for our officers

president: name: Katheryn McDaniel address: > 138 Almond Street > Topeka, Kansas 20697 phone: cell: 1-210-555-5297 home: 1-210-555-8470 # Katheryn prefers that we always call her on her cell phone. email: [email protected] additional roles: - board member

vice president: name: Margaret Hodge address: > 2586 Marigold Lane > Topeka, Kansas 20682 phone: 1-470-555-0398 email: [email protected] additional roles: - new membership task force - accounting task force

treasurer: - name: Fumiko Purvis address: > 3636 Buffalo Ave > Topeka, Kansas 20692 phone: 1-268-555-0280 email: [email protected] additional roles: - accounting task force - name: Merrill Eldridge # Fumiko's term is ending at the end of the year. # She will be replaced by Merrill. phone: 1-268-555-3602 email: [email protected]

The format holds dictionaries (ordered collections of name/value pairs), lists (ordered collections of values), and strings (text) organized hierarchically to any depth. Indentation indicates the hierarchy of the data, and a simple natural syntax distinguishes the types of data in such a manner that needs no quoting or escaping. Specifically,

  • lines that begin with a word (or words) followed by a colon are dictionary items,
  • lines that begin with a dash are list items,
  • lines that begin with a greater-than sign are part of a multiline string, and
  • lines that begin with a hash are comments and are ignored.

Dictionaries and lists can be nested arbitrarily.

NestedText is somewhat unique in that the leaf values are always strings. Of course, the values start as strings in the input file, but alternatives like YAML or TOML aggressively convert those values into the underlying data types such as integers, floats, and Booleans. For example, a value like 2.10 would be converted to a floating-point number. But the decision to do so is based purely on the form of the value, not the context in which it is found, which can lead to misinterpretations. For example, assume that this value is the software version number two point ten. By converting it to a floating-point number it becomes two point one, which is wrong. There are many possible versions of this basic issue. But there is also the inverse problem; values that should be converted to particular data types but are not recognized. For example, a value of $2.00 should be converted to a real number but would remain a string instead. There are simply too many values types for a general-purpose solution that is only looking at the values themselves to be able to interpret all of them. For example, 12/10/09 is likely a date, but is it in MM/DD/YY, YY/MM/DD or DD/MM/YY form? The fact is, the value alone is often insufficient to reliably determine how to convert values into internal data types.
NestedText avoids these problems by leaving the values in their original form and allowing the decision to be made by the end application where more context is available to help guide the conversions. If a price is expected for a value, then $2.00 would be checked and converted accordingly. Similarly, local conventions along with the fact that a date is expected for a particular value allow 12/10/09 to be correctly validated and converted. This process of validation and conversion is referred to as applying a schema to the data.
There are packages such as

Pydantic 
_ and
Voluptuous 
_ available that make this process easy and reliable.

Related Projects

Reference Material ~~~~~~~~~~~~~~~~~~

nestedtext docs 
_ """"""""""""""""""""""""""""""""""""""""""" NestedText documentation and language specification.

nestedtext source 
_ """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Source code repository for language documentation and Python implementation.
Report any issues here.

nestedtext_tests 
_ """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Official NestedText test suite. Also included as submodule in
nestedtext 
_.

Implementations ~~~~~~~~~~~~~~~

nestex 
_ """""""""""""""""""""""""""""""""""""""""""""""""
Go 
_ implementation of NestedText (supports :ref:
NestedText v3.0 
).

janet-nested-text 
_ """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Janet 
_ implementation of NestedText (supports :ref:
NestedText v3.0 
).

zig-nestedtext 
_ """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Zig 
_ implementation of NestedText (slight subset of :ref:
NestedText v3.0 
).

Utilities ~~~~~~~~~

parametrize from file 
_ """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Separate your test cases, held in NestedText, from your
PyTest 
_ test code.

vim-nestedtext 
_ """""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Vim syntax files for NestedText (supports :ref:
NestedText v3.0 
).

visual studio 
_ """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" Syntax files for Visual Studio (supports :ref:
NestedText v1.0 
).

Contributing

This package contains a Python reference implementation of NestedText and a test suite. Implementation in many languages is required for NestedText to catch on widely. If you like the format, please consider contributing additional implementations.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.