Document RawInputInterface for accessing raw arguments/options and unparsing

Author: lacatoire

console/input.rst

@@ -825,6 +825,58 @@ command without having to worry about the number of arguments or options::
         // ...
     }
 
+Accessing Raw Arguments and Options
+-----------------------------------
+
+While ``getRawTokens()`` returns the unparsed CLI tokens as strings, sometimes
+you need access to the *parsed* arguments and options without default values
+merged in. The :class:`Symfony\\Component\\Console\\Input\\RawInputInterface`
+provides methods for this::
+
+    use Symfony\Component\Console\Input\RawInputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
+
+    public function __invoke(RawInputInterface $input, OutputInterface $output): int
+    {
+        // returns only arguments explicitly passed by the user (no defaults)
+        $rawArguments = $input->getRawArguments();
+
+        // returns only options explicitly passed by the user (no defaults)
+        $rawOptions = $input->getRawOptions();
+
+        // ...
+    }
+
+The ``unparse()`` method converts parsed options back to their CLI string
+representation (e.g. ``['--format=json', '--verbose']``), which is useful when
+forwarding options to a child process::
+
+    use Symfony\Component\Console\Input\RawInputInterface;
+    use Symfony\Component\Console\Output\OutputInterface;
+    use Symfony\Component\Process\Process;
+
+    public function __invoke(RawInputInterface $input, OutputInterface $output): int
+    {
+        $process = new Process([
+            PHP_BINARY, 'bin/console', 'app:child-command',
+            ...$input->getRawArguments(),
+            ...$input->unparse(),
+        ]);
+        $process->mustRun();
+
+        // ...
+    }
+
+You can also pass an array of option names to ``unparse()`` to only include
+specific options::
+
+    // only include --format and --verbose in the unparsed output
+    $unparsed = $input->unparse(['format', 'verbose']);
+
+.. versionadded:: 8.1
+
+    The ``RawInputInterface`` was introduced in Symfony 8.1.
+
 .. _console-input-completion:
 
 Adding Argument/Option Value Completion