Debian Codegraph @

vendor/symfony/console/Input/InputArgument.php

raw
1 <?php
2
3 /*
4 * This file is part of the Symfony package.
5 *
6 * (c) Fabien Potencier <[email protected]>
7 *
8 * For the full copyright and license information, please view the LICENSE
9 * file that was distributed with this source code.
10 */
11
12 namespace Symfony\Component\Console\Input;
13
14 use Symfony\Component\Console\Command\Command;
15 use Symfony\Component\Console\Completion\CompletionInput;
16 use Symfony\Component\Console\Completion\CompletionSuggestions;
17 use Symfony\Component\Console\Completion\Suggestion;
18 use Symfony\Component\Console\Exception\InvalidArgumentException;
19 use Symfony\Component\Console\Exception\LogicException;
20
21 /**
22 * Represents a command line argument.
23 *
24 * @author Fabien Potencier <[email protected]>
25 */
26 class InputArgument
27 {
28 /**
29 * Providing an argument is required (e.g. just 'app:foo' is not allowed).
30 */
31 public const REQUIRED = 1;
32
33 /**
34 * Providing an argument is optional (e.g. 'app:foo' and 'app:foo bar' are both allowed). This is the default behavior of arguments.
35 */
36 public const OPTIONAL = 2;
37
38 /**
39 * The argument accepts multiple values and turn them into an array (e.g. 'app:foo bar baz' will result in value ['bar', 'baz']).
40 */
41 public const IS_ARRAY = 4;
42
43 private int $mode;
44 private string|int|bool|array|float|null $default;
45
46 /**
47 * @param string $name The argument name
48 * @param int-mask-of<InputArgument::*>|null $mode The argument mode: a bit mask of self::REQUIRED, self::OPTIONAL and self::IS_ARRAY
49 * @param string $description A description text
50 * @param string|bool|int|float|array|null $default The default value (for self::OPTIONAL mode only)
51 * @param array|\Closure(CompletionInput,CompletionSuggestions):list<string|Suggestion> $suggestedValues The values used for input completion
52 *
53 * @throws InvalidArgumentException When argument mode is not valid
54 */
55 public function __construct(
56 private string $name,
57 ?int $mode = null,
58 private string $description = '',
59 string|bool|int|float|array|null $default = null,
60 private \Closure|array $suggestedValues = [],
61 ) {
62 if (null === $mode) {
63 $mode = self::OPTIONAL;
64 } elseif ($mode >= (self::IS_ARRAY << 1) || $mode < 1) {
65 throw new InvalidArgumentException(\sprintf('Argument mode "%s" is not valid.', $mode));
66 }
67
68 $this->mode = $mode;
69
70 $this->setDefault($default);
71 }
72
73 /**
74 * Returns the argument name.
75 */
76 public function getName(): string
77 {
78 return $this->name;
79 }
80
81 /**
82 * Returns true if the argument is required.
83 *
84 * @return bool true if parameter mode is self::REQUIRED, false otherwise
85 */
86 public function isRequired(): bool
87 {
88 return self::REQUIRED === (self::REQUIRED & $this->mode);
89 }
90
91 /**
92 * Returns true if the argument can take multiple values.
93 *
94 * @return bool true if mode is self::IS_ARRAY, false otherwise
95 */
96 public function isArray(): bool
97 {
98 return self::IS_ARRAY === (self::IS_ARRAY & $this->mode);
99 }
100
101 /**
102 * Sets the default value.
103 */
104 public function setDefault(string|bool|int|float|array|null $default): void
105 {
106 if ($this->isRequired() && null !== $default) {
107 throw new LogicException('Cannot set a default value except for InputArgument::OPTIONAL mode.');
108 }
109
110 if ($this->isArray()) {
111 if (null === $default) {
112 $default = [];
113 } elseif (!\is_array($default)) {
114 throw new LogicException('A default value for an array argument must be an array.');
115 }
116 }
117
118 $this->default = $default;
119 }
120
121 /**
122 * Returns the default value.
123 */
124 public function getDefault(): string|bool|int|float|array|null
125 {
126 return $this->default;
127 }
128
129 /**
130 * Returns true if the argument has values for input completion.
131 */
132 public function hasCompletion(): bool
133 {
134 return [] !== $this->suggestedValues;
135 }
136
137 /**
138 * Supplies suggestions when command resolves possible completion options for input.
139 *
140 * @see Command::complete()
141 */
142 public function complete(CompletionInput $input, CompletionSuggestions $suggestions): void
143 {
144 $values = $this->suggestedValues;
145 if ($values instanceof \Closure && !\is_array($values = $values($input))) {
146 throw new LogicException(\sprintf('Closure for argument "%s" must return an array. Got "%s".', $this->name, get_debug_type($values)));
147 }
148 if ($values) {
149 $suggestions->suggestValues($values);
150 }
151 }
152
153 /**
154 * Returns the description text.
155 */
156 public function getDescription(): string
157 {
158 return $this->description;
159 }
160 }