Merge pull request #19 from alexandresalome/comments

Comments

README.md

@@ -11,5 +11,5 @@ PHP Graphviz
 Graphviz's generation for PHP.
 
 * [Documentation](https://alexandresalome.github.io/graphviz/)
-* [Changelog](CHANGELOG.md)
-* [Contributors](CONTRIBUTORS.md)
+* [Changelog](docs/changelog.md)
+* [Contributors](docs/contributors.md)

composer.json

@@ -34,6 +34,7 @@
     "phpunit/phpunit": "^9.5",
     "symfony/process": "^5.4|^6.1",
     "symfony/finder": "^5.4|^6.1",
-    "symfony/var-dumper": "^5.4|^6.1"
+    "symfony/var-dumper": "^5.4|^6.1",
+    "phpstan/phpstan-phpunit": "^1.2"
   }
 }

CHANGELOG.md → docs/changelog.md

@@ -1,6 +1,13 @@
 CHANGELOG
 =========
 
+2.1.0 (In development)
+----------------------
+
+* [feature] Add a ``commentLine`` method on graph objects
+* [feature] Add a ``commentBlock`` method on graph objects
+* [bug] Fix method parameters typing for edges and attributes
+
 2.0.0 (23/10/2022)
 ------------------
 

docs/usage/comment.md

@@ -0,0 +1,114 @@
+---
+title: Add comments
+---
+
+Adding comments
+===============
+
+<p style="padding: .2rem .5rem; border: 1px solid #8888ff; background-color: #ddeeff; color: #0033aa; font-weight: bold;">
+    Available from the version 2.1
+</p>
+
+Add comments into the graph
+---------------------------
+
+### Single line comments
+
+You can add a comment inside your graph by using the method ``commentLine``:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentLine('Empty graph');
+echo $graph->render();
+
+# digraph G {
+#     // Empty graph
+# }
+```
+
+Note that if you pass multiple lines to this method, it will add multiple lines:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentLine("Line 1\nLine 2");
+echo $graph->render();
+
+# digraph G {
+#     // Line 1
+#     // Line 2
+# }
+```
+
+You can also remove the initial space prefix by passing ``false`` as a second
+argument:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentLine('-- ASCII MASTER --//', false);
+echo $graph->render();
+
+# digraph G {
+#     //-- ASCII MASTER --//
+# }
+```
+
+And for C++ style arguments (``#`` instead of ``//``), pass ``true`` as a third
+argument:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentLine('C++ style', true, false);
+echo $graph->render();
+
+# digraph G {
+#     # C++ style
+# }
+```
+
+### Block comments
+
+You can add block comments by using the ``commentBlock`` function:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentBlock('My block comment');
+echo $graph->render();
+
+# digraph G {
+#     /*
+#      * My block comment
+#      */
+# }
+```
+
+Multiple lines is also supported:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentBlock("My block comment\non multiple lines");
+echo $graph->render();
+
+# digraph G {
+#     /*
+#      * My block comment
+#      * on multiple lines
+#      */
+# }
+```
+
+
+
+You can disable new lines and spacing and new line indent by providing ``false``
+as a second  argument:
+
+```php
+$graph = new Graphviz\Digraph();
+$graph->commentBlock("** ASCII fan\nNew line\n**", false);
+echo $graph->render();
+
+# digraph G {
+#     /*** ASCII fan
+# New line\n
+# ***/
+# }
+```

mkdocs.yml

@@ -14,10 +14,14 @@ nav:
           - usage/attributes.md
           - usage/nodes.md
           - usage/edges.md
+          - usage/comment.md
           - usage/rendering.md
     - Graphviz:
           - graphviz/subgraph.md
     - Examples:
           - examples/basic.md
           - examples/subgraph.md
           - examples/table.md
+    - About:
+          - changelog.md
+          - contributors.md

phpstan.neon

@@ -1,8 +1,10 @@
 parameters:
-    level: 6
+    level: 7
     paths:
         - src
         - src_dev
         - tests
     bootstrapFiles:
         - vendor/autoload.php
+includes:
+    - vendor/phpstan/phpstan-phpunit/extension.neon

src/AbstractGraph.php

@@ -131,10 +131,10 @@ public function set(string $name, string|RawText $value): self
     /**
      * Define attributes for node/edge/graph.
      *
-     * @param string                                     $name       Name of type
-     * @param array<string, string|RawText>|AttributeBag $attributes Attributes of the type
+     * @param string                        $name       Name of type
+     * @param array<string, string|RawText> $attributes Attributes of the type
      */
