- Overview
- Usage
- License
Rx is a DSL that extends Markdown for the purpose of defining a document in terms of constraints on its structure and content. An Rx file can then be used to validate the conformance of other plain markdown documents to the generic document definition.
CommonMark is a formal specification of
Markdown and is the specific standard that Rx extends. A valid CommonMark file
is also a valid Rx file and in the context of Rx, describes a document that must
match identically. In addition to this Literal type of specification, Rx
provides the three tokens -!!-, -??-, and -""- which indicate Mandatory,
Optional, and Repeatable respectively. CommonMark conceptualizes a markdown
document as consisting of block and inline elements and the exact meaning of the Rx
tokens is dependent on the type of Markdown element it is used in conjunction
with.
In CommonMark, inline elements contain textual content and formatting context. In addition to plain textual content, they include things such as links, inline code snippets, emphasis, etc. The full list of element types can be viewed in the CommonMark Spec.
Rx tokens that appear in the context of inline elements represent prompts for arbitrary textual content to appear according to token type.
-
Literal Any textual content that is not an Rx token or a syntactic element of Markdown must be matched with an identical section of text.
The exception to this is inline HTML which will be ignored for the purposes of matching. Feel free to use them as placeholders or comments.
-
-!!-MandatorySome content must be inserted here. Each mandatory token must match with at least one non-whitespace characters, so adjacent mandatory tokens must be matched with content whose length is greater than or equal to the number of tokens.
-
-??-OptionalSome content may be inserted here, but is not necessary for the document to be considered valid.
-
-""-RepeatableHas no signifigance in this context. Is not considered a valid usage of this token.
# A Heading
Some content.# A Heading
Some content.Literally anything else.# We're off to see -!!-
The -!!- of -!!-.# We're off to see the wizard
The wonderful wizard of Oz.# We're off to see the veterinarian
The priciest doctor of dogs.# We're off to see the optometrist
The optometrist will tell us if we are in need of glasses.# We're off to see
The dentist because our teeth are full of cavities.In this case, the Mandatory token in the heading has not been satisfied.
Seeking a -??-qualified applicant for our remote -??- offices.Seeking a woefully unqualified applicant for our remote customer support offices.Seeking a qualified applicant for our remote offices.Seeking a marginally qualified applicant for our remote call center.An inline Optional token cannot by itself cause a mismatch since it can match any textual content or nothing. In this case the mismatch is triggered by the Literal content
officesbeing omitted.
Please [visit](https:://-!!-.polysync.io) us on the web!Please [visit](https:://www.polysync.io) us on the web!Please [visit](https:://www.rx.polysync.io) us on the web!Please [visit](https:://.polysync.io) us on the web!Rejected because there was no prefix specified in the uri.
Please [visit](http:://scam.polysync.io) us on the web!Rejected because the
swas omitted from the protocol portion of the uri.
In CommonMark, block elements are categorized into container blocks and leaf blocks. Leaf blocks such as Paragraphs or Headings contain inline elements. Container blocks such as List Items or Block Quotes can contain both leaf blocks and other container blocks. The full description of blocks elements and their types is available in the CommonMark Spec.
In Rx, block elements can be annotated with an Rx token to indicate a block-level matching rule. The placement of the token is usually at the beginning of the element on its own line, but varies slightly depending on the element type due to the constraints of CommonMark syntax. See the Block Element Annotation section below for examples of token placement for each different element type.
Block elements with block-level tokens can also be classified as being Explicit, or Wildcard types. Explicit types contain additional content, whereas Wildcard types contain just the block-level token annotation.
The match constraints imposed by block-level tokens are as follows.
-
Literal
A Literal Block Element is a block element without a block-level Rx token. Literal elements are implicitly mandatory and all their contained elements must match according to their individual match constraints in order for the block as a whole to match.
The exception to this is HTML Blocks. These will be ignored. Feel free to use them as placeholders or comments.
-
-!!-Mandatory-
Explicit:
In order to match, a block element of the same type must appear in this position in the matching document. In addition, all block elements contained within the scope of this element must also be matched according to their relevant matching constraints.
-
Wildcard:
In order to match, a block element of the same type must appear in this position in the document however, it may contain any number of arbitrary internal elements.
-
-
-??-Optional-
Explicit:
In order to match, a block element of the same type may appear in this position in the matching document but is not necessary for the document as a whole to match. If the element does appear, all contained elements must also be matched according to their respective constraints.
-
Wildcard
In order to match, a block element of the same type may appear in this position in the document, but is not necessary. If the element does appear, it may contain any number of arbitrary internal elements.
-
-
-""-RepeatableA block element may be specified as repeatable by placing an empty element of the same type immediately following it that is annotated with a block-level repeatable token. This indicates that any number of elements that match the repeatable element may appear at this position in the document. The matching constraints of the element marked as repeatable must still be adhered to however, i.e. if it is marked as mandatory, then at least one matching element must be present.
* -!!-
* Internal Content* -!!-* -??-
* Internal Content* -??-* Some Content
* -""-> -!!-
> Internal Content> -!!-> -??-
> Internal Content> -??-> Some Content
> -""-# -!!-
# Heading Content# -!!-# -??-
# Heading Content# -??-# Heading Content
# -""--!!-
Paragraph Content-!!--??-
Paragraph Content-??-Paragraph Content
-""-```-!!-
Code Block Content
``````-!!-
``````-??-
Code Block Content
``````-??-
``````
Code Block Content
```
```-""-
```Block level tokens are not supported for indented code blocks due to the
limitations imposed by libcmark the current canonical CommonMark parser. This
may be addressed in future version of the spec.
HTML Blocks are ignored and therefore do not support annotation.
# -!!-
# The wonderful thing about tiggers
-!!-
Is tiggers are wonderful things!or
# The wonderful thing about tiggers
Is tiggers are wonderful things!# The wonderful thing about tiggers
Is tiggers are wonderful things!The wonderful thing about tiggers
Is tiggers are wonderful things!Rejected because although the text of the first block matches, it is not part of the same type of block element.
# The wonderful thing about tiggers
Is tiggers are wonderful things!
Their tops are made out of rubber
Their bottoms are made out of springs!Rejected because of superflous paragraphs included at the end.
Four score and seven years ago our fathers brought forth on this continent a new
nation, conceived in Liberty, and dedicated to the proposition that all men are
created equal.
-??-
Now we are engaged in a great civil war, testing whether that nation or any
nation so conceived and so dedicated, can long endure....
-??-
But, in a larger sense, we can not dedicate—we can not consecrate—we can
not hallow—this ground....
> -??-
> TLDR; -!!-Four score and seven years ago our fathers brought forth on this continent a new
nation, conceived in Liberty, and dedicated to the proposition that all men are
created equal.
Now we are engaged in a great civil war, testing whether that nation or any
nation so conceived and so dedicated, can long endure....
But, in a larger sense, we can not dedicate—we can not consecrate—we can
not hallow—this ground....Four score and seven years ago our fathers brought forth on this continent a new
nation, conceived in Liberty, and dedicated to the proposition that all men are
created equal.
> TLDR; We must finish what we have started my dudes.A literal intro paragraph.
-!!-
A mandatory paragraph about -!!-.
-""-
-??-
An optional closing paragraph that must say this if present.A literal mandatory intro paragraph.
A mandatory paragraph about turnips.
A mandatory paragraph about bacon.
An optional closing paragraph that must say this if present.A literal intro paragraph.
A mandatory paragraph about superheroes.A literal intro paragraph.A verbatim intro paragraph.
An optional closing paragraph that must say this if present.* First Item
* -""-
* Last Item* First Item
* Second Item
* Third Item
* Last Item* First Item
* Last Item© 2018, Devin Smith [email protected], Nathan Äschbacher [email protected]