documentation for shell list

Author: Christian Benthake

src/Collection/ShellList.php

@@ -11,6 +11,8 @@
 final class ShellList extends AbstractCollection
 {
     /**
+     * Returns something like: || echo "hello world"
+     *
      * @param string|ShellInterface $command
      * @return $this
      * @throws ShellBuilderException
@@ -23,6 +25,8 @@ public static function addOr($command): self
     }
 
     /**
+     * Returns something like: && echo "hello world"
+     *
      * @param string|ShellInterface $command
      * @return $this
      * @throws ShellBuilderException
@@ -35,6 +39,8 @@ public static function addAnd($command): self
     }
 
     /**
+     * Returns something like: ; echo "hello world"
+     *
      * @param string|ShellInterface $command
      * @return $this
      * @throws ShellBuilderException
@@ -45,4 +51,18 @@ public static function add($command): self
         $list->tuple = $list->toTuple($command, ControlOperator::COMMAND_DELIMITER);
         return $list;
     }
+
+    /**
+     * Returns something like: & echo "hello world"
+     *
+     * @param string|ShellInterface $command
+     * @return static
+     * @throws ShellBuilderException
+     */
+    public static function async($command): self
+    {
+        $list = new self();
+        $list->tuple = $list->toTuple($command, ControlOperator::BASH_AMPERSAND);
+        return $list;
+    }
 }

src/ShellBuilder.php

@@ -61,9 +61,6 @@ public function add($command): self
      */
     public function and($command): self
     {
-        if (is_string($command)) {
-            $command = $this->createCommand($command);
-        }
         $this->commandList[] = ShellList::addAnd($this->parseCommand($command));
         return $this;
     }
@@ -75,23 +72,28 @@ public function and($command): self
      */
     public function or($command): self
     {
-        if (is_string($command)) {
-            $command = $this->createCommand($command);
-        }
         $this->commandList[] = ShellList::addOr($this->parseCommand($command));
         return $this;
     }
 
+    /**
+     * @param string|ShellInterface $command
+     * @return $this
+     * @throws ShellBuilderException
+     */
+    public function async($command): self
+    {
+        $this->commandList[] = ShellList::async($this->parseCommand($command));
+        return $this;
+    }
+
     /**
      * @param string|ShellInterface $command
      * @return $this
      * @throws ShellBuilderException
      */
     public function pipe($command): self
     {
-        if (is_string($command)) {
-            $command = $this->createCommand($command);
-        }
         $this->commandList[] = Pipeline::pipe($this->parseCommand($command));
         return $this;
     }
@@ -103,9 +105,6 @@ public function pipe($command): self
      */
     public function pipeWithForward($command): self
     {
-        if (is_string($command)) {
-            $command = $this->createCommand($command);
-        }
         $this->commandList[] = Pipeline::pipeErrorForward($this->parseCommand($command));
         return $this;
     }

src/ShellCommand.php

@@ -27,6 +27,8 @@ final class ShellCommand implements ShellInterface
     private $isCommandSubstitution = false;
     /** @var ShellBuilder|null */
     private $parentBuilder;
+    /** @var bool */
+    private $invertOutput = false;
 
     public function __construct(string $name, ShellBuilder $builder = null)
     {
@@ -48,6 +50,12 @@ public function toggleCommandSubstitution(): self
         return $this;
     }
 
+    public function invert(bool $invert = true): self
+    {
+        $this->invertOutput = $invert;
+        return $this;
+    }
+
     /**
      * @param string $option
      * @param ShellInterface|string|mixed $value
@@ -183,7 +191,8 @@ public function __toString(): string
     {
         /** @psalm-suppress ImplicitToStringCast */
         $result = (sprintf(
-            '%s%s%s',
+            '%s%s%s%s',
+            $this->invertOutput ? '! ' : '',
             empty($this->environmentVariables) ? '' : $this->environmentVariablesToString(),
             $this->executable,
             empty($this->arguments) ? '' : ' ' . $this->argumentsToString()

tests/ShellBuilderTest.php

@@ -221,6 +221,14 @@ public function testAsyncCommandBuilder(): void
         $this->assertEquals("coproc echo 'hello'", (string)$builder);
     }
 
+    public function testAsyncListCommandBuilder(): void
+    {
+        $builder = new ShellBuilder();
+        $builder->createCommand('echo')->addArgument('hello')->addToBuilder()
+            ->async('ls');
+        $this->assertEquals("echo 'hello' & ls", (string)$builder);
+    }
+
     public function testRedirectToAppend(): void
     {
         $builder = new ShellBuilder();

tests/ShellCommandTest.php

@@ -47,6 +47,13 @@ public function testShellCommandWithCommandSubstitution(): void
         $this->assertEquals("ls -ld $(date +%B).txt", (string)$command);
     }
 
+    public function testShellCommandWithInvertedOutput(): void
+    {
+        $command = new ShellCommand('echo');
+        $command->invert()->addShortOption('e', 'hello world');
+        $this->assertEquals('! echo -e \'hello world\'', (string)$command);
+    }
+
     public function testEscapeOptionWithAssignOperator(): void
     {
         $command = (string)(new ShellCommand('ls'))->addOption('color', 'true', true, true);