{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# `pidgy` metasyntax"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "    import pidgy, IPython, jinja2, doctest\n",
       "\n",
       "`pidgy` not only allows the [Markdown] and [Python] to cooperate in a document, \n",
       "metasyntaxes emerge at the interface between the language."
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "    import pidgy, IPython, jinja2, doctest\n",
    "\n",
    "`pidgy` not only allows the [Markdown] and [Python] to cooperate in a document, \n",
    "metasyntaxes emerge at the interface between the language."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Markdown is the primary language"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Indented blocks are always code like in literate coffeescript.\n"
     ]
    },
    {
     "data": {
      "text/markdown": [
       "`pidgy` considers [Markdown] indented code blocks and language free code fences\n",
       "as valid [Python] code while every other object is represented as a triple \n",
       "quoted block string.\n",
       "\n",
       "    print(\"Indented blocks are always code like in literate coffeescript.\")"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "`pidgy` considers [Markdown] indented code blocks and language free code fences\n",
    "as valid [Python] code while every other object is represented as a triple \n",
    "quoted block string.\n",
    "\n",
    "    print(\"Indented blocks are always code like in literate coffeescript.\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Executing code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "There are two specific to ensure that code is executed in `pidgy`.\n",
       "\n",
       "### Indented code.\n",
       "\n",
       "Like in the prior cell, an indented code block is a specific token in Markdown\n",
       "that `pidgy` recognizes canonically as code.\n",
       "\n",
       "    \"This is code\" # because of the indent.\n",
       "\n",
       "### Code fences.\n",
       "\n",
       "```\n",
       "\"I am code because no language is specified.\"\n",
       "```\n",
       "\n",
       "### Ignoring code.\n",
       "\n",
       "Include a language with the code fence to skip code execution.\n",
       "\n",
       "```alangage\n",
       "Add alanguage specification to code fence to ignore its input.\n",
       "```\n",
       "\n",
       "Or, use html tags.\n",
       "\n",
       "<pre><code>\n",
       "I am explicit HMTL.\n",
       "</code></pre>"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "There are two specific to ensure that code is executed in `pidgy`.\n",
    "\n",
    "### Indented code.\n",
    "\n",
    "Like in the prior cell, an indented code block is a specific token in Markdown\n",
    "that `pidgy` recognizes canonically as code.\n",
    "\n",
    "    \"This is code\" # because of the indent.\n",
    "\n",
    "### Code fences.\n",
    "\n",
    "```\n",
    "\"I am code because no language is specified.\"\n",
    "```\n",
    "\n",
    "### Ignoring code.\n",
    "\n",
    "Include a language with the code fence to skip code execution.\n",
    "\n",
    "```alangage\n",
    "Add alanguage specification to code fence to ignore its input.\n",
    "```\n",
    "\n",
    "Or, use html tags.\n",
    "\n",
    "<pre><code>\n",
    "I am explicit HMTL.\n",
    "</code></pre>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Testing code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "`pidgy` recognizes doctests, a literate programming approach to testing, in the input and executes them in a formal unittest\n",
       "testing suite. `doctest` are identified by the `\">>>\"` line prefix.\n",
       "\n",
       "    >>> assert True\n",
       "    >>> print\n",
       "    <built-in function print>\n",
       "    >>> pidgy\n",
       "    <module...__init__.py'>"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "`pidgy` recognizes doctests, a literate programming approach to testing, in the input and executes them in a formal unittest\n",
    "testing suite. `doctest` are identified by the `\">>>\"` line prefix.\n",
    "\n",
    "    >>> assert True\n",
    "    >>> print\n",
    "    <built-in function print>\n",
    "    >>> pidgy\n",
    "    <module...__init__.py'>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Weaving and templating code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "`pidgy` permits the popular `jinja2` templating syntax.  Any use of \n",
       "templates references <code>{{}}</code> will be filled in with\n",
       "information from the current namespace.\n",
       "\n",
       "There is a variable `foo` with the value <code>20</code>.\n",
       "\n",
       "    foo = 20"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "`pidgy` permits the popular `jinja2` templating syntax.  Any use of \n",
    "templates references <code>{% raw %}{{}}{% endraw %}</code> will be filled in with\n",
    "information from the current namespace.\n",
    "\n",
    "There is a variable `foo` with the value <code>{{foo}}</code>.\n",
    "\n",
    "    foo = 20"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Suppressing the weave output."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "\n",
    "\n",
    "`pidgy` will not render any input beginning with a blank line."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Emergent language features"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/markdown": [
       "Interleaving Markdown and Python results in natural metasyntaxes that allow\n",
       "`pidgy` authors to write programs that look like documentation.\n",
       "\n",
       "### Docstrings.\n",
       "\n",
       "[Markdown] that follows function and class definitions are wrapped as block strings\n",
       "and indented according `pidgy`'s heuristics. What results is the [Markdown]\n",
       "represents the docstring.\n",
       "\n",
       "    def my_function():\n",
       "\n",
       "`my_function` demonstrates how docstrings are defined.\n",
       "\n",
       "    class MyClass:\n",
       "\n",
       "The same goes for class definitions.\n",
       "\n",
       "    ...\n",
       "    >>> my_function.__doc__\n",
       "    '`my_function` demonstrates how ...'\n",
       "    >>> MyClass.__doc__\n",
       "    'The same goes for class definitions.'"
      ],
      "text/plain": [
       "<IPython.core.display.Markdown object>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "Interleaving Markdown and Python results in natural metasyntaxes that allow\n",
    "`pidgy` authors to write programs that look like documentation.\n",
    "\n",
    "### Docstrings.\n",
    "\n",
    "[Markdown] that follows function and class definitions are wrapped as block strings\n",
    "and indented according `pidgy`'s heuristics. What results is the [Markdown]\n",
    "represents the docstring.\n",
    "\n",
    "    def my_function():\n",
    "\n",
    "`my_function` demonstrates how docstrings are defined.\n",
    "\n",
    "    class MyClass:\n",
    "\n",
    "The same goes for class definitions.\n",
    "\n",
    "    ...\n",
    "    >>> my_function.__doc__\n",
    "    '`my_function` demonstrates how ...'\n",
    "    >>> MyClass.__doc__\n",
    "    'The same goes for class definitions.'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "    # NBVAL_SKIP\n",
    "## Interactive Testing\n",
    "\n",
    "Failures are treated as natural outputs of the documents.  Tests may fail, but parts of the unit may be reusable.\n",
    "\n",
    "    def test_functions_start_with_test():\n",
    "        assert False, \"False is not True\"\n",
    "        assert False is not True\n",
    "    ...\n",
    "\n",
    "<!--\n",
    "\n",
    "    skip_explicit_failure(test_functions_start_with_test)\n",
    "\n",
    "-->"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "pidgy 3",
   "language": "python",
   "name": "pidgy"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.7.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}