examples of tangled pidgy input

this document is used to demonstrate how pidgy tangles code (ie translates markdown to python). each cell contains markdown input and the corresponding python code is revealed below.

indented code vs fenced code

the commonmark spec has two conventions before code, indented code and fenced code. literate programming languages generally choose on or the other. literate coffeescript prefers indented code while rmarkdown, myst, org-mode rely on code fences.

code fences always add markdown semantics at the interface of code and narrative. indented code on the other hand can seamlessly flow between narrative. pidgy uses the indented code opinion and creates new affordances for both markdown and python as a single metalanguage.

markdown as block strings

a single line of markdown is wrapped in block quotes.

"""markdown is just a string; the semi-colon is appended to suppress output.""";

markdown blocks, not containing indented code, are block strings.

"""`pidgy`s tangle scheme only requires block level parsing of markdown,
and all non-indented markdown blocks are represented as strings.
this approach breaks convention relative to other markdown-forward literate programming
implementations that rely on code fences to indicate executable code.

print(\"in `pidgy`, code fences are ignored.\")


what follows is a large python block string""";

"""quotations are \'\'escaped\' for safety\'""";

adding IPython code

"""code is acknowledged the first moment that an indented code block is found like the print expression below."""

print("this is the first line of real code")    
"""the result is valid python code with the markdown chunks represented as block strings""";

"""line continuations can be used to connection python expressions to the markdown blocks.""" 

a_block_of_markdown=\
\
"""we can explicitly use line continuations to connection indented python to markdown.
this block of code will define `a_block_or_markdown`""";

another tactic capturing blocks of markdown using parenthesis. in this form, methods can be applied to contents of the parenthesis. parenthesis are needed to combine multiple non-code markdown blocks.

parenthesized_markdown_block = (
"""one line"""

    +
    """another line"""

).upper()

"""explicit strings, even explicit regular formatted strings, are invoked when the preceding code block ends with triple quotes."""

explicit_string = rf"""
this markdown string is formatted and stripped.        

""".strip()

docstrings

on of the most convenient affordances of pidgy is the ability to naturally write docstrings in markdown.

def my_function():
                    """`my_function` doesn\'t do anything!"""

                    return # the position of the first line of code controls the aligned of the quotations

classes can be composed with docstrings for the type and methods.

class MyClass:
        """this is `MyClass`, i\'m object oriented!"""

        def my_method(self):
                    """`MyClass.my_method` has knowledge of self"""

                    pass

conflicting opinions

• magic functions - specific to ipython not python
• truncating markdown blocks with null operators ..., pass, "", # comment
• hiding output during the weave step
• line continuations