User:Alvinos/dev

= What is Ladybug ? = Ladybug is a bug handler for MediaWiki pages. I made it to match my own needs, on my own website, which uses many templates and requires many transclusions to display a single page. The code of these templates is complex, and very hard to debug because of the number of their interactions. Thus, I wrote Ladybug.

MediaWiki already handles its own internal errors. So this never meant to be Ladybug's job. However, templates (or any other includable page) are unable to report sysops in case of bug, error or warning. Neither can they produce detailed reports about variables' or parameters' values. Ladybug was written to achieve such a detailed tracking.

= How does it work ? =

Ladybug is not one of these extensions which do all the job by itself. Changes need to be applied to the pages of the wiki.

Ladybug adds two new parser functions to MediaWiki:
 * which sends neutral reports to Ladybug
 * which sends error reports to Ladybug

These two parser functions have to be added into the text of any wiki page you wish Ladybug to watch. They are like beacons, which inform Ladybug about what's going on right now.

With the first one, you can inform Ladybug about a variable value, a parameter value, the beginning of a new execution stage, the result of a control structure, etc.

With the second one, you can inform Ladybug about a missing parameter, an unavailable article, or an invalid parameter value.

During all the execution time, Ladybug collects data. Then, it generates a report to make it readable.

= Ladybug's features = Ladybug is able to do the following few things:
 * Listen to any kind of article for event or error messages.
 * Generate a full report to make such information readable. This report features:
 * A chronology section, which show exactly what happened, when, and in what order;
 * An entities section, which groups events of the same type under subsections;
 * An errors section, which displays all the errors encountered during execution.
 * Log any error on a dedicated log page.
 * Act in standby mode when not needed: event collection is disabled when Ladybug is not used, whereas error collection is always enabled.
 * Deny its use to unallowed users via a special user right.
 * Fit anybody's needs: the source code was written so that new error or event types can be added quickly to the default ones.

= Base concepts = Ladybug uses standard parser functions, which only accepts three parameters:
 * 1) an instruction
 * 2) a subject
 * 3) a predicate

The order of these parameters never changes: the first one is always an instruction, the second one a subject, and the last one a predicate.

Role of each parameter

 * Instructions are the most important parameter of a Ladybug call. They allow to define the call's goal (e.g.: "parameter_value").  and   do not share the same instructions set.
 * Subjects mostly define the item the call applies to (e.g.: a parameter name).
 * A predicate is what the call says about a subject (e.g: a parameter value).

Example
The following call:  tells Ladybug that
 * 1) We'll send a parameter value (instruction)
 * 2) The name of the parameter is "myParameter" (subject)
 * 3) The value of the parameter is "33" (predicate)

Group instructions
When using the parser function which is dedicated to events, you'll have to deal with group instructions. Group instructions begin with an operator, whereas simple instructions begin directly with an instruction name. The "parameter_value" instruction (from the previous example) is a simple instruction.

For now, there is only two valid operators in Ladybug: new and end.
 * new marks the beginning of a group instruction.
 * end marks the end of a group instruction.

Group instructions are instructions which are meant to include other instructions. For example, "loop" is a group instruction, since it will include several other instructions inside a loop structure. The correct syntax for such a case would be: We inform Laybug about the beginning of a new loop, with type "while" and condition "i < 10"

We inform Ladybug about the beginning of a new iteration, with counter variable "myCounter" = "1" We inform Ladybug about the value of the variable "myVariable", which is "10" We inform Ladybug about the end of an iteration

We inform Ladybug about the beginning of a new iteration, with counter variable "myCounter" = "2" We inform Ladybug about the value of the variable "myVariable", which is "100" We inform Ladybug about the end of an iteration

...

We inform Ladybug about the end of the loop

= Syntax = Here are the default syntax rules for each parser function:

Simple instructions

 * parameter_check allows to inform Ladybug about the result of a parameter check:
 * parameterName is the name of the checked parameter.
 * checkResult is the result of the parameter check (generally "success" or "failure").
 * checkResult is the result of the parameter check (generally "success" or "failure").


 * parameter_value allows to inform Ladybug about the value of a parameter:
 * parameterName is the name of the parameter.
 * parameterValue is the value of the parameter.
 * parameterValue is the value of the parameter.


 * variable_value allows to inform Ladybug about the value of a variable:
 * variableName is the name of the variable.
 * variableValue is the value of the variable.
 * variableValue is the value of the variable.


 * condition_notice allows to inform Ladybug about the result of an alternative control structure like "if" or "else":
 * condition is the condition which was tested.
 * result is the result of the test (generally "true" or "false").
 * result is the result of the test (generally "true" or "false").

Group instructions

 * pagename allows to inform Ladybug about the name of the current page. This instruction should be the first Ladybug call of any page, since Ladybug won't process anything if it can't find it.
 * pagename is a full pagename (namespace included).
 * pageDescription is a description of what this page aims to do.
 * pageDescription is a description of what this page aims to do.


 * stage allows to define execution stages within the code:
 * stageName is a short name for the stage.
 * stageDescription is a longer description of the stage.
 * stageDescription is a longer description of the stage.


 * loop allows to mark the beginning and the end of a loop structure:
 * loopType is a usual loop type ("for", "while"...).
 * loopCondition is the loop execution condition.
 * loopCondition is the loop execution condition.


 * iteration allows to mark the beginning and the end of a loop iteration. It is only used within a loop:
 * counterName  is the name of the counter variable for the current loop.
 * counterValue  is the value of the counter for the current iteration.
 * counterValue  is the value of the counter for the current iteration.