[Summary view] [Print] [Text view]

   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\Exception\InvalidArgumentException;
  15  use Symfony\Component\Console\Exception\LogicException;
  16  
  17  /**
  18   * Represents a command line option.
  19   *
  20   * @author Fabien Potencier <[email protected]>
  21   */
  22  class InputOption
  23  {
  24      /**
  25       * Do not accept input for the option (e.g. --yell). This is the default behavior of options.
  26       */
  27      public const VALUE_NONE = 1;
  28  
  29      /**
  30       * A value must be passed when the option is used (e.g. --iterations=5 or -i5).
  31       */
  32      public const VALUE_REQUIRED = 2;
  33  
  34      /**
  35       * The option may or may not have a value (e.g. --yell or --yell=loud).
  36       */
  37      public const VALUE_OPTIONAL = 4;
  38  
  39      /**
  40       * The option accepts multiple values (e.g. --dir=/foo --dir=/bar).
  41       */
  42      public const VALUE_IS_ARRAY = 8;
  43  
  44      /**
  45       * The option may have either positive or negative value (e.g. --ansi or --no-ansi).
  46       */
  47      public const VALUE_NEGATABLE = 16;
  48  
  49      private $name;
  50      private $shortcut;
  51      private $mode;
  52      private $default;
  53      private $description;
  54  
  55      /**
  56       * @param string|array|null                $shortcut The shortcuts, can be null, a string of shortcuts delimited by | or an array of shortcuts
  57       * @param int|null                         $mode     The option mode: One of the VALUE_* constants
  58       * @param string|bool|int|float|array|null $default  The default value (must be null for self::VALUE_NONE)
  59       *
  60       * @throws InvalidArgumentException If option mode is invalid or incompatible
  61       */
  62      public function __construct(string $name, $shortcut = null, int $mode = null, string $description = '', $default = null)
  63      {
  64          if (str_starts_with($name, '--')) {
  65              $name = substr($name, 2);
  66          }
  67  
  68          if (empty($name)) {
  69              throw new InvalidArgumentException('An option name cannot be empty.');
  70          }
  71  
  72          if (empty($shortcut)) {
  73              $shortcut = null;
  74          }
  75  
  76          if (null !== $shortcut) {
  77              if (\is_array($shortcut)) {
  78                  $shortcut = implode('|', $shortcut);
  79              }
  80              $shortcuts = preg_split('{(\|)-?}', ltrim($shortcut, '-'));
  81              $shortcuts = array_filter($shortcuts);
  82              $shortcut = implode('|', $shortcuts);
  83  
  84              if (empty($shortcut)) {
  85                  throw new InvalidArgumentException('An option shortcut cannot be empty.');
  86              }
  87          }
  88  
  89          if (null === $mode) {
  90              $mode = self::VALUE_NONE;
  91          } elseif ($mode >= (self::VALUE_NEGATABLE << 1) || $mode < 1) {
  92              throw new InvalidArgumentException(sprintf('Option mode "%s" is not valid.', $mode));
  93          }
  94  
  95          $this->name = $name;
  96          $this->shortcut = $shortcut;
  97          $this->mode = $mode;
  98          $this->description = $description;
  99  
 100          if ($this->isArray() && !$this->acceptValue()) {
 101              throw new InvalidArgumentException('Impossible to have an option mode VALUE_IS_ARRAY if the option does not accept a value.');
 102          }
 103          if ($this->isNegatable() && $this->acceptValue()) {
 104              throw new InvalidArgumentException('Impossible to have an option mode VALUE_NEGATABLE if the option also accepts a value.');
 105          }
 106  
 107          $this->setDefault($default);
 108      }
 109  
 110      /**
 111       * Returns the option shortcut.
 112       *
 113       * @return string|null
 114       */
 115      public function getShortcut()
 116      {
 117          return $this->shortcut;
 118      }
 119  
 120      /**
 121       * Returns the option name.
 122       *
 123       * @return string
 124       */
 125      public function getName()
 126      {
 127          return $this->name;
 128      }
 129  
 130      /**
 131       * Returns true if the option accepts a value.
 132       *
 133       * @return bool true if value mode is not self::VALUE_NONE, false otherwise
 134       */
 135      public function acceptValue()
 136      {
 137          return $this->isValueRequired() || $this->isValueOptional();
 138      }
 139  
 140      /**
 141       * Returns true if the option requires a value.
 142       *
 143       * @return bool true if value mode is self::VALUE_REQUIRED, false otherwise
 144       */
 145      public function isValueRequired()
 146      {
 147          return self::VALUE_REQUIRED === (self::VALUE_REQUIRED & $this->mode);
 148      }
 149  
 150      /**
 151       * Returns true if the option takes an optional value.
 152       *
 153       * @return bool true if value mode is self::VALUE_OPTIONAL, false otherwise
 154       */
 155      public function isValueOptional()
 156      {
 157          return self::VALUE_OPTIONAL === (self::VALUE_OPTIONAL & $this->mode);
 158      }
 159  
 160      /**
 161       * Returns true if the option can take multiple values.
 162       *
 163       * @return bool true if mode is self::VALUE_IS_ARRAY, false otherwise
 164       */
 165      public function isArray()
 166      {
 167          return self::VALUE_IS_ARRAY === (self::VALUE_IS_ARRAY & $this->mode);
 168      }
 169  
 170      public function isNegatable(): bool
 171      {
 172          return self::VALUE_NEGATABLE === (self::VALUE_NEGATABLE & $this->mode);
 173      }
 174  
 175      /**
 176       * @param string|bool|int|float|array|null $default
 177       */
 178      public function setDefault($default = null)
 179      {
 180          if (self::VALUE_NONE === (self::VALUE_NONE & $this->mode) && null !== $default) {
 181              throw new LogicException('Cannot set a default value when using InputOption::VALUE_NONE mode.');
 182          }
 183  
 184          if ($this->isArray()) {
 185              if (null === $default) {
 186                  $default = [];
 187              } elseif (!\is_array($default)) {
 188                  throw new LogicException('A default value for an array option must be an array.');
 189              }
 190          }
 191  
 192          $this->default = $this->acceptValue() || $this->isNegatable() ? $default : false;
 193      }
 194  
 195      /**
 196       * Returns the default value.
 197       *
 198       * @return string|bool|int|float|array|null
 199       */
 200      public function getDefault()
 201      {
 202          return $this->default;
 203      }
 204  
 205      /**
 206       * Returns the description text.
 207       *
 208       * @return string
 209       */
 210      public function getDescription()
 211      {
 212          return $this->description;
 213      }
 214  
 215      /**
 216       * Checks whether the given option equals this one.
 217       *
 218       * @return bool
 219       */
 220      public function equals(self $option)
 221      {
 222          return $option->getName() === $this->getName()
 223              && $option->getShortcut() === $this->getShortcut()
 224              && $option->getDefault() === $this->getDefault()
 225              && $option->isNegatable() === $this->isNegatable()
 226              && $option->isArray() === $this->isArray()
 227              && $option->isValueRequired() === $this->isValueRequired()
 228              && $option->isValueOptional() === $this->isValueOptional()
 229          ;
 230      }
 231  }