Core¶
MDiocre¶
The core converter.
- class mdiocre.core.MDiocre(parser=None, parser_name=None)¶
Main class to process source files and render HTML files.
- Parameters
parser (Optional) – a BaseParser-derived object. If both parser_name and parser are defined, parser takes the priority.
parser_name (str, Optional) – The parser name. See
switch_parser()
for which ones are currently implemented.
- process(string, ignore_content=False)¶
Process a string into a variable dictionary to use e.g. with
render()
.The string is processed according to a parser that converts it to HTML and extracts any MDiocre “commands”. For Markdown and HTML, these are stuff that is prefixed with <!–:, for RST, it’s :mdiocre:.
More details about the conversion process can be found in
VariableManager
.As of 3.1, this is really a wrapper for all the parsers.
- Parameters
string (string) – A string containing MDiocre commands.
ignore_content (bool, Optional) – If True, it will not convert the string to the content variable.
- Returns
A VariableManager object containing the processed variables, that also contains the converted HTML under the
content
variable, if ignore_content is False.
- render(template, variables)¶
Renders a template with the specified variables.
Due to the mechanism, template variables are separate from the page’s variables. The converted page is defined in the
content
variable, and can be used by templates to render the documents.- Parameters
template (string) – A string containing formatted comments.
variables (VariableManager) – Variable object to use with the template.
- Returns
The processed string.
- switch_parser(name)¶
Switch parsers by using an identifier. To implement a new parser, it must be a class with inherited from
BaseParser
, Its name and file name must also match, e.g. a parser with the html identifier must be in html.py and have the class name of HtmlParser.- Parameters
name (string) – Parser name. Currently implemented: markdown, html, rst, zim
- Returns
None.
Variable Manager¶
This stores information that can be set and or replaced in a text.
- class mdiocre.core.VariableManager¶
Variable manager.
Variables are stored as a dictionary under self.variables. The identifiers can be any character except the = operator, which serves to separate the identifier and the value.
Warning
- There are a few reserved variables, which their names cannot be used, namely:
content : The contents of a page that will be put into a template
mdiocre-gen-timestamp : Timestamp of the generated content
Note
The
mdiocre-template
variable is required when using theWizard
.- assign(query)¶
Assigns a variable to a value.
The variable name has almost no limitations (especially not limitations usually posed by a programming language), but it is terminated by the = symbol.
- The value can be one of the following:
- Stringif the value has quotes (single or double) around it.
Example query:
My Variable = "Toast"
- Concatenationif two or more variable names are specified, with a comma separating each.
Example query:
My Variable = Var 1, Var 2
Value assignment : if the value is a variable name. This is assumed to be the default. Will assign to an empty string if the variable is not found.
Example query:
My Variable = Something else
Function calls : if a function is defined using the
using
keyword, it may be used for dynamic data conversion and processing. Surrounded by parentheses, the word directly after it is the function name, followed by its arguments, surrounded by spaces. Like regular Python, strings need to be in quotes. Arguments may be names of variables that are already defined up to that point, they will be automatically substituted.Example query:
RSSDate = (toRFC822 PubDate)
- ..warning::
The function call feature executes raw Python code, so it may pose a security risk! Use with caution, and double-check your source files!
- Parameters
query (string) – Expects a string in the form of
variable = value
.- Returns
None (or SyntaxError). If the variable is successfully assigned, its value will be added to the object’s
variables
dictionary.
- get(variable)¶
Gets a variable from the variables list and returns its value.
- Parameters
variable (string) – Name of the variable.
- Returns
String contents of the variable, or an empty string if the variable is not found.
- parse_keyword(query)¶
Currently called from
function()
, this implements a few commands, or “keywords” that can be used to implement a little more modularity in one’s templates/contents.Operands are separated by the colon :, on the left hand side is the keyword, on the right hand is the argument, assumed to be a string.
The keyword is case-insensitive.
- They can be one of the following:
- IncludeEssentially, it literally includes a file into the template or content. It can be used to set global variables, include common banners, etc. Its argument is a file RELATIVE TO THE WORKING DIRECTORY THE SCRIPT IS CALLED IN!
Example:
Include: ../variables.html
- UsingLoad a Python script. You can use it to define a few functions which can be useful with the function call feature during assignment, for example to dynamically convert a few strings of text.
Example:
Using: ../_functions.py
Warning
The using keyword executes raw Python code, so it may pose a security risk! Use with caution, and double-check your source files!
- Parameters
query (string) – Expects a string in the form of
keyword : argument
.- Returns
None (or SyntaxError).