added changelog for v1.2.0

Reviewed-on: MassiveDynamic/Parkdown#2

CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## Version 1.2.0
+The *"annotation release"*
+
+### Added
+* paragraph annotations *(now can set HTML ids and classes with `{.someClass, #someId}` syntax)*
+* unit tests for annotation
+* unit for headings *(`h1` to `h5`)*
+
+### Removed
+* Testing code in `index.php`
+
+## Version 1.1.2
+No major changes introduced, getting ready for release
+
+### Changed
+* added compatibility for `prism` code highlighting inside code blocks
+
+## Version 1.1.0
+No major changes introduced, getting ready for release
+
+### Added
+* unit tests via `PHPUnit`
+
+### Changed
+* Parser does not generate unnessecary empty paragraphs anymore
+* Fix: parse does not get stuck on blockquotes that are not followed by an empty
+  line anymore
+
+### Removed
+* "Monkey test" `.md` files in `tests` folder
+
+## Version 1.0.0
+Basic implementation

LICENSE.md

@@ -0,0 +1,18 @@
+Copyright (C) 2022, MikO <miko@massivedynamic.eu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -33,11 +33,27 @@ Parkdown currently support the following block types:
 ### Paragraphs
 ```markdown
 A simple paragraph can contain **bold text**, `inline codeblocks` and *italic text*. We can also link [with a direct url][https://google.com] *(i.e. to google)*
-or via reference to [a later defined url][massivedynamic], i we so desire.
+or via reference to [a later defined url][massivedynamic], if we so desire.
 ```
 
 A simple paragraph can contain **bold text**, `inline codeblocks` and *italic text*. We can also link [with a direct url](https://google.com) *(i.e. to google)*
-or via reference to [a later defined url][massivedynamic], i we so desire.
+or via reference to [a later defined url][massivedynamic], if we so desire.
+
+Paragraphs can be annotated with `id` and `class` attributes:
+
+```markdown
+Paragraphs can be annotated with ids and classes {.thisIsAClass, .anotherClass, #thisIsAnID}
+```
+
+results in
+
+Paragraphs can be annotated with ids and classes {.thisIsAClass, .anotherClass, #thisIsAnID}
+
+```html
+<p class="thisIsAClass anotherClass" id="thisIsAnID">
+	Paragraphs can be annotated with ids and classes
+</p>
+```
 
 ### Images
 ```markdown
@@ -57,14 +73,14 @@ or via reference to [a later defined url][massivedynamic], i we so desire.
 > Only two things are infinite,
 > the universe and human stupidity,
 > i am not totally shure about the universe, though...
->    - Albert Einstein
+>    – Albert Einstein
 ```
 
 
 > Only two things are infinite,
 > the universe and human stupidity,
 > i am not totally shure about the universe, though...
->    - Albert Einstein
+>    – Albert Einstein
 
 ### Code blocks
 ```markdown
@@ -110,4 +126,30 @@ or via reference to [a later defined url][massivedynamic], i we so desire.
 [massivedynamic]: https://massivedynamic.eu
 ```
 
-[massivedynamic]: https://massivedynamic.eu
+[massivedynamic]: https://massivedynamic.eu
+
+## Usage
+Simply construct an new `parkdown\Parkdown` object and pass the Markdown source code to it's constructor. The parsed `DOMDocument` or it's `HTML` output can then be retrieved through the `::html()` and `::tree()` member functions.
+
+**Example**
+
+```php
+	use parkdown\Parkdown;
+
+	$source = "
+		This is a **bold** word in a paragraph.
+	";
+
+	$parser = new Parkdown($source);
+	$tree   = $parser->tree();
+
+	print_r($tree);
+	echo $parser->html();
+```
+
+## Testing
+Unit tests can be run via `composer`:
+
+```
+	composer test
+```

composer.json

@@ -1,6 +1,7 @@
 {
     "name": "massivedynamic/parkdown",
     "type": "library",
+	"version": "v1.2.0",
     "license": "MIT",
     "autoload": {
         "psr-4": {
@@ -13,6 +14,9 @@
             "email": "miko@massivedynamic.eu"
         }
     ],
+	"require": {
+		"php" : ">=8.1"
+	},
     "require-dev": {
         "phpunit/phpunit": "^9"
     },

index.php

@@ -4,15 +4,24 @@ require __DIR__."/vendor/autoload.php";
 
 
 $source = file_get_contents(dirname(__FILE__)."/README.md");
-//$source = file_get_contents(dirname(__FILE__)."/tests/paragraph.md");
-//$source = file_get_contents(dirname(__FILE__)."/tests/list.md");
 
 echo "
 <style>
 	body {
+		padding: 4rem;
+		margin: 0;
 		font-family: sans-serif;
 	}
 
+	img {
+		max-width: 100%;
+	}
+
+	code {
+		word-break: break-word;
+		white-space: break-spaces;
+	}
+
 	table {
 		width: 100%;
 	}

src/Lexer.php

@@ -104,6 +104,14 @@ class Lexer {
 						$clearBuffer();
 						array_push($tokens, new Token(TokenType::COLON, $char));
 						break;
+					case '{':
+						$clearBuffer();
+						array_push($tokens, new Token(TokenType::LBRACE, $char));
+						break;
+					case '}':
+						$clearBuffer();
+						array_push($tokens, new Token(TokenType::RBRACE, $char));
+						break;
 					default:
 						$buffer .= $char;
 						break;

src/Parser.php

@@ -2,6 +2,7 @@
 
 namespace parkdown;
 
+use Attribute;
 use DOMDocument;
 use DOMElement;
 use DOMNode;
@@ -11,6 +12,11 @@ enum ListType {
 	case UNORDERED;
 }
 
+class Attributes {
+	public array   $classes = [];
+	public ?string $id      = null;
+}
+
 class Parser {
 	const MAGIC_CHAR = "*";
 
@@ -148,8 +154,8 @@ class Parser {
 	}
 
 	private function parseText($paragraph = false) : array {
-		$elms   = [];
-		$buffer = "";
+		$elms    = [];
+		$buffer  = "";
 		
 		$clearBuffer = function() use (&$elms, &$buffer) {
 			array_push($elms, $this->document->createTextNode($buffer));
@@ -164,7 +170,8 @@ class Parser {
 				TokenType::BACKTICK,
 				TokenType::ASTERISK,
 				TokenType::LBRACKET,
-				TokenType::BANG
+				TokenType::BANG,
+				TokenType::LBRACE
 			])) {
 				$this->consume()->data; // backslash
 				$buffer .= $this->consume()->data;
@@ -228,6 +235,41 @@ class Parser {
 				$clearBuffer();
 				array_push($elms, $elm);
 				continue;
+			} elseif ($this->current()->type === TokenType::LBRACE) {
+				$lbrace  = $this->consume();
+				assert($lbrace->type === TokenType::LBRACE, "expected left brace, got ".$lbrace->type->name);
+
+				$content = "";
+				while ($this->current()->type !== TokenType::EOF &&
+						$this->current()->type !== TokenType::EOL &&
+						$this->current()->type !== TokenType::RBRACE) {
+					$content .= $this->consume()->data;
+				}
+				$rbrace = $this->consume();
+				assert($rbrace->type === TokenType::RBRACE, "expected right brace, got ".$rbrace->type->name);
+
+				$attributes = array_map(function($element) {
+					return trim($element);
+				}, explode(',', $content));
+
+				$obj = new Attributes();
+
+				foreach($attributes as $attribute) {
+					if (!in_array($attribute[0], [".", "#"]))
+						continue;
+					switch ($attribute[0]) {
+						case ".":
+							array_push($obj->classes, substr($attribute, 1));
+							break;
+						case "#":
+							$obj->id = substr($attribute, 1);
+							break;
+						default:
+							continue 2;
+					}
+				}
+
+				array_push($elms, $obj);
 			} else
 				$buffer .= self::StripBackslashes($this->consume()->data);
 		}
@@ -268,6 +310,7 @@ class Parser {
 			// then we parse the node content
 			$elm = $this->document->createElement("li");
 			foreach ($this->parseText() as $node)
+			 	if ($node instanceof DOMNode)
 				$elm->appendChild($node);
 
 			// now we check, if the level of the next line is higher than the current level.
@@ -303,10 +346,17 @@ class Parser {
 	private function buildParagraph(array $elms) : void {
 		if (count($elms) < 1)
 			return;
-
 		$elm = $this->document->createElement("p");
 		$i   = 0;
 		foreach ($elms as $node) {
+			if ($node instanceof Attributes) {
+				if (count($node->classes) > 0)
+					$elm->setAttribute("class", join(" ", $node->classes));
+				if ($node->id)
+					$elm->setAttribute("id", $node->id);
+				
+				continue;
+			}
 			if ($node->nodeName === "#text" && trim($node->textContent) === "")
 				continue;
 			$elm->appendChild($node);
@@ -326,7 +376,8 @@ class Parser {
 		}
 		$elm = $this->document->createElement("h".$level);
 		foreach ($this->parseText() as $node)
-			$elm->appendChild($node);
+			if ($node instanceof DOMNode)
+				$elm->appendChild($node);
 		$this->document->appendChild($elm);
 	}
 
@@ -344,8 +395,10 @@ class Parser {
 		$lang = count($lang) > 0 ? trim($lang[0]->data) : null;
 
 		$container = $this->document->createElement("pre");
-		if ($lang)
+		if ($lang) {
 			$container->setAttribute("data-lang", $lang);
+			$container->setAttribute("class", "language-$lang");
+		}
 		
 		$buffer = "";
 		while (!($this->current()->type === TokenType::BACKTICK &&
@@ -360,6 +413,10 @@ class Parser {
 		}
 
 		$elm = $this->document->createElement("code", htmlspecialchars($buffer));
+		if ($lang) {
+			$elm->setAttribute("data-lang", $lang);
+			$elm->setAttribute("class", "language-$lang");
+		}
 		$container->appendChild($elm);
 		$this->document->appendChild($container);
 		$this->consume();
@@ -505,6 +562,10 @@ class Parser {
 		while ($this->current()->type !== TokenType::EOF) {
 			switch($this->current()->type) {
 				case TokenType::ASTERISK:
+					if ($this->next()->type === TokenType::ASTERISK) {
+						$this->buildParagraph($this->parseText(true));
+						break;
+					}
 					$list = $this->parseList();
 					$this->document->appendChild($list);
 					break;

src/Token.php

@@ -22,6 +22,8 @@ enum TokenType {
 	case PIPE     ;
 	case GT       ;
 	case TAB      ;
+	case LBRACE   ;
+	case RBRACE   ;
 }
 
 class Token {

tests/AnnotationsTest.php

@@ -0,0 +1,70 @@
+<?php declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+final class AnnotationsTest extends TestCase {
+	public function testAnnotationsDoNotBreakHeadings() : void {
+		$source = "
+# This is an H1 {.withAClass}
+## This is an H2 {.withAClass}
+### This is an H3 {.withAClass}
+#### This is an H4 {.withAClass}
+##### This is an H5 {.withAClass}
+		";
+		$target = "
+		<h1>This is an H1</h1>
+		<h2>This is an H2</h2>
+		<h3>This is an H3</h3>
+		<h4>This is an H4</h4>
+		<h5>This is an H5</h5>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+
+	public function testAnnotationsDoNotBreakLists() : void {
+		$source = "
+
+* this is a list
+* with annotations {#someID}
+
+1. this is an ordered list
+	1. with an annotation {.someClass}
+
+";
+		$target = "
+		<ul>
+			<li>this is a list</li>
+			<li>with annotations</li>
+		</ul>
+		<ol>
+			<li>
+				this is an ordered list
+				<ol>
+					<li>with an annotation</li>
+				</ol>
+			</li>
+		</ol>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+
+	public function testAnnotationsDoNotBreakCodeblocks() : void {
+		$source = "
+```
+		this is a code block
+``` {.someClass}
+";
+		$target = "
+		<pre>
+			<code>this is a code block</code>
+		</pre>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+}

tests/CodeBlocksTest.php

@@ -31,8 +31,8 @@ final class CodeBlocksTest extends TestCase {
 ```
 		";
 		$target = "
-<pre data-lang=\"php\">
-	<code>
+<pre data-lang=\"php\" class=\"language-php\">
+	<code data-lang=\"php\" class=\"language-php\">
 		public function testLanguageAnnotationParsesCorrectly() : bool {
 			return true;
 		}

tests/GenericBlocksTest.php

@@ -44,4 +44,20 @@ this is a paragraph
 		[$source, $result] = createTest($source, $target);
 		$this->assertEquals($source, $result);
 	}
+
+	public function testParagraphAnnotations() : void {
+		$source = "
+		
+this is an annotated paragraph {.classA, .classB}
+		
+		";
+		$target = "
+		<p class=\"classA classB\">
+			this is an annotated paragraph
+		</p>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
 }

tests/HeadingsTest.php

@@ -0,0 +1,65 @@
+<?php declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+
+final class HeadingsTest extends TestCase {
+	public function testH1ParsesCorrectly() : void {
+		$source = "
+# This is an H1
+		";
+		$target = "
+		<h1>This is an H1</h1>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+	
+	public function testH2ParsesCorrectly() : void {
+		$source = "
+## This is an H2
+		";
+		$target = "
+		<h2>This is an H2</h2>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+
+	public function testH3ParsesCorrectly() : void {
+		$source = "
+### This is an H3
+		";
+		$target = "
+		<h3>This is an H3</h3>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+
+	public function testH4ParsesCorrectly() : void {
+		$source = "
+#### This is an H4
+		";
+		$target = "
+		<h4>This is an H4</h4>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+
+	public function testH5ParsesCorrectly() : void {
+		$source = "
+##### This is an H5
+		";
+		$target = "
+		<h5>This is an H5</h5>
+		";
+
+		[$source, $result] = createTest($source, $target);
+		$this->assertEquals($source, $result);
+	}
+}