From 6be43664fd0e090a0e33fde891fff790659ad7b5 Mon Sep 17 00:00:00 2001 From: Aidan Woods Date: Sat, 21 May 2022 22:26:39 +0100 Subject: [PATCH] Add additional explaination for the `State` object Adds a small non-technical introduction to help with intuition, after the object appears for the first time. --- docs/Migrating-Extensions-v2.0.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/Migrating-Extensions-v2.0.md b/docs/Migrating-Extensions-v2.0.md index ccefdc8..8e49cc5 100644 --- a/docs/Migrating-Extensions-v2.0.md +++ b/docs/Migrating-Extensions-v2.0.md @@ -44,6 +44,16 @@ $Parsedown = new Parsedown(ParsedownExtra::from(ParsedownMath::from(new State))) $Parsedown = new Parsedown(ParsedownMath::from(ParsedownExtra::from(new State))); ``` +In the above, the first object that we initialise the chain of composed extensions is the `State` object. This `State` +object is passed from `ParsedownExtra` to `ParsedownMath`, and then finally, to `Parsedown`. At each stage new +information is added to the `State`: adding or removing parsing instructions, and to enabling or disabling features. + +The `State` object both contains instructions for how to parse a document (e.g. new blocks and inlines), as well as +information used throughout parsing (such as link reference definitions, or recursion depth). By writing `new State`, +we create a `State` object that is setup with Parsedown's default behaviours, and by passing that object through +different extensions (using the `::from` method), these extensions are free to alter, add to, or remove from that +default behaviour. + ## Introduction to the `State` Object Key to Parsedown's new composability for extensions is the `State` object.