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 the Wizard.

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).