-    public function attr(string $name, array|AttributeBag $attributes): self
+    public function attr(string $name, array $attributes): self
     {
         $this->instructions[] = new AttributeSet($name, $attributes);
 
@@ -154,12 +154,12 @@ public function subgraph(string $id): Subgraph
     /**
      * Created a new node on graph.
      *
-     * @param string                                     $id         Identifier of node
-     * @param array<string, string|RawText>|AttributeBag $attributes Attributes to set on node
+     * @param string                        $id         Identifier of node
+     * @param array<string, string|RawText> $attributes Attributes to set on node
      *
      * @return self Fluid-interface
      */
-    public function node(string $id, array|AttributeBag $attributes = []): self
+    public function node(string $id, array $attributes = []): self
     {
         $this->instructions[] = new Node($this, $id, $attributes);
 
@@ -191,40 +191,94 @@ public function nodes(array $nodes): self
     /**
      * Created a new node on graph.
      *
-     * @param string                                     $id         Identifier of node
-     * @param array<string, string|RawText>|AttributeBag $attributes Attributes to set on node
+     * @param string                        $id         Identifier of node
+     * @param array<string, string|RawText> $attributes Attributes to set on node
      */
-    public function beginNode(string $id, array|AttributeBag $attributes = []): Node
+    public function beginNode(string $id, array $attributes = []): Node
     {
         return $this->instructions[] = new Node($this, $id, $attributes);
     }
 
     /**
      * Created a new edge on graph.
      *
-     * @param array<string|array<string>>                $list       List of edges
-     * @param array<string, string|RawText>|AttributeBag $attributes Attributes to set on edge
+     * @param array<string|array<string>>   $list       List of edges
+     * @param array<string, string|RawText> $attributes Attributes to set on edge
      *
      * @return self Fluid-interface
      */
-    public function edge(array $list, array|AttributeBag $attributes = []): self
+    public function edge(array $list, array $attributes = []): self
     {
         $this->beginEdge($list, $attributes);
 
         return $this;
     }
 
     /**
-     * Created a new edge on graph.
+     * Creates a new edge on graph.
      *
-     * @param array<string|array<string>>               $list       List of edges
-     * @param array<string,string|RawText>|AttributeBag $attributes Attributes to set on edge
+     * @param array<string|array<string>>  $list       List of edges
+     * @param array<string,string|RawText> $attributes Attributes to set on edge
      */
-    public function beginEdge(array $list, array|AttributeBag $attributes = []): Edge
+    public function beginEdge(array $list, array $attributes = []): Edge
     {
         return $this->instructions[] = new Edge($this, $list, $attributes);
     }
 
+    /**
+     * Adds a new comment line to the graph (starting with //, or #).
+     *
+     * If you pass a multiline string to this method, it will append multiple
+     * comment lines.
+     *
+     * @param string $comment   The comment to add
+     * @param bool   $withSpace Adds a space at the beginning of the comment
+     * @param bool   $cppStyle  Indicates if it's a classic (//) or C++ style (#)
+     *
+     * @return $this Fluid interface
+     */
+    public function commentLine(string $comment, bool $withSpace = true, bool $cppStyle = false): self
+    {
+        $space = $withSpace ? ' ' : '';
+        $prefix = $cppStyle ? '#' : '//';
+        foreach (explode("\n", $comment) as $line) {
+            $this->instructions[] = new Comment($prefix.$space.$line);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Adds a new comment block to the graph (starting with /*).
+     *
+     * If you pass a multiline string to this method, it will append multiple
+     * comment lines.
+     *
+     * @param string $comment   The comment to add
+     * @param bool   $withSpace Adds a space at the beginning of the comment
+     *
+     * @return $this Fluid interface
+     */
+    public function commentBlock(string $comment, bool $withSpace = true): self
+    {
+        $lines = explode("\n", $comment);
+        if ($withSpace) {
+            $lines = array_merge(
+                ['/*'],
+                array_map(fn ($line) => ' * '.$line, $lines),
+                [' */'],
+            );
+        } else {
+            $lines[0] = '/*'.$lines[0];
+            $last = count($lines) - 1;
+            $lines[$last] .= '*/';
+        }
+
+        $this->instructions[] = new Comment(implode("\n", $lines), $withSpace);
+
+        return $this;
+    }
+
     /**
      * Fluid-interface to access parent.
      */

src/Comment.php

@@ -0,0 +1,46 @@
+<?php
+/*
+ * This file is part of PHP Graphviz.
+ * (c) Alexandre Salomé <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Graphviz;
+
+/**
+ * Comment.
+ *
+ * @author Alexandre Salomé <[email protected]>
+ */
+class Comment implements InstructionInterface
+{
+    /** @var string Content of the comment */
+    protected string $content;
+
+    /** @var bool Indent the comment on rendering */
+    protected bool $indented;
+
+    /**
+     * Creates a new comment.
+     *
+     * @param string $content  Comment content, with delimiters
+     * @param bool   $indented Indicates if the content must be rendered indented
+     */
+    public function __construct(string $content, bool $indented = true)
+    {
+        $this->content = $content;
+        $this->indented = $indented;
+    }
+
+    public function getContent(): string
+    {
+        return $this->content;
+    }
+
+    public function isIndented(): bool
+    {
+        return $this->indented;
+    }
+}

src/Edge.php

@@ -24,7 +24,7 @@ class Edge implements InstructionInterface
     /**
      * List of element identifiers.
      *
-     * @var string[]
+     * @var array<string|array<string>>
      */
     protected array $list;
 
@@ -36,9 +36,9 @@ class Edge implements InstructionInterface
     /**
      * Creates an edge.
      *
-     * @param string[]                      $list       List of edges
-     * @param array<string, string|RawText> $attributes Associative array of attributes
      * @param AbstractGraph                 $parent     Parent instruction
+     * @param array<string|array<string>>   $list       List of edges
+     * @param array<string, string|RawText> $attributes Associative array of attributes
      */
     public function __construct(AbstractGraph $parent, array $list, array $attributes = [])
     {
@@ -50,7 +50,7 @@ public function __construct(AbstractGraph $parent, array $list, array $attribute
     /**
      * Returns list of elements composing the edge.
      *
-     * @return string[]
+     * @return array<string|array<string>>
      */
     public function getPath(): array
     {