Commits

Zero Piraeus  committed 362d54e

Remove obsolete documentation.

  • Participants
  • Parent commits ae37368

Comments (0)

Files changed (2)

File doc/lib/escapedstring.txt

-
-==================
-csx._EscapedString
-==================
-
-`_EscapedString` strips comments and quoted strings (storing the latter for
-later reinsertion) from its `str` argument, so that they can be processed by
-`csx._TokenStream` and `csx._Renderable` without any text embedded in those
-comments and quoted strings being mistaken for elements of CSX structure. ::
-
-    >>> from csx import _EscapedString
-
-    >>> music = _EscapedString("""
-    ...
-    ...   /*  Year: 1956
-    ...    *  Length: 2'21"
-    ...    */
-    ...
-    ...   track {
-    ...     title: "Ain't Got No Home";
-    ...     artist: 'Clarence "Frogman" Henry';
-    ...   }
-    ...
-    ... """)
-
-Passing an `_EscapedString` instance to `str()` returns the string with
-comments and extraneous whitespace removed. ::
-
-    >>> print(music)
-    track { title: "Ain't Got No Home"; artist: 'Clarence "Frogman" Henry'; }
-
-In the underlying `str` object, comments are removed (although any embedded
-newlines are preserved to maintain correct line counts), `str.format`-style
-replacement fields are substituted for quoted strings, and braces are doubled
-to prevent them from interfering with `str.format()`. ::
-
-    >>> music[:]
-    '\n\n  \n\n\n\n  track {{\n    title: {0};\n    artist: {1};\n  }}\n\n'
-
-Substituted strings are stored in the attribute `subs`. ::
-
-    >>> music.subs
-    ['"Ain\'t Got No Home"', '\'Clarence "Frogman" Henry\'']
-
-Whitespace inside substituted strings is preserved ... ::
-
-    >>> spaced = _EscapedString("content: ' a   b '")
-
-    >>> print(spaced)
-    content: ' a   b '
-
-... but a quoted substring may *not* contain an embedded newline ... ::
-
-    >>> illegal = _EscapedString("""
-    ...
-    ...   :before {
-    ...     content: "phwoaar ...
-    ...     "
-    ...   }
-    ...
-    ... """)
-    Traceback (most recent call last):
-        ...
-    csx.Error: line 4: unfinished string
-
-... even if it's escaped with a backslash. ::
-
-    >>> still_illegal = _EscapedString(r"""
-    ...
-    ...   :after {
-    ...     content: " \
-    ...     ... crikey." 
-    ...   }
-    ...
-    ... """)
-    Traceback (most recent call last):
-        ...
-    csx.Error: line 4: unfinished string
-
-Comment markers inside strings are ignored, as are quotes and `/*` markers
-inside comments, single quotes inside double-quoted strings, and vice versa.
-Backslash-escaped single or double quotes are ignored everywhere. ::
-
-    >>> insane_but_legal = _EscapedString(r"""
-    ...
-    ...   /* any combination of /*, ', ", "this", 'that', "t'other", etc. */
-    ...
-    ...   :before { content: "/* or \" or '" }
-    ...   :after { content: '*/ or \' or "' }
-    ...
-    ... """)
-
-    >>> insane_but_legal[:]
-    '\n\n  \n\n  :before {{ content: {0} }}\n  :after {{ content: {1} }}\n\n'
-
-    >>> for sub in insane_but_legal.subs:
-    ...     print(sub)
-    "/* or \" or '"
-    '*/ or \' or "'
-
-As previously seen, comments may span multiple lines, but they must eventually
-be terminated. ::
-
-    >>> _EscapedString("/* forgot something ...")
-    Traceback (most recent call last):
-        ...
-    csx.Error: line 1: unfinished comment
-
-`@`, `<!--` and `-->` are illegal outside strings and comments ... ::
-
-    >>> _EscapedString("<!--")
-    Traceback (most recent call last):
-        ...
-    csx.Error: line 1: illegal text '<!--'
-
-    >>> _EscapedString("-->")
-    Traceback (most recent call last):
-        ...
-    csx.Error: line 1: illegal text '-->'
-
-    >>> _EscapedString("@")
-    Traceback (most recent call last):
-        ...
-    csx.Error: line 1: illegal text '@'
-
-... but fine inside them. ::
-
-    >>> print(_EscapedString("go: '<!-- hog wild *' /* and --> @here */"))
-    go: '<!-- hog wild *'
-

File doc/lib/tokenstream.txt

-
-================
-csx._TokenStream
-================
-
-`_TokenStream` iterates over tokens representing CSX structure found within its
-`str` argument. The attribute `pos` stores the current line number. ::
-
-    >>> from csx import _TokenStream
-
-    >>> stream = _TokenStream("""
-    ...
-    ...     /* lists */
-    ...
-    ...     ol, ul {
-    ...         background: orange;
-    ...         li { color: maroon; }
-    ...     }
-    ...
-    ...     dd {
-    ...         background: yellow;
-    ...         dt { color: red }
-    ...         dd { color: blue }
-    ...     }
-    ...
-    ... """)
-
-    >>> for token in stream:
-    ...     print("line {0:2d}: {1!r}".format(stream.pos, token))
-    line  5: 'ol, ul {'
-    line  6: 'background: orange'
-    line  7: 'li {'
-    line  7: 'color: maroon'
-    line  7: '}'
-    line  8: '}'
-    line 10: 'dd {'
-    line 11: 'background: yellow'
-    line 12: 'dt {'
-    line 12: 'color: red'
-    line 12: '}'
-    line 13: 'dd {'
-    line 13: 'color: blue'
-    line 13: '}'
-    line 14: '}'
-
-
-Methods
-=======
-
-revert()
---------
-
-`revert()` steps back through previous tokens. ::
-
-    >>> stream.revert()
-    >>> next(stream)
-    '}'
-
-    >>> stream.revert(3)
-    >>> next(stream)
-    'color: blue'
-
-If a stream is reverted more times than there are previous tokens, the stream
-is reset to the beginning. ::
-
-    >>> stream.revert(999)
-
-    >>> next(stream)
-    'ol, ul {'
-
-Once the end of the stream has been reached, it can still be reverted. [1]_ :: 
-
-    >>> while True:
-    ...     next(stream)
-    Traceback (most recent call last):
-        ...
-    StopIteration
-
-    >>> stream.revert(6)
-    >>> for token in stream:
-    ...     print("line {0:2d}: {1!r}".format(stream.pos, token))
-    line 12: 'color: red'
-    line 12: '}'
-    line 13: 'dd {'
-    line 13: 'color: blue'
-    line 13: '}'
-    line 14: '}'
-
-
-.. [1]  This is a violation of the `iterator protocol`_, which suggests to the
-        author that the iterator protocol is broken.
-
-.. _iterator protocol: http://www.python.org/dev/peps/pep-0234
-