hhvm / hh-clilib

Command Line Interface (CLI) Library for the Hack programming language

Hack CLI Library

This library provides basic command-line handling, including:

• parsing of ARGV
• interactive TTY detection
• color TTY detection

It aims for as much code as possible to be in strict mode.

Installation

hhvm composer.phar require facebook/hh-clilib

Examples

In src/MyCLI.hh:

// MyCLI.hh
<?hh // strict

use type Facebook\CLILib\CLIBase;

final class MyCLI extends CLIBase {
  <<__Override>>
  public async function mainAsync(): Awaitable<int> {
    $this->getStdout()->write("Hello, world!");
    return 0;
  }
}

In bin/mycli:

<?hh // not strict because of top-level statements.

require_once(__DIR__.'/../vendor/hh_autoload.php');

MyCLI::main();

Options

Options are optional, always have a long form (e.g. --foo), may have a short form (e.g. -f), and may require a value (e.g. --foo=bar or --foo bar).

You can specify supported options by implemented getSupportedOptions(); --help is always supported.

<<__Override>>
protected function getSupportedOptions(): vec<CLIOptions\CLIOption> {
	return vec[
		CLIOptions\flag(
			() ==> { $this->verbosity++; },
			"Increase output verbosity",
			'--verbose',
			'-v',
		),
		CLIOptions\with_required_enum(
			OutputFormat::class,
			$f ==> { $this->format = $f; },
			Str\format(
				"Desired output format (%s). Default: %s",
				Str\join(OutputFormat::getValues(), '|'),
				(string) $this->format,
			),
			'--format',
			'-f',
		),
		CLIOptions\with_required_string(
			$s ==> { $this->outputRoot = $s; },
			"Directory for output files. Default: working directory",
			'--output',
			'-o',
		),
	];
}

Arguments

Arguments do not have a name, and may be required. To support arguments, extend CLIWithArguments or CLIWithRequiredArguments.

Arguments are always strings, and can be retrieved via ->getArguments();

Contributing

See CONTRIBUTING.md.

License

hh-clilib is MIT-licensed.

hh-clilib's Issues

Add interface for stdin

Migrate to the hsl-experimental IO interfaces

https://github.com/hhvm/hsl-experimental/releases/tag/v3.29.2

Add 'context' object, bundling together information/handles for the current session

For example:

• supportsColors()
• isInteractive()
• access to stdout and stderr

Inconsistent that getHelpTextForRequiredarguments() is static, but getSupportedOptions is not

Handle terminal encoding

If someone writes to stdout, we currently just send raw bytes. We should respect locale.

While most terminals are either C or some variant of UTF-8, a large variety of encodings are supported, e.g. on recent ubuntu:

fred@homeserver:~# LC_ALL=ja_JP.UTF-8 date
2019年  2月 21日 木曜日 08:52:14 PST
fred@homeserver:~# LC_ALL=ja_JP.EUC_JP date
2019ǯ  2�� 21�� ������ 08:52:22 PST

I suggest:

• defining Hack source files/literals etc as UTF-8 (this needs some wider discussion)
• keeping HSL IO interfaces as raw bytes
• stop using HSL IO interfaces directly here - provide (read|write)(Text|Bytes) that handle locale if appropriate

CLI output truncated to first KB

For this CLI class:

<?hh // strict
use type Facebook\CLILib\CLIWithArguments;
use namespace Facebook\CLILib\CLIOptions;
final class TruncateOutputCLI extends CLIWithArguments {
	<<__Override>>
	public async function mainAsync(): Awaitable<int> {
		$kb = str_repeat(".", 1023) . "\n";
		$output = str_repeat($kb, 4);
		$bytes = strlen($output);
		$bytes_written = $this->getTerminal()->getStdout()->write($output);
		// Same issue occurs with
		// echo str_repeat($kb, 4);
		echo "\n";
		echo "Bytes: " . strlen($output) . "\n";
		echo "Written: " . $bytes_written . "\n";
		return $bytes === $bytes_written ? 0 : 1;
	}
	public function getSupportedOptions(): vec<CLIOptions\CLIOption> {
		return vec[];
	}
}

Only the first 1023 bytes are output. This issue occurs for me with hhvm 3.28 and the current nightly on OSX.

See https://github.com/ryangreenberg/hh-clilib-repro for code to reproduce. My initial guess is that this has something to do with mainAsync being an Awaitable but I don't understand why that would be the case. When I step through this code in the debugger it outputs all the content.

Add support for bash completion