The Ada Wiki Engine is a small Ada library that parses a Wiki text in several Wiki syntax such as MediaWiki, Creole, Markdown and renders the result either in HTML, text or into another Wiki format. The Ada Wiki Engine is used in two steps:
- The Wiki text is parsed according to its syntax to produce a Wiki Document instance.
- The Wiki document is then rendered by a renderer to produce the final HTML or text.
The Ada Wiki Engine does not manage any storage for the wiki content so that it only focuses on the parsing and rendering aspects.
Overview
The Ada Wiki engine is organized in several packages:
- Several Wiki stream packages define the interface, types and operations for the Wiki
engine to read the Wiki or HTML content and for the Wiki renderer to generate the HTML or text outputs.
- The Wiki parser is responsible for parsing HTML or Wiki content according to a
selected Wiki syntax. It builds the final Wiki document through filters and plugins.
- The Wiki filters provides a simple filter framework that allows to plug specific
filters when a Wiki document is parsed and processed. Filters are used for the table of content generation, for the HTML filtering, to collect words or links and so on.
- The Wiki plugins defines the plugin interface that is used by the Wiki engine
to provide pluggable extensions in the Wiki. Plugins are used for the Wiki template support, to hide some Wiki text content when it is rendered or to interact with other systems.
- The Wiki documents and attributes are used for the representation of the Wiki
document after the Wiki content is parsed.
- The Wiki renderers are the last packages which are used for the rendering of the
Wiki document to produce the final HTML or text.
Building Ada Wiki Engine
Download the ada-wiki-1.0.1.tar.gz or get the sources from GitHub:
git clone git@github.com:stcarrez/ada-wiki.git ada-wiki
If you are using Ada Utility Library then you can configure with:
./configure
Otherwise, you should configure with:
./configure --with-ada-util=no
Then, build the library:
make
Once complete, you can install it:
make install
To use the library in your Ada project, add the following line in your GNAT project file:
with "wiki";
Rendering example
The rendering example described in this article generates an HTML or text content from a Wiki source file. The example reads the file in one of the supported Wiki syntax and produces the HTML or text. You will find the source file on GitHub in render.adb. The example has the following usage:
Render a wiki text file into HTML (default) or text
Usage: render [-t] [-m] [-M] [-d] [-c] [-s style] {wiki-file}
-t Render to text only
-m Render a Markdown wiki content
-M Render a Mediawiki wiki content
-d Render a Dotclear wiki content
-g Render a Google wiki content
-c Render a Creole wiki content
-s style Use the CSS style file
Parsing a Wiki Text
To render a Wiki text you will first need to parse the Wiki text and produce a Wiki document instance. For this you will need to declare the Wiki document instance and the Wiki parser instance:
with Wiki.Documents;
with Wiki.Parsers;
...
Doc : Wiki.Documents.Document;
Engine : Wiki.Parsers.Parser;
The Ada Wiki Engine has a filter mechanism that is used while parsing the input and before building the target wiki document instance. Filters are chained together and a filter can do some work on the content it sees such as blocking some content (filtering), collecting some data and doing some transformation on the content. When you want to use a filter, you have to declare an instance of the corresponding filter type.
with Wiki.Filters.Html;
with Wiki.Filters.Autolink;
with Wiki.Filters.TOC;
...
Filter : aliased Wiki.Filters.Html.Html_Filter_Type;
Autolink : aliased Wiki.Filters.Autolink.Autolink_Filter;
TOC : aliased Wiki.Filters.TOC.TOC_Filter;
We use the Autolink filter that detects links in the text and transforms them into real links. The TOC filter is used to collect header sections in the Wiki text and builds a table of content. The Html filter is used to filter HTML content that could be contained in a Wiki text. By default it ignores several HTML tags such as html, head, body, title, meta (these tags are silently discarded). Furthermore it has the ability to hide several elements such as style and script (the tag and its content is discarded).
You will then configure the Wiki engine to build the filter chain and then define the Wiki syntax that the parser must use:
Engine.Add_Filter (TOC'Unchecked_Access);
Engine.Add_Filter (Autolink'Unchecked_Access);
Engine.Add_Filter (Filter'Unchecked_Access);
Engine.Set_Syntax (Syntax);
The Wiki engine gets its input from an Input_Stream interface that only defines a Read procedure. The Ada Wiki Engine provides several implementations of that interface, one of them is based on the Ada Text_IO package. This is what we are going to use:
with Wiki.Streams.Text_IO;
...
Input : aliased Wiki.Streams.Text_IO.File_Input_Stream;
You will then open the input file. If the file contains UTF-8 characters, you may open it as follows:
Input.Open (File_Path, "WCEM=8");
where File_Path is a string that represents the file's path.
Once the Wiki engine is setup and the input file opened, you can parse the Wiki text and build the Wiki document:
Engine.Parse (Input'Unchecked_Access, Doc);
Rendering a Wiki Document
After parsing a Wiki text you get a Wiki.Documents.Document instance that you can use as many times as you want. To render the Wiki document, you will first choose a renderer according to the target format that you need. The Ada Wiki Engine provides three renderers:
- A Text renderer that produces text outputs,
- A HTML renderer that generates an HTML presentation for the document,
- A Wiki renderer that generates various Wiki syntaxes.
The renderer needs an output stream instance. We are using the Text_IO implementation:
with Wiki.Stream.Html.Text_IO;
with Wiki.Render.Html;
...
Output : aliased Wiki.Streams.Html.Text_IO.Html_File_Output_Stream;
Renderer : aliased Wiki.Render.Html.Html_Renderer;
You will then configure the renderer to tell it the output stream to use. You may enable or not the rendering of Table Of Content and you just use the Render procedure to render the document.
Renderer.Set_Output_Stream (Output'Unchecked_Access);
Renderer.Set_Render_TOC (True);
Renderer.Render (Doc);
By default the output stream is configured to write on the standard output. This means that when Render is called, the output will be written to the standard output. You can choose another output stream or open the output stream to a file according to your needs.
Conclusion
The Ada Wiki Engine can be used to parse HTML content, sanitize the result through the HTML filter and convert it to text or to some Wiki syntax (have a look at the import.adb example). The engine can be extended through filters or plugins thus providing some flexible architecture. The library does not impose any storage mechanism. The Ada Wiki Engine is the core engine used by AWA Blogs and AWA Wiki web applications. You may have a look at some online Wiki in the Atlas Wiki demonstrator.