2.0.0

[aidantwoods]

Big PR to track everything for planned changes towards 2.0.0—please leave reviews here (preferably by adding a review to the relevant code site), or make PRs targeting the 2.0.x branch if you'd like to help.

I don't plan on making any more changes here directly, rather changes can be merged into this via separate dedicated PRs.

[aidantwoods]

@BenjaminHoegh I've converted ParsedownExtra to be compatible with this branch over at erusev/parsedown-extra#172.

Currently, the plan would be for "extensions" in the new world to implement the StateBearer protocol (they don't have to, but it helps with composability).

Using Parsedown with ParsedownExtra would look something like:

$Parsedown = new Parsedown(new ParsedownExtra);
$actualMarkup = $Parsedown->toHtml($markdown);

This would allow multiple extensions to be composed together, so that if there was another extension, say, ParsedownMath, then this could be composed with ParsedownExtra in whichever order the user prefers.

E.g.

$Parsedown = new Parsedown(ParsedownExtra::from(ParsedownMath::from(new State)));

$Parsedown = new Parsedown(ParsedownMath::from(ParsedownExtra::from(new State)));

Provided all extensions implement the StateBearer protocol, then these can be composed indefinitely (in practice, though, this could result in odd behaviours of course).

A State object incorporates Blocks, Inlines and some additional render steps, and any custom configuration options that the user might want to set. This can fully control how a document is parsed and rendered.

When writing the docs for new extensions to follow, I think it is a good idea to encourage extensions to document the state modifications they do so that a user can add these manually if they so wish. This, ultimately, will allow a user fairly granular control to try to make extensions interoperable (especially if extensions are large and contain quite a few behaviours).

For instance, if a user only wanted the "abbreviations" feature from ParsedownExtra and nothing else, then they could manually construct:

$State = new State;

$BlockTypes = $State->get(BlockTypes::class)
    ->addingMarkedLowPrecedence('*', [Abbreviation::class])
;

$RenderStack = $State->get(RenderStack::class)
    ->push(Abbreviations::expandAbbreviations())
;

$State = $State
    ->setting($BlockTypes)
    ->setting($RenderStack)
;

$Parsedown = new Parsedown($State);
$actualMarkup = $Parsedown->toHtml($markdown);

In the case of ParsedownExtra though, I've made each feature its own StateBearer, so one can just write:

use Erusev\ParsedownExtra\Features\Abbreviations;

$State = Abbreviations::from(new State);

$Parsedown = new Parsedown($State);
$actualMarkup = $Parsedown->toHtml($markdown);

This IMO, would be the ideal pattern for extensions to use: which allows very simple granular composability by the user, allowing them to pick just one feature, or the entire package of features with the extension as they wish.

[BenjaminHoegh]

@aidantwoods is there a way to manipulate with TList without having to rewrite it?

[aidantwoods]

There isn't. This is to make sure that mutations are localised and don't end up being in places where they weren't intended.

As a plus to this approach, this means that the Lis that make up the TList can all be passed by reference if they are unmodified without needing to clone. i.e. different TLists can safely reference the same underlying Lis because they aren't going to change unexpectedly.

This allows things like copying a TList to be done with a simple assignment, and allows those copies to be modified (actually overwritten) without risk of modifying another copy.

[aidantwoods]

Depending on what you're trying to do, could it be made easier if there was a constructor or more getters made available for TList?

[BenjaminHoegh]

Depending on what you're trying to do, could it be made easier if there was a constructor or more getters made available for TList?

Just trying to make tasks using the - [] my task

[BenjaminHoegh]

Missing information about the different ways to add such as addingMarketHighPrecedence

[BenjaminHoegh]

need some more information about adding new elements