add blank-line margins around auto-split lines with improved margin c…

…ontrols

also fixes issue where final else gets lost after `else if`

CHANGELOG.md

@@ -1,13 +1,35 @@
 # Change Log
 
+## NEXT
+
+- Make line control more explicit.
+
+    - Remove Printable::$hasAttribute, $hasComment, $isFirst, hasAttribute(), hasComment(), and isFirst().
+
+    - Remove Styler::$atFirstInBody, $hadComment, $hadAttributem, forceSingleNewline(), maybeDoubleNewline(), and rtrim().
+
+    - The Line object now tracks if a margin above or below is advised for addition, and if a margin above or below is allowed.
+
+    - The Styler methods now specify margin additions and allowances on the current Line object.
+
+- Protect various Styler methods that were mistakenly public.
+
+- Add method Styler::blankLine() to create new Line instances.
+
+- Rename Line::newline() to Line::blankLine().
+
+- Styler::newline() now applies one line of margin above and below auto-split lines, subject to margin allowances; updated tests to reflect this expectation.
+
+- Fix issue where final `else` gets lost after `else if` (refs #4).
+
 ## 0.14.0
 
 - Can now `apply` stying to arbitrary paths by passing file and directory
   names at the command line.
 
 ## 0.13.0
 
-- Force visibility  on class members
+- Force visibility on class members
 
 - Rename Property to ClassProperty
 

README.md

@@ -32,7 +32,7 @@ PHP-Styler is **not appropriate** for PHP-based templates, as it does not use th
 
 PHP-Styler uses a 3-pass system to reformat and style PHP code:
 
-1. _PHPParser\Parser_ converts the code to an abstract syntax tree of _Node_ elements.
+1. _PHPParser\Parser_ converts the code to an abstract syntax tree of _Node_ elements, applying transformations from _PHPStyler\Visitor_ along the way.
 2. _PHPStyler\Printer_ flattens the _Node_ tree into a list of _Printable_ elements.
 3. _PHPStyler\Styler_ converts each _Printable_ back into text using a series of _Line_ objects; it applies horizontal spacing, vertical spacing, and line-splitting rules as it goes.
 
@@ -235,6 +235,8 @@ At first, PHP-Styler builds each statement/instruction as a single line. If that
 
 If the first rule does not make the line short enough, the second rule is applied in addition, then the third, and so on.
 
+Finally, PHP-Styler will add one blank line of margin around each line that has been automatically split.
+
 The line splitting logic attempts to be idiomatic; that is, PHP-Styler tries to take common line-splitting idioms into account, rather than making weighted calculations of elements. Reference projects were:
 
 - cakephp/database

composer.json

@@ -28,7 +28,7 @@
     },
     "require": {
         "php": "^8.1 | ^8.2 | ^8.3",
-        "nikic/php-parser": "^4.17",
+        "nikic/php-parser": "^4.19",
         "pmjones/auto-shell": "^1.0"
     },
     "require-dev": {
@@ -41,7 +41,7 @@
         "bin/php-styler"
     ],
     "scripts": {
-        "analyze": "./vendor/bin/phpstan",
+        "analyze": "./vendor/bin/phpstan --memory-limit=256M",
         "check": "composer test && composer analyze && composer cs-check",
         "cs-check": "php bin/php-styler check -c php-styler.php",
         "cs-fix": "php bin/php-styler apply -c php-styler.php",

src/Command/Preview.php

@@ -21,12 +21,14 @@ public function __invoke(
     {
         $configFile = $options->configFile ?? $this->findConfigFile();
         $config = $this->loadConfigFile($configFile);
+
         $service = new Service(
             $config->styler,
             $options->debugParser ?? false,
             $options->debugPrinter ?? false,
             $options->debugStyler ?? false,
         );
+
         echo $service((string) file_get_contents($sourceFile));
         return 0;
     }

src/Line.php

@@ -49,6 +49,14 @@ class Line implements ArrayAccess
      */
     protected array $lines = [];
 
+    protected bool $addMarginAbove = false;
+
+    protected bool $addMarginBelow = false;
+
+    protected bool $allowMarginAbove = true;
+
+    protected bool $allowMarginBelow = true;
+
     public function __construct(
         protected string $eol,
         protected int $indentNum,
@@ -92,6 +100,69 @@ public function outdent() : void
         $this->indentNum --;
     }
 
+    /**
+     * This is advisory, and applies only when allowed.
+     */
+    public function addMarginAbove() : void
+    {
+        $this->addMarginAbove = true;
+    }
+
+    public function hasMarginAbove() : bool
+    {
+        return $this->addMarginAbove;
+    }
+
+    /**
+     * This is advisory, and applies only when allowed.
+     */
+    public function addMarginBelow() : void
+    {
+        $this->addMarginBelow = true;
+    }
+
+    public function hasMarginBelow() : bool
+    {
+        return $this->addMarginBelow;
+    }
+
+    public function allowMarginAbove(bool $allowMarginAbove) : void
+    {
+        $this->allowMarginAbove = $allowMarginAbove;
+    }
+
+    public function marginAllowedAbove() : bool
+    {
+        return $this->allowMarginAbove;
+    }
+
+    public function allowMarginBelow(bool $allowMarginBelow) : void
+    {
+        $this->allowMarginBelow = $allowMarginBelow;
+    }
+
+    public function marginAllowedBelow() : bool
+    {
+        return $this->allowMarginBelow;
+    }
+
+    public function isBlank() : bool
+    {
+        return empty($this->parts);
+    }
+
+    public function autoAddMargins() : void
+    {
+        $tmp = clone $this;
+        $output = '';
+        $tmp->append($output);
+
+        if ($tmp->lines || strpos(trim($output), $this->eol)) {
+            $this->addMarginAbove();
+            $this->addMarginBelow();
+        }
+    }
+
     public function append(string &$output) : void
     {
         list($level, $rule) = $this->listLevelRule();
@@ -107,7 +178,7 @@ public function append(string &$output) : void
     protected function splitLines(string &$output, int $level, string $rule) : void
     {
         $this->lines = [];
-        $this->line = $this->newline();
+        $this->line = $this->blankLine();
 
         foreach ($this->parts as $part) {
             if (
@@ -131,7 +202,7 @@ protected function splitLines(string &$output, int $level, string $rule) : void
         }
     }
 
-    protected function newline() : Line
+    protected function blankLine() : Line
     {
         return new Line(
             $this->eol,
@@ -145,14 +216,14 @@ protected function newline() : Line
     protected function incrSplit(Split $part) : void
     {
         $this->lines[] = $this->line;
-        $this->line = $this->newline();
+        $this->line = $this->blankLine();
         $this->line->indentNum ++;
     }
 
     protected function condenseSplit(Split $part) : void
     {
         $this->lines[] = $this->line;
-        $this->line = $this->newline();
+        $this->line = $this->blankLine();
         $this->line->indentNum ++;
         $this->line[] = new W\Condense(when: fn () => true);
     }
@@ -164,7 +235,7 @@ protected function sameSplit(Split $part) : void
         }
 
         $this->lines[] = $this->line;
-        $this->line = $this->newline();
+        $this->line = $this->blankLine();
     }
 
     protected function fitsOnSingleLine(string &$output) : bool
@@ -177,6 +248,7 @@ protected function fitsOnSingleLine(string &$output) : bool
             if ($part instanceof Whitespace) {
                 $method = lcfirst(substr((string) strrchr(get_class($part), '\\'), 1))
                     . 'Whitespace';
+
                 $this->{$method}($part, $output);
             } elseif (is_string($part)) {
                 $this->append .= $part;

src/Printable/Printable.php

@@ -5,34 +5,8 @@
 
 abstract class Printable
 {
-    protected bool $hasAttribute = false;
-
-    protected bool $hasComment = false;
-
     protected bool $isExpansive = false;
 
-    protected bool $isFirst = false;
-
-    public function hasAttribute(bool $hasAttribute = null) : ?bool
-    {
-        if ($hasAttribute === null) {
-            return $this->hasAttribute;
-        }
-
-        $this->hasAttribute = $hasAttribute;
-        return null;
-    }
-
-    public function hasComment(bool $hasComment = null) : ?bool
-    {
-        if ($hasComment === null) {
-            return $this->hasComment;
-        }
-
-        $this->hasComment = $hasComment;
-        return null;
-    }
-
     public function isExpansive(bool $isExpansive = null) : ?bool
     {
         if ($isExpansive === null) {
@@ -42,14 +16,4 @@ public function isExpansive(bool $isExpansive = null) : ?bool
         $this->isExpansive = $isExpansive;
         return null;
     }
-
-    public function isFirst(bool $isFirst = null) : ?bool
-    {
-        if ($isFirst === null) {
-            return $this->isFirst;
-        }
-
-        $this->isFirst = $isFirst;
-        return null;
-    }
 }