Beware: the functions in this module may raise exceptions! If you use them, you should be careful.
most important loop, which has to be given as an argument
Translate tokens to Markdown representation.
""
.
default language for code blocks
flag: bold/emph using using underscores is by default github-style, which means that underscores inside words are left as underscore, rather than special characters, because it's more convenient. However it is also less expressive because then you can't bold/emph a part of a word. You might want to set this flag to false.
flag: if true, will not check whether a used HTML tag actually exists in HTML.
flag: if true, will only accept known inline HTML tags in inline HTML.
flag: if true, will output warnings
flag: if true, will convert warnings to errors
default language for code blocks
flag: bold/emph using using underscores is by default github-style, which means that underscores inside words are left as underscore, rather than special characters, because it's more convenient. However it is also less expressive because then you can't bold/emph a part of a word. You might want to set this flag to false.
flag: if true, will not check whether a used HTML tag actually exists in HTML.
flag: if true, will only accept known inline HTML tags in inline HTML.
unindent_rev n l
returns the same couple as unindent n l
except that the first element (which is a list) is reversed.
This function is used for lists.
unindent n l
returns (unindented, rest)
where unindented
is
the consecutive lines of l
that are indented with at least n
spaces, and de-indented by n
spaces. If l
starts with a line
that is indented by less than n
spaces, then it returns ([], l)
.
(* This function is used for lists, so it does not require n
*)
(* spaces on every single line, but only on some specific ones of them. *)
This function is used for lists and blockquotes.
is_blank l
returns true
if l
only contains blanks, which are
spaces and newlines.
semph_or_bold n l
returns None
if l
doesn't start with
a bold/emph phrase (marked using stars), else it returns Some(x,y)
where x
is the emph and/or bold phrase at the beginning of l
and y
is the rest of l
.
sm_uemph_or_bold n l
returns None
if l
doesn't start with
a bold/emph phrase (marked using underscores), else it returns Some(x,y)
where x
is the emph and/or bold phrase at the beginning of l
and y
is the rest of l
.
gh_uemph_or_bold n l
returns None
if l
doesn't start with
a bold/emph phrase (marked using underscores), else it returns Some(x,y)
where x
is the emph and/or bold phrase at the beginning of l
and y
is the rest of l
.
uemph_or_bold n l
returns None
if l
doesn't start with a
bold/emph phrase (marked using underscores), else it returns
Some(x,y)
where x
is the emph and/or bold phrase at the
beginning of l
and y
is the rest of l
. N.B. if
!gh_uemph_or_bold_style
then in Github style (i.e., underscores
inside words are considered as underscores).
eat_blank l
returns l
where all blanks at the beginning of the
list have been removed (it stops removing as soon as it meets an element
that is not a blank). Blanks are spaces and newlines only.
tag__maybe_h1 main_loop
is a tag that is injected everywhere that
might preceed a H1 title. It needs main_loop
as argument because
it is used to parse the contents of the titles.
tag__maybe_h2 main_loop
is the same as tag__maybe_h1 main_loop
but for H2.
tag__md md
encapsulates md
to make it a value of type tok
.
Its purpose is to inject some pre-parsed markdown (i.e., md
of type t
)
in a yet-to-parse token stream of type tok
.
Tag used for the lines that *might* be titles using setext-style.
read_until_...
are functions that read from a token list
and return two token lists: the first one is the tokens read
until a specific token is met, and the second one is the remainder.
The particularity of these functions is that they do consider
backslash-escaped characters and closing characters.
For instance, read_until_gt "1 < 2 > 3 > 4"
returns
"1 < 2 > 3 ", " 4"
: note that the ">" before " 4" has disappeared
and that read_until_gt
takes a tok list
(not a string) and
returns a couple of tok list
(not a couple of strings), the
string notation is used here for concision.
Until otherwise noted, those functions do *not* consider
backquote-trapped sections.
For instance, read_until_gt "1 < 2 > 3 `>` 4"
returns "1 < 2 > 3 `", "` 4"
.
If you use these functions, you should make sure that they
do what you think they do (i.e., do look at the code).
If the expected characters are not found, the exception
Premature_ending
is raised. For instance,
read_until_gt "1 < > 3"
raises Premature_ending
.
If no_nl
is true
(default value for no_nl
is false
)
and '\n'
occurs before the splitting character,
then NL_exception
is raised.
read_title main_loop n r p l
returns Some(r,p,l)
if it succeeds, None
otherwise.
read_title main_loop n r p l
expects to read a n
-level
hash-declared title from l
, where the hashes have *already*
been *removed*. If n
is not between 1 and 6 (included), then
it returns None
.
main_loop
is used to parse the contents of the title.
r
and p
are the classical "result" and "previous" parameters.
maybe_extension e r p l
returns None
if there is no extension or
if extensions haven't had any effect, returns Some(nr, np, nl)
if
at least one extension has applied successfully.
emailstyle_quoting main_loop r p l
returns Some(r,p,l)
with
r
being the updated result, p
being the last parsed token
and l
being the remaining tokens to parse. If emailstyle_quoting
fails, then it returns None
, in which case its user is advise
to investigate why it returns None
because there's possibly a
real problem.
maybe_reference
tries to parse a reference, a reference definition or
a github-style short reference (e.g., foo
as a shortcut for foo
),
and returns Some(r,p,l)
if it succeeds, None
otherwise.
parse_list main_loop r p l
parses a list from l
.
**Important property*** It is considered in Omd that a sub-list is always more indented than the item that contains it (so, 2 items with different indentations cannot have the direct same parent).
Since Omd_parser.parse
doesn't build paragraphs, if you want
Markdown-style paragraphs, you need to apply this function to
the result of Omd_parser.parse
.