Avoid suggesting echo in documentation and examples

README.md

@@ -41,12 +41,12 @@ For example:
 namespace greetings;
 
 use Castor\Attribute\AsTask;
-use function Castor\run;
+use function Castor\io;
 
 #[AsTask()]
 function hello(): void
 {
-    run('echo "Hello from castor"');
+    io()->writeln('Hello from castor');
 }
 ```
 

doc/getting-started/arguments.md

@@ -6,14 +6,14 @@ the function will be used as arguments or options:
 ```php
 use Castor\Attribute\AsTask;
 
-use function Castor\run;
+use function Castor\io;
 
 #[AsTask()]
 function task(
     string $firstArg,
     string $secondArg
 ) {
-    run(['echo', $firstArg, $secondArg]);
+    io()->writeln($firstArg . ' ' . $secondArg);
 }
 ```
 
@@ -31,14 +31,14 @@ You can make an argument optional by giving it a default value:
 ```php
 use Castor\Attribute\AsTask;
 
-use function Castor\run;
+use function Castor\io;
 
 #[AsTask()]
 function task(
     string $firstArg,
-    string $default = 'default'
+    string $secondArg = 'default'
 ) {
-    run(['echo', $firstArg, $secondArg]);
+    io()->writeln($firstArg . ' ' . $secondArg);
 }
 ```
 
@@ -80,14 +80,14 @@ the `Castor\Attribute\AsArgument` attribute:
 use Castor\Attribute\AsArgument;
 use Castor\Attribute\AsTask;
 
-use function Castor\run;
+use function Castor\io;
 
 #[AsTask()]
 function command(
     #[AsArgument(name: 'foo', description: 'This is the foo argument')]
     string $arg = 'bar',
 ) {
-    run(['echo', $arg]);
+    io()->writeln($arg);
 }
 ```
 
@@ -108,14 +108,14 @@ If you prefer, you can force an argument to be an option by using the
 use Castor\Attribute\AsOption;
 use Castor\Attribute\AsTask;
 
-use function Castor\run;
+use function Castor\io;
 
 #[AsTask()]
 function command(
     #[AsOption(name: 'foo', description: 'This is the foo option')]
     string $arg = 'bar',
 ) {
-    run(['echo', $arg]);
+    io()->writeln($arg);
 }
 ```
 
@@ -139,7 +139,7 @@ function command(
     bool $force,
 ) {
     if ($force) {
-        echo "command has been forced\n";
+        io()->writeln('command has been forced');
     }
 }
 ```

doc/getting-started/basic-usage.md

@@ -16,20 +16,24 @@ namespace hello;
 
 use Castor\Attribute\AsTask;
 
+use function Castor\io;
+
 #[AsTask()]
 function castor(): void
 {
-    echo 'Hello castor';
+    io()->writeln('Hello castor');
 }
 
 namespace foo;
 
+use function Castor\io;
+
 use Castor\Attribute\AsTask;
 
 #[AsTask()]
 function bar(): void
 {
-    echo 'Foo bar';
+    io()->writeln('Foo bar');
 }
 ```
 
@@ -77,10 +81,12 @@ arguments: `name`, `namespace` and `description` to override the default values:
 ```php
 use Castor\Attribute\AsTask;
 
