<?php

namespace Nest\Cli\Commands;

/**
 * A flag definition object.
 */
class FlagDefinition
{
	/**
	 * Help flag name.
	 */
	const string HELP_FLAG = "help";

	/**
	 * Short version of the flag.
	 * @var string|null
	 */
	protected ?string $short = null;

	/**
	 * Flag description.
	 * @var string|null
	 */
	protected ?string $description = null;

	/**
	 * Positional parameters array for the current flag.
	 * @var object{name: string, description: string}[]
	 */
	protected array $parameters = [];

	/**
	 * Set if the flag is required or not. A flag is NOT required by default.
	 * @var bool
	 */
	protected bool $required = false;

	/**
	 * Set the short version of the flag.
	 * @param string $short Short version of the flag.
	 * @return $this
	 */
	public function short(string $short): static
	{
		$this->short = $short;
		return $this;
	}

	/**
	 * Set the description of the flag.
	 * @param string $description The description of the flag.
	 * @return $this
	 */
	public function description(string $description): static
	{
		// Set description.
		$this->description = $description;
		return $this;
	}

	/**
	 * Add a positional parameter to the flag.
	 * @param string $name Parameter name.
	 * @param string $description Parameter description.
	 * @return $this
	 */
	public function parameter(string $name, string $description): static
	{
		// Add a positional parameter to the next position, with given metadata.
		$this->parameters[] = (object) [
			"name" => $name,
			"description" => $description,
		];

		return $this;
	}

	/**
	 * Set the flag as required (or not).
	 * @param bool $require True to set the flag as required.
	 * @return $this
	 */
	public function require(bool $require = true): static
	{
		$this->required = $require;
		return $this;
	}

	/**
	 * Get short version of the flag, if there is one.
	 * @return string|null
	 */
	public function getShort(): ?string
	{
		return $this->short;
	}

	/**
	 * Get flag description.
	 * @return string
	 */
	public function getDescription(): string
	{
		return $this->description ?? "";
	}

	/**
	 * Get flag parameters count.
	 * @return int
	 */
	public function getParametersCount(): int
	{
		return count($this->parameters);
	}

	/**
	 * Determine if the flag is required or not.
	 * @return bool True if the flag is required.
	 */
	public function isRequired(): bool
	{
		return $this->required;
	}
}