Add more examples

README.md

@@ -6,6 +6,8 @@ This is a small package to load and parse files (or just text) with YAML front m
 
 [![Build Status](https://travis-ci.org/eyeseast/python-frontmatter.svg?branch=master)](https://travis-ci.org/eyeseast/python-frontmatter)
 
+**[Documentation](https://python-frontmatter.readthedocs.io/en/latest/)**
+
 ## Install:
 
     pip install python-frontmatter
@@ -112,4 +114,4 @@ Well, hello there, world.
 
 ```
 
-For more examples, see files in the `tests/` directory. Each sample file has a corresponding `.result.json` file showing the expected parsed output.
+For more examples, see files in the `tests/` directory. Each sample file has a corresponding `.result.json` file showing the expected parsed output. See also the `examples/` directory, which covers more ways to customize input and output.

examples/content/pandoc.txt

@@ -0,0 +1,11 @@
+---
+lipsum: https://www.lipsum.com/
+ref: https://github.com/eyeseast/python-frontmatter/issues/42
+title: Pandoc-flavored Front Matter
+...
+
+Nulla pulvinar, turpis ullamcorper tempus posuere, sapien purus porttitor diam, id ullamcorper lorem neque id mauris. Sed facilisis, elit eget luctus posuere, quam nibh imperdiet magna, vel placerat arcu risus sit amet arcu. Morbi sit amet mollis leo. Mauris sit amet condimentum mi. Quisque lectus libero, varius scelerisque tempor ut, elementum ac diam. Morbi nisl sapien, ullamcorper ac elementum at, auctor quis magna. Curabitur nec neque purus.
+
+Proin tincidunt cursus turpis, mattis euismod sapien. Cras consectetur id felis non volutpat. Proin vulputate ante gravida quam euismod blandit. Nulla at varius nibh. Donec congue erat vel mattis volutpat. Sed fringilla lorem sit amet velit ornare gravida. Sed ac scelerisque nisi.
+
+Generated 2 paragraphs, 109 words, 730 bytes of Lorem Ipsum

examples/content/sorted.txt

@@ -0,0 +1,12 @@
+---
+title: Pandoc-flavored Front Matter
+ref: https://github.com/eyeseast/python-frontmatter/issues/26
+lipsum: https://www.lipsum.com/
+alpha: false
+---
+
+Nulla pulvinar, turpis ullamcorper tempus posuere, sapien purus porttitor diam, id ullamcorper lorem neque id mauris. Sed facilisis, elit eget luctus posuere, quam nibh imperdiet magna, vel placerat arcu risus sit amet arcu. Morbi sit amet mollis leo. Mauris sit amet condimentum mi. Quisque lectus libero, varius scelerisque tempor ut, elementum ac diam. Morbi nisl sapien, ullamcorper ac elementum at, auctor quis magna. Curabitur nec neque purus.
+
+Proin tincidunt cursus turpis, mattis euismod sapien. Cras consectetur id felis non volutpat. Proin vulputate ante gravida quam euismod blandit. Nulla at varius nibh. Donec congue erat vel mattis volutpat. Sed fringilla lorem sit amet velit ornare gravida. Sed ac scelerisque nisi.
+
+Generated 2 paragraphs, 109 words, 730 bytes of Lorem Ipsum

examples/pandoc.py

@@ -0,0 +1,35 @@
+import frontmatter
+
+
+class PandocHandler(frontmatter.YAMLHandler):
+    """
+    Pandoc format uses different start and end delimiters, which trips up parsing a bit.
+    To make it work, we need a custom handler that deals with each part separately.
+
+    >>> with open('examples/content/pandoc.txt') as f:
+    ...     text = f.read()
+    >>> post = frontmatter.loads(text, handler=PandocHandler())
+    >>> post['title']
+    'Pandoc-flavored Front Matter'
+    >>> print(frontmatter.dumps(post))
+    ---
+    lipsum: https://www.lipsum.com/
+    ref: https://github.com/eyeseast/python-frontmatter/issues/42
+    title: Pandoc-flavored Front Matter
+    ...
+    <BLANKLINE>
+    Nulla pulvinar, turpis ullamcorper tempus posuere, sapien purus porttitor diam, id ullamcorper lorem neque id mauris. Sed facilisis, elit eget luctus posuere, quam nibh imperdiet magna, vel placerat arcu risus sit amet arcu. Morbi sit amet mollis leo. Mauris sit amet condimentum mi. Quisque lectus libero, varius scelerisque tempor ut, elementum ac diam. Morbi nisl sapien, ullamcorper ac elementum at, auctor quis magna. Curabitur nec neque purus.
+    <BLANKLINE>
+    Proin tincidunt cursus turpis, mattis euismod sapien. Cras consectetur id felis non volutpat. Proin vulputate ante gravida quam euismod blandit. Nulla at varius nibh. Donec congue erat vel mattis volutpat. Sed fringilla lorem sit amet velit ornare gravida. Sed ac scelerisque nisi.
+    <BLANKLINE>
+    Generated 2 paragraphs, 109 words, 730 bytes of Lorem Ipsum
+    """
+
+    START_DELIMITER = "---"
+    END_DELIMITER = "..."
+
+    def split(self, text):
+        "It's going to take a few passes to split here"
+        _, start, text = text.partition(self.START_DELIMITER)
+        fm, end, content = text.partition(self.END_DELIMITER)
+        return fm, content

examples/sorted.py

@@ -0,0 +1,21 @@
+"""
+This is an example of setting ``sort_keys=False`` in ``frontmatter.dumps`` 
+to preserve the original sort order.
+"""
+import frontmatter
+from pathlib import Path
+
+
+def test_load_sorted():
+    examples = Path(__file__).parent
+    text = (examples / "content" / "sorted.txt").read_text()
+    post = frontmatter.loads(text)
+
+    assert frontmatter.dumps(post, sort_keys=False) == text.strip()
+
+
+if __name__ == "__main__":
+    import sys
+    import pytest
+
+    pytest.main([__file__] + sys.argv[1:])