-#[AsTask(name: 'bar', namespace: 'foo', description: 'Echo foo bar')]
+use function Castor\io;
+
+#[AsTask(name: 'bar', namespace: 'foo', description: 'Output foo bar')]
 function a_very_long_function_name_that_is_very_painful_to_write(): void
 {
-    echo 'Foo bar';
+    io()->writeln('Foo bar');
 }
 ```
 

doc/getting-started/context.md

@@ -20,14 +20,15 @@ You can get the initial context thanks to the `context()` function:
 use Castor\Attribute\AsTask;
 
 use function Castor\context;
+use function Castor\io;
 use function Castor\run;
 
 #[AsTask()]
 function foo(): void
 {
     $context = context();
 
-    echo $context->currentDirectory; // will print the directory of the castor.php file
+    io()->writeln($context->currentDirectory); // will print the directory of the castor.php file
 
     $context = $context->withCurrentDirectory('/tmp'); // will create a new context where the current directory is /tmp
     run('pwd', context: $context); // will print "/tmp"
@@ -117,6 +118,7 @@ setting the `default` argument to `true` in the `AsContext` attribute:
 use Castor\Attribute\AsContext;
 use Castor\Context;
 
+use function Castor\io;
 use function Castor\run;
 
 #[AsContext(default: true, name: 'my_context')]
@@ -128,7 +130,7 @@ function create_default_context(): Context
 #[AsTask()]
 function foo(Context $context): void
 {
-    run(['echo', $context['foo']]); // will print bar even if you do not use the --context option
+    io()->writeln($context['foo']); // will print bar even if you do not use the --context option
     run('pwd'); // will print /tmp
 }
 ```

doc/getting-started/run.md

@@ -12,8 +12,8 @@ use function Castor\run;
 #[AsTask()]
 function foo(): void
 {
-    run('echo "bar"');
-    run(['echo', 'bar']);
+    run('my-script.sh');
+    run(['php', 'vendor/bin/phpunit', '--filter', 'MyTest']);
 }
 ```
 
@@ -35,8 +35,8 @@ use function Castor\run;
 #[AsTask()]
 function foo(): void
 {
-    $process = run('echo "bar"');
-    $process->isSuccessful(); // will return true
+    $process = run('my-script.sh');
+    $process->isSuccessful(); // will return true if the process exited with code 0.
 }
 ```
 
@@ -152,13 +152,14 @@ trims the output, then returns it:
 use Castor\Attribute\AsTask;
 
 use function Castor\capture;
+use function Castor\io;
 
 #[AsTask()]
 function whoami()
 {
     $whoami = capture('whoami');
 
-    echo "Hello: $whoami\n";
+    io()->writeln("Hello: $whoami");
 }
 ```
 
@@ -200,7 +201,7 @@ use function Castor\run;
 #[AsTask()]
 function foo(): void
 {
-    run('echo "bar"', timeout: 120);
+    run('my-script.sh', timeout: 120);
 }
 ```
 

doc/going-further/helpers/cache.md

@@ -9,19 +9,22 @@ use Castor\Attribute\AsTask;
 use Psr\Cache\CacheItemInterface;
 
 use function Castor\cache;
