Metadata-Version: 2.1
Name: nestedtext
Version: 0.6.0
Summary: human readable and writable data interchange format
Home-page: https://nestedtext.org
Author: Ken Kundert and Kale Kundert
Author-email: admin@nestedtext.org
License: GPLv3+
Download-URL: https://github.com/kenkundert/nestedtext/tarball/master
Keywords: data
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Text Processing :: Markup
Classifier: Topic :: Utilities
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
Requires-Dist: inform (>=1.23)

NestedText: A Human Friendly Data Format
========================================

.. image:: https://img.shields.io/travis/KenKundert/nestedtext/master.svg
    :target: https://travis-ci.org/KenKundert/nestedtext

.. image:: https://img.shields.io/coveralls/KenKundert/nestedtext.svg
    :target: https://coveralls.io/r/KenKundert/nestedtext

.. 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: 0.6.0
| Released: 2020-09-26
| Please post all questions, suggestions, and bug reports to
  `NestedText Github <https://github.com/KenKundert/nestedtext/issues>`_.
|


*NestedText* is a file format for holding data that is to be entered, edited, or 
viewed by people.  It allows data to be organized into a nested collection of 
dictionaries, lists, and strings.  In this way it is similar to *JSON* and 
*YAML*, but without the complexity and risk of *YAML* and without the syntatic 
clutter of *JSON*.  *NestedText* is both simple and natural. Only a small number 
of concepts and rules must be kept in mind when creating it.
It is easily created, modified, or viewed with a text editor and 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::

    # Contact information for our officers

    president:
        name: Katheryn McDaniel
        address:
            > 138 Almond Street
            > Topika, 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: KateMcD@aol.com
        kids:
            - Joanie
            - Terrance

    vice president:
        name: Margaret Hodge
        address:
            > 2586 Marigold Lane
            > Topika, Kansas 20682
        phone: 1-470-555-0398
        email: margaret.hodge@uk.edu
        kids:
            - Arnie
            - Zach
            - Maggie

    treasurer:
        name: Fumiko Purvis
        address:
            > 3636 Buffalo Ave
            > Topika, Kansas 20692
        phone: 1-268-555-0280
        email: fumiko.purvis@hotmail.com
        kids:
            - Lue

The format holds dictionaries (ordered collections of name/value pairs), lists 
(ordered collections of values) and strings (text) organized hierarchically to 
any depth.  Indentation is used to indicate the hierarchy of the data, and 
a simple natural syntax is used to distinguish the types of data in such 
a manner that it is not easily confused.  Specifically, lines that begin with 
a word or words followed by a colon are dictionary items; a dash introduces list 
items, and a leading greater-than symbol signifies a line in a multiline string.
Dictionaries and lists are used for nesting, the leaf values are always strings.


Alternatives
------------

There are no shortage of well established alternatives to *NestedText* for 
storing data in a human-readable text file. Probably the most obvious are `json 
<https://docs.python.org/3/library/json.html>`_ and `YAML 
<https://pyyaml.org/wiki/PyYAMLDocumentation>`_.  Both have serious short 
comings.

*JSON* is a subset of JavaScript suitable for holding data. Like *NestedText*, 
it consists of a hierarchical collection of dictionaries, lists, and strings, 
but also allows integers, floats, Booleans and nulls.  The problem with *JSON* 
for this application is that it is awkward.  With all those data types it must 
syntactically distinguish between them.  For example, in *JSON* 32 is an 
integer, 32.0 is the real version of 32, and "32" is the string version. These 
distinctions are not meaningful and can be confusing to non-programmers. In 
addition, in most datasets a majority of leaf values are strings and the 
required quotes adds substantial visual clutter.  *NestedText* avoids these 
issues by treating all leaf values as strings with no need for quoting or 
escaping.  It is up to the application that employs *NestedText* as an input 
format to sort things out later.

*JSON* does not provide for multiline strings and any special characters like 
newlines or unicode are encoded with escape codes, which can make strings quite 
difficult to interpret.  Finally, dictionary and list items must be separated 
with commas, but a comma must not follow last item.  All of this results in 
*JSON* being a frustrating format for humans to read, enter or edit.

*NestedText* has the following clear advantages over *JSON* as human readable 
and writable data file format:

- text does not require quotes
- data type does not change based on seemingly insignificant details (32, 32.0, "32")
- comments
- multiline strings
- special characters without escaping them
- Unicode characters without encoding them
- commas are not used to separate dictionary and list items

*YAML* was to be the human friendly alternative to *JSON*, but the authors were 
too ambitious and tried to support too many data types and too many formats. To 
distinguish between all the various types and formats, a complicated and 
non-intuitive set of rules developed.  For example, 2 is interpreted as an 
integer, 2.0 as a real number, and both 2.0.0 and "2" are strings.  *YAML* at 
first appears very appealing when used with simple examples, but things can 
quickly become complicated or provide unexpected results.  A reaction to this is 
the use of *YAML* subsets, such as `StrictYAML 
<https://hitchdev.com/strictyaml>`_.  However, the subsets still try to maintain 
compatibility with *YAML* and so inherit much of its complexity.

*YAML* recognized the problems that result from *JSON* needing to unambiguously 
distinguish between many data types and instead uses implicit typing, which 
creates its own `problems
<https://hitchdev.com/strictyaml/why/implicit-typing-removed>`_.
For example, consider the following *YAML* fragment::

    Enrolled: NO
    Country Code: NO

Presumably *Enrolled* is meant to be a Boolean value whereas *Country Code* is 
meant to be a string (*NO* is the country code for Norway). Reading this 
fragment with *YAML* results in {'Enrolled': *False*, 'Country Code': *False*}.  
When read by *NestedText* both values are retained in their original form as 
strings.  With *NestedText* any decisions about how to interpret the leaf values 
are passed to the end application, which is the only place where they can be 
made knowledgeably.  The assumption is that the end application knows that 
*Enrolled* should be a Boolean and knows how to convert 'NO' to *False*.  The 
same is not possible with *YAML* because the *Country Code* value has been 
transformed and because there are many possible strings that map to *False* 
(`n`, `no`, `false`, `off`; etc.).

This is one example of the many possible problems that stem from implicit 
typing.  In fact, many people make it a habit to add quotes to all values simply 
to avoid the ambiguities, which makes *YAML* more like *JSON*.

*NestedText* was inspired by *YAML*, but eschews its complexity. It has the 
following clear advantages over *YAML* as human readable and writable data file 
format:

- simple
- unambiguous (no implicit typing)
- data type does not change based on seemingly insignificant details (2, 2.0, 2.0.0, "2")
- syntax is insensitive to special characters within text
- safe, no risk of malicious code execution


Issues
------

Please ask questions or report problems on `Github 
<https://github.com/KenKundert/nestedtext/issues>`_.


Contributing
------------

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


