Examples

Building the examples

You can use the samples.gpr GNAT project and the gnatmake tool to build the examples:

gnatmake -Psamples

Rendering example

The render example uses the Wiki renderer to generate 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.

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 a number of variables for the Wiki input representation, define a set of Wiki filters, declare the Wiki document instance and the Wiki engine instance:

with Wiki.Streams.Text_IO;
with Wiki.Filters.Html;
with Wiki.Filters.Autolink;
with Wiki.Filters.TOC;
with Wiki.Documents;
with Wiki.Parsers;
...
     Input    : aliased Wiki.Streams.Text_IO.File_Input_Stream;
     Filter   : aliased Wiki.Filters.Html.Html_Filter_Type;
     Autolink : aliased Wiki.Filters.Autolink.Autolink_Filter;
     TOC      : aliased Wiki.Filters.TOC.TOC_Filter;
     Doc      : Wiki.Documents.Document;
     Engine   : Wiki.Parsers.Parser;

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

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 two renderers:

• A Text renderer that produces text outputs,
• A HTML renderer that generates an HTML presentation for the document.

The renderer needs an output stream instance.

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.

Word Collector Example

The words examples shows how to parse a Wiki document in order to extract some information stored in the document. For example you may use it to collect a list of words, a list of links or a list of images that are referenced by the document.

Report list of words or links used in a wiki text file or HTML file
Usage: words [-l] [-i] [-m] [-H] [-M] [-d] [-c] {wiki-file}
  -l        Report links instead of words
  -i        Report images instead of words
  -m        Parse a Markdown wiki content
  -M        Parse a Mediawiki wiki content
  -d        Parse a Dotclear wiki content
  -g        Parse a Google wiki content
  -c        Parse a Creole wiki content
  -H        Parse an HTML content

This example uses the Collectors filter to identify and keep the useful information while a document is parsed. You will need to declare the collector filters:

with Wiki.Filters.Collectors;
...
   Words      : aliased Wiki.Filters.Collectors.Word_Collector_Type;
   Links      : aliased Wiki.Filters.Collectors.Link_Collector_Type;
   Images     : aliased Wiki.Filters.Collectors.Image_Collector_Type;

And then add it to the filter chain:

   Engine.Add_Filter (Words'Unchecked_Access);
   Engine.Add_Filter (Links'Unchecked_Access);
   Engine.Add_Filter (Images'Unchecked_Access);

After parsing the document, the collector filters will hold the information that you want. You will then use the Iterate procedure to iterate over each collected item:

procedure Print (Pos : in Wiki.Filters.Collectors.Cursor) is
   Count : constant Natural := Wiki.Filters.Collectors.WString_Maps.Element (Pos);
begin
   Ada.Wide_Wide_Text_IO.Put (Wiki.Filters.Collectors.WString_Maps.Key (Pos));
   Ada.Wide_Wide_Text_IO.Put (" ");
   Ada.Wide_Wide_Text_IO.Put_Line (Natural'Wide_Wide_Image (Count));
end Print;

Images.Iterate (Print'Access);
Links.Iterate (Print'Access);
Words.Iterate (Print'Access);