+use function Castor\io;
 
 #[AsTask()]
 function foo()
 {
-    echo cache('a-key', expansive_call(...));
+    $result = cache('a-key', expansive_call(...));
 
     // Or if you want to set a TTL
 
-    echo cache('another-key', function (CacheItemInterface $item) => {
+    $result = cache('another-key', function (CacheItemInterface $item) => {
         $item->expiresAfter(3600);
 
         return expansive_call();
     });
+
+    io()->writeln($result);
 }
 ```
 
@@ -43,6 +46,7 @@ If you need to have a full control on the cache, you can access the
 use Castor\Attribute\AsTask;
 
 use function Castor\get_cache;
+use function Castor\io;
 
 #[AsTask()]
 function foo()
@@ -56,6 +60,6 @@ function foo()
       $cache->save($item);
     }
 
-    echo $item->get();
+    io()->writeln($item->get());
 }
 ```

doc/going-further/helpers/filesystem.md

@@ -14,23 +14,24 @@ use Castor\Attribute\AsTask;
 use Symfony\Component\Filesystem\Path;
 
 use function Castor\fs;
+use function Castor\io;
 
 #[AsTask()]
 function foo()
 {
     $dir = '/tmp/foo';
 
-    echo $dir, ' directory exist: ', fs()->exists($dir) ? 'yes' : 'no', \PHP_EOL;
+    io()->writeln($dir . ' directory exist: ' . (fs()->exists($dir) ? 'yes' : 'no'));
 
     fs()->mkdir($dir);
     fs()->touch($dir . '/bar.md');
 
-    echo $dir, ' is an absolute path: ', Path::isAbsolute($dir) ? 'yes' : 'no', \PHP_EOL;
-    echo '../ is an absolute path: ', Path::isAbsolute('../') ? 'yes' : 'no', \PHP_EOL;
+    io()->writeln($dir, ' is an absolute path: ' . (Path::isAbsolute($dir) ? 'yes' : 'no'));
+    io()->writeln('../ is an absolute path: ' . (Path::isAbsolute('../') ? 'yes' : 'no'));
 
     fs()->remove($dir);
 
-    echo 'Absolute path: ', Path::makeAbsolute('../', $dir), \PHP_EOL;
+    io()->writeln('Absolute path: ' . Path::makeAbsolute('../', $dir));
 }
 ```
 
@@ -50,11 +51,12 @@ intuitive fluent interface. It returns an instance of
 use Castor\Attribute\AsTask;
 
 use function Castor\finder;
+use function Castor\io;
 
 #[AsTask()]
 function foo()
 {
-    echo 'Number of PHP files: ', finder()->name('*.php')->in(__DIR__)->count(), \PHP_EOL;
+    io()->writeln('Number of PHP files: ' . finder()->name('*.php')->in(__DIR__)->count());
 }
 ```
 

doc/going-further/helpers/fingerprint.md

@@ -13,14 +13,14 @@ the given fingerprint has changed.
 ```php
 use Castor\Attribute\AsTask;
 use function Castor\fingerprint;
-use function Castor\run;
+use function Castor\io;
 
 #[AsTask(description: 'Execute a callback only if the fingerprint has changed')]
 function task_with_a_fingerprint(): void
 {
     fingerprint(
         callback: function () {
-            run('echo "Cool, no fingerprint! Executing..."');
+            io()->writeln('Cool, no fingerprint! Executing...');
         },
         fingerprint: "my fingerprint",
     );
@@ -69,7 +69,7 @@ function task_with_a_fingerprint(): void
 {
     fingerprint(
         callback: function () {
-            run('echo "Executing the callback because my-file.json has changed."');
+            io()->writeln('Executing the callback because my-file.json has changed.');
         },
         fingerprint: hasher()->writeFile('my-file.json', FileHashStrategy::Content)->finish(),
     );
@@ -94,7 +94,7 @@ use function Castor\hasher;
 function task_with_some_fingerprint(): void
 {
     if (!fingerprint_exists(my_fingerprint_check())) {
-        run('echo "Executing some code because fingerprint has changed."');
+        io()->writeln('Executing some code because fingerprint has changed.');
         fingerprint_save(my_fingerprint_check());
     }
 }

doc/going-further/helpers/http-request.md

@@ -9,12 +9,13 @@ request and returns an instance of
 ```php
 use Castor\Attribute\AsTask;
 
+use function Castor\io;
 use function Castor\request;
 
 #[AsTask()]
 function foo()
 {
-    echo request('GET', 'https://example.org')->getContent(), \PHP_EOL;
+    io()->writeln(request('GET', 'https://example.org')->getContent());
 }
 ```
 

doc/going-further/helpers/parallel.md

@@ -8,6 +8,7 @@ so you do not have to wait for a function to finish before starting another one:
 ```php
 use Castor\Attribute\AsTask;
 
+use function Castor\io;
 use function Castor\parallel;
 
 #[AsTask()]
@@ -22,8 +23,8 @@ function foo(): void
         }
     );
 
-    echo $foo->getOutput(); // will print foo
-    echo $bar->getOutput(); // will print bar
+    io()->writeln($foo->getOutput()); // will print foo
+    io()->writeln($bar->getOutput()); // will print bar
 }
 ```