docs: add first draft of documentation for version 2.0

Still has a long way to go
showdownjs · Sep 25, 2018 · 4da93e8 · 4da93e8
1 parent d3ebff7
commit 4da93e8
Show file tree

Hide file tree

Showing 2 changed files with 158 additions and 0 deletions.
diff --git a/docs/event_system.md b/docs/event_system.md
@@ -0,0 +1,149 @@
+# Event System
+
+## Introduction
+
+
+## The Event Object
+
+
+## Events
+
+Events are raised when a subparser is run (or about to be run).
+Within a subparser, the events always follow a certain order (sequence). For instance, **.before** events always run before **.captureStart**.
+Each subparser raises several events sequentially:
+
+ 1. **.start**: **always runs** except it subparser is disabled
+
+    Raised when the **subparser has started**, but no capturing or any modification to the text was done.
+
+    **Always runs** (except if the subparser is deactivated through options).
+
+    ***Properties***:
+
+    | property | type      | access     | description                                                        |
+    |----------|-----------|------------|--------------------------------------------------------------------|
+    | input    | string    | read       | The full text that was passed to the subparser                     |
+    | output   | string    | write      | The full text with modification that will be passed along the chain|
+    | regex    | null      |            |                                                                    |
+    | matches  | null      |            |                                                                    |
+
+    Usually you would want to use this event if you wish to change the input to the subparser
+
+ 2. **.captureStart**: *might not be run*;
+
+     Raised when a regex match is found and a capture was successful. Some normalization and modification 
+     of the regex captured groups might be performed.
+
+     Might not be run if no regex match is found.
+
+     ***Properties***:
+
+     | property | type      | access     | description                                                        |
+     |----------|-----------|------------|--------------------------------------------------------------------|
+     | input    | string    | read       | The captured text                                                  |
+     | output   | string    | write      | The text that will be passed to the subparser/other listeners      |
+     | regex    | RegExp    | readonly   | Regular Expression used to capture groups                          |
+     | matches  | object    | read/write | Matches groups. Changes to this object are reflected in the output |
+     
+     Usually you would want to use this event if you wish to modify a certain subparser behavior.
+     Exs: remove all title attributes from links; change indentation of code blocks; etc...
+
+ 3. **.captureEnd**: *might not be run*;
+
+    Raised after the modifications to the captured text are done but before the replacement is introduced in the document.
+
+    Might not be run if no regex match is found.
+
+    ***Properties***:
+
+    | property   | type      | access     | description                                                                    |
+    |------------|-----------|------------|--------------------------------------------------------------------------------|
+    | input      | string    | read       | The captured text                                                              |
+    | output     | string    | write      | The text that will be passed to the subparser/other listeners                  |
+    | regex      | RegExp    | readonly   | Regular Expression used to capture groups                                      |
+    | matches    | object    | read/write | Keypairs of matches groups. Changes to this object are reflected in the output |
+    | attributes | object    | read/write | Attributes to add to the HTML output                                           |
+
+ 4. **.beforeHash**: *might not be run*;
+
+    Raised before the output is hashed.
+
+    Always run (except if the subparser was deactivated through options), even if no hashing is performed. 
+
+    ***Properties***:
+
+    | property | type       | access     | description                                                        |
+    |----------|------------|------------|--------------------------------------------------------------------|
+    | input    | string     | read       | The captured text                                                  |
+    | output   | string     | write      | The text that will be passed to the subparser/other listeners      |
+    | regex    | null       |            |                                                                    |
+    | matches  | null       |            |                                                                    |
+
+    Usually you would want to use this event if you wish change the subparser output before it is hashed
+
+ 5. **.end**: *always runs*;
+
+    Raised when the subparser has finished its work and is about to exit.
+
+    Always runs (except if the subparser is deactivated through options).
+
+    ***Properties***:
+
+    | property | type      | access     | description                                                        |
+    |----------|-----------|------------|--------------------------------------------------------------------|
+    | input    | string    | read       | The partial/full text with the subparser modifications             |
+    | output   | string    | write      | The text that will be passed to other subparsers                   |
+    | regex    | null      |            |                                                                    |
+    | matches  | null      |            |                                                                    |
+     
+    Usually you would want to use this event if you wish change the subparser hashed output
+
+
+### Special Events
+
+There are some special events that are useful for *"positioning"* a listener extension in the main chain of events.
+Usually these extensions introduce new syntax that, due to precedence 
+These events are always guaranteed to be called, regardless of options or circumstances. 
+
+ 1. **.before_{subparserName}**: *always runs*
+
+    Raised just before the **{subparserName} is about to be entered**.
+
+    ***Properties***:
+
+    | property | type      | access     | description                                                        |
+    |----------|-----------|------------|--------------------------------------------------------------------|
+    | input    | string    | read       | The full text that was passed to the subparser                     |
+    | output   | string    | write      | The full text with modification that will be passed along the chain|
+    | regex    | null      |            |                                                                    |
+    | matches  | null      |            |                                                                    |
+
+ 2. **.after**.{subparserName}: *always runs*;
+
+    Raised when the **{subparserName} has exited** and before the next one is called.
+
+    ***Properties***:
+
+    | property | type      | access     | description                                                        |
+    |----------|-----------|------------|--------------------------------------------------------------------|
+    | input    | string    | read       | The partial/full text with the subparser modifications             |
+    | output   | string    | write      | The text that will be passed to other subparsers                   |
+    | regex    | null      |            |                                                                    |
+    | matches  | null      |            |                                                                    |
+
+
+### Notes
+
+ - There are 2 main differences between **before.{subparserName}** and **{subparserName}.start**.
+
+     1. **before.{subparserName}** is always guaranteed to be called, even if the subparser is disabled, 
+        while **{subparserName}.start** doesn't.
+
+        ex: `makehtml.before.strikethrough` is always called even if the option `strikethrough` is false 
+
+     2. **before.{subparserName}** is only raised once in a span context while **{subparserName}.start** is raised
+        everytime **{subparserName}** is called.
+
+    As a rule of thumb, 
+
+## Events List
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,9 @@
+# Index
+
+1. Options
+2. Subparsers
+3. [Event System](event_system.md)
+    1. [Introduction](event_system.md#introduction)
+    2. [The Event Object](event_system.md#the-event-object)
+    3. [Events](event_system.md#events)
+    4. [Events List](event_system.md#events-list)