diff --git a/.gitignore b/.gitignore index 8f7e97e..3d793e8 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ # Configuration file /tools/config.php + +# unuseful caches +/.phpunit.result.cache diff --git "a/include/class-cli\\Opts.php" "b/include/class-cli\\Opts.php" index ee10f6c..a99224d 100644 --- "a/include/class-cli\\Opts.php" +++ "b/include/class-cli\\Opts.php" @@ -1,224 +1,279 @@ . # command line interface namespace cli; /** * Register command line parameters and read their arguments */ class Opts { /** * All the registered parameters * * @var array */ private $params; /** * Internal flag cache * * @var bool */ private $read = false; /** * Constructor * * @param $params array Parameters */ public function __construct( $params = [] ) { $this->register( $params ); } /** * Static instance */ private static $_instance; /** * Get a singleton instance * * @param $params array * @return self */ public static function instance() { if( ! isset( self::$_instance ) ) { self::$_instance = new self(); } return self::$_instance; } /** * Register multiple parameters * * @param $params array * @return self */ public function register( $params ) { foreach( $params as $param ) { $this->add( $param ); } return $this; } /** * Register a new parameter * * @param $param object Parameter * @return self */ public function add( Param $param ) { $this->params[] = $param; $this->read = false; // invalidate the cache return $this; } + /** + * Add a flag option + * + * @param $long_name string Long name like 'is-enabled' + * @param $short_name string Short name like 'e' + * @param $description string Short human description + * @param $default_val + * @return self + */ + public function addFlag( $long_name, $short_name = null, $description = null ) { + return $this->add( new ParamFlag( $long_name, $short_name, $description ) ); + } + + /** + * Add a valued option + * + * @param $long_name string Long name like 'revision-text' + * @param $short_name string Short name like 'r' + * @param $description string Short human description + * @param $default_val string Default value + * @return self + */ + public function addValued( $long_name, $short_name = null, $description = null, $default_val = null ) { + return $this->add( new ParamValued( $long_name, $short_name, $description, $default_val ) ); + } + + /** + * Get a single argument + * + * @param $name string Param name (short or long) + * @param $default_val string Default param value + * @return string|null + */ + public function get( $name, $default_val = null ) { + return $this->populate()->findParamFromName( $name )->getValue( $default_val ); + } + + /** + * Get all the registered parameters + * + * @return array + * @deprecated + */ + public function getAll() { + return $this->params; + } + + /** + * Get all the unnamed arguments + * + * @return array + */ + public static function unnamedArguments() { + $args = []; + foreach( $GLOBALS[ 'argv' ] as $arg ) { + if( '-' !== $arg[ 0 ] ) { + $args[] = $arg; + } + } + array_shift( $args ); + return $args; + } + + /** + * Print all the parameters in an human readable format + */ + public function printParams() { + + foreach( $this->getParams() as $param ) { + + $commands = []; + + if( $param->hasLongName() ) { + $commands[] = '--' . $param->getLongName(); + } + + if( $param->hasShortName() ) { + $commands[] = '-' . $param->getShortName(); + } + + $command = implode( '|', $commands ); + if( $command && ! $param->isFlag() ) { + $command .= $param->isValueOptional() + ? '=[VALUE]' + : '=VALUE'; + } + + printf( ' % -20s ', $command ); + + // eventually print an human description + if( $param->hasDescription() ) { + echo ' ' . $param->getDescription(); + } + + // eventually show the default value + if( $param->hasDefaultValue() ) { + printf( ' (default VALUE: %s)', $param->getDefaultValue() ); + } + + echo "\n"; + } + } + /** * Populate all parameters with their arguments * * @see getopt() * @return self */ public function populate() { if( ! $this->read ) { // prepare getopt() syntax $shorts = ''; $longs = []; foreach( $this->params as $opt ) { $shorts .= $opt->getShortOptFormat(); if( $opt->hasLongName() ) { $longs[] = $opt->getLongOptFormat(); } } // get command line arguments $args = getopt( $shorts, $longs ); // fill all parameters with their arguments foreach( $this->params as $opt ) { // try with the short name if( $opt->hasShortName() ) { $name = $opt->getShortName(); if( isset( $args[ $name ] ) ) { $opt->setValue( $opt->isFlag() ? true : $args[ $name ] ); continue; } } // try with the long name if( $opt->hasLongName() ) { $name = $opt->getLongName(); if( isset( $args[ $name ] ) ) { $opt->setValue( $opt->isFlag() ? true : $args[ $name ] ); } } } $this->read = true; } return $this; } /** * Find a registered param from a whatever name, the long or short on * * @param $name string Parameter name (long or short) * @return Param */ protected function findParamFromName( $name ) { foreach( $this->params as $opt ) { if( $opt->isName( $name ) ) { return $opt; } } throw new \InvalidArgumentException( 'unregistered parameter ' . $name ); } /** * Get all the registered parameters * * @return array + * @deprecated */ public function getParams() { - return $this->params; + return $this->getAll(); } /** * Get a single argument * * @param $name string Param name (short or long) - * @param $default string Default param value + * @param $default_val string Default param value * @return string|null + * @deprecated */ - public function getArg( $name, $default = null ) { - return $this->populate()->findParamFromName( $name )->getValue( $default ); - } - - /** - * Get all the unnamed arguments - * - * @return array - */ - public static function unnamedArguments() { - $args = []; - foreach( $GLOBALS[ 'argv' ] as $arg ) { - if( '-' !== $arg[ 0 ] ) { - $args[] = $arg; - } - } - array_shift( $args ); - return $args; - } - - /** - * Print all the parameters - */ - public function printParams() { - - foreach( $this->getParams() as $param ) { - - $commands = []; - - if( $param->hasLongName() ) { - $commands[] = '--' . $param->getLongName(); - } - - if( $param->hasShortName() ) { - $commands[] = '-' . $param->getShortName(); - } - - $command = implode( '|', $commands ); - if( $command && ! $param->isFlag() ) { - $command .= $param->isValueOptional() - ? '=[VALUE]' - : '=VALUE'; - } - - printf( ' % -20s ', $command ); - - if( $param->hasDescription() ) { - echo ' ' . $param->getDescription(); - } - - echo "\n"; - } + public function getArg( $name, $default_val = null ) { + return $this->get( $name, $default_val ); } } diff --git "a/include/class-cli\\Param.php" "b/include/class-cli\\Param.php" index 3fbc1a1..22e3435 100644 --- "a/include/class-cli\\Param.php" +++ "b/include/class-cli\\Param.php" @@ -1,298 +1,331 @@ . # command line interface namespace cli; /** * A command line parameter * * A difference between a 'parameter' and an argument is that a * 'parameter' can have a value and that value is its 'argument'. */ class Param { /** * To specify that the parameter has no any value */ const NO_VALUE = 1; /** * To specify that the parameter has an optional value */ const OPTIONAL_VALUE = 2; /** * To specify that the parameter has a mandatory value */ const REQUIRED_VALUE = 4; /** * Param long name * * @var string|null */ private $longName; /** * Param short name (one letter) * * @var string|null */ private $shortName; /** * Can be Param::NO_VALUE|Param::OPTIONAL_VALUE|Param::REQUIRED_VALUE * * @var int */ private $valueKind = 1; /** * Parameter argument * * @var mixed */ private $value; /** * Description * * @var string|null */ private $description; + /** + * Default value + * + * @var string|null + */ + private $defaultVal; + /** * Constructor * - * @param $long_name string Long name - * @param $short_name string Short name - * @param $value_kind int Value kind - * @param $description string Description + * @param $long_name string Long name like 'custom-option-name' + * @param $short_name string Short name like 'c' + * @param $value_kind int Value kind (1 = NO VALUE, 2 = OPTIONAL VALUE, 3 = REQUIRED VALUE) + * @param $description string Short human description + * @param $default_val string Default value */ - public function __construct( $long_name, $short_name, $value_kind, $description ) { + public function __construct( $long_name, $short_name = null, $value_kind = null, $description = null, $default_val = null ) { $this->longName = $long_name; $this->setShortName( $short_name ); $this->setValueKind( $value_kind ); $this->setDescription( $description ); + $this->defaultVal = $default_val; } /** * Set the short name * * @param $short_name string|null */ public function setShortName( $short_name ) { if( strlen( $short_name ) > 1 ) { throw new \InvalidArgumentException( 'short option must be 1 characters long' ); } $this->shortName = $short_name; } /** * Set the value kind * * @param $value_kind */ public function setValueKind( $value_kind ) { $value_kind = (int) $value_kind; switch( $value_kind ) { case self::NO_VALUE: case self::OPTIONAL_VALUE: case self::REQUIRED_VALUE: $this->valueKind = $value_kind; break; default: throw new \InvalidArgumentException( 'unexpected value kind' ); } } /** * Has a long name? * * @return bool */ public function hasLongName() { return null !== $this->getLongName(); } /** * Get the long name * * @return string|null */ public function getLongName() { return $this->longName; } /** * Has a short name? * * @return bool */ public function hasShortName() { return null !== $this->getShortName(); } /** * Get the short name * * @return string|null */ public function getShortName() { return $this->shortName; } + /** + * Check if the option has a default value + * + * @return boolean + */ + public function hasDefaultValue() { + return null !== $this->getDefaultValue(); + } + + /** + * Get the default value (if any) + * + * @return string|null + */ + public function getDefaultValue() { + return $this->defaultVal; + } + /** * Check if a name belongs to this parameter * * @param string $name Long or short parameter name * @return bool */ public function isName( $name ) { return $this->getLongName() === $name || $this->getShortName() === $name; } /** * Get the kind of the value * * @return int */ public function getValueKind() { return $this->valueKind; } /** * Get the parameter's argument or a default one * - * @param $default string Default value + * @param $default_val string Default value * @return string|null */ - public function getValue( $default = null ) { - return $this->value ? $this->value : $default; + public function getValue( $default_val = null ) { + + // eventually inherit the default value + if( $default_val === null ) { + $default_val = $this->getDefaultValue(); + } + + return $this->value ? $this->value : $default_val; } /** * Set the parameter's argument * * @param $value string|null */ public function setValue( $value ) { $this->value = $value; } /** * Check if the description exists * * @return bool */ public function hasDescription() { return null !== $this->getDescription(); } /** * Get the parameter's argument * * @param $description string */ public function getDescription() { return $this->description; } /** * Set the parameter's argument * * @param $description string */ public function setDescription( $description ) { $this->description = $description; } /** * Is the value of a certain kind? * * @param $kind int * @return bool */ protected function isValueKind( $kind ) { return $this->getValueKind() === $kind; } /** * Is the value optional? * * @return bool */ public function isValueOptional() { return $this->isValueKind( self::OPTIONAL_VALUE ); } /** * Is the value required? * * @return bool */ public function isValueRequired() { return $this->isValueKind( self::REQUIRED_VALUE ); } /** * Check if it can't have a value * * @return bool */ public function isFlag() { return $this->isValueKind( self::NO_VALUE ); } /** * Get the long option format * * @return string */ public function getLongOptFormat() { $v = ''; if( $this->hasLongName() ) { $v = $this->getLongName(); if( $this->isValueKind( self::OPTIONAL_VALUE ) ) { $v .= ':'; } elseif( $this->isValueKind( self::REQUIRED_VALUE ) ) { $v .= '::'; } } return $v; } /** * Get the short option format * * @return string */ public function getShortOptFormat() { $v = ''; if( $this->hasShortName() ) { $v = $this->getShortName(); if( $this->isValueKind( self::OPTIONAL_VALUE ) ) { $v .= ':'; } elseif( $this->isValueKind( self::REQUIRED_VALUE ) ) { $v .= '::'; } } return $v; } } diff --git "a/include/class-cli\\ParamFlag.php" "b/include/class-cli\\ParamFlag.php" index 1917d1c..1bf36d1 100644 --- "a/include/class-cli\\ParamFlag.php" +++ "b/include/class-cli\\ParamFlag.php" @@ -1,37 +1,38 @@ . # command line interface namespace cli; /** * A command line parameter that have not a value */ class ParamFlag extends Param { /** * Constructor * - * @param $long_name string Long name - * @param $short_name string Short name - * @param $description string + * @param $long_name string Long name like 'is-enabled' + * @param $short_name string Short name like 'e' + * @param $description string Short human description + * @return self */ - public function __construct( $long_name, $short_name, $description ) { + public function __construct( $long_name, $short_name = null, $description = null ) { parent::__construct( $long_name, $short_name, self::NO_VALUE, $description ); } } diff --git "a/include/class-cli\\ParamFlagLong.php" "b/include/class-cli\\ParamFlagLong.php" index 006e520..1e0e15d 100644 --- "a/include/class-cli\\ParamFlagLong.php" +++ "b/include/class-cli\\ParamFlagLong.php" @@ -1,36 +1,36 @@ . # command line interface namespace cli; /** * A command line flag with a long-name */ class ParamFlagLong extends ParamFlag { /** * Constructor * * @param $long_name string Long name * @param $description string Description */ - public function __construct( $long_name, $description ) { + public function __construct( $long_name, $description = null ) { parent::__construct( $long_name, null, $description ); } } diff --git "a/include/class-cli\\ParamValued.php" "b/include/class-cli\\ParamValued.php" index c592ee7..c75c5fb 100644 --- "a/include/class-cli\\ParamValued.php" +++ "b/include/class-cli\\ParamValued.php" @@ -1,37 +1,38 @@ . # command line interface namespace cli; /** * A command line parameter that must have a value */ class ParamValued extends Param { /** * Constructor * - * @param $long_name string Long name - * @param $short_name string Short name - * @param $description string Description + * @param $long_name string Long name like 'revision-text' + * @param $short_name string Short name like 'r' + * @param $description string Short human description + * @param $default_val string Default value */ - public function __construct( $long_name, $short_name, $description ) { - parent::__construct( $long_name, $short_name, self::REQUIRED_VALUE, $description ); + public function __construct( $long_name, $short_name = null, $description = null, $default_val = null ) { + parent::__construct( $long_name, $short_name, self::REQUIRED_VALUE, $description, $default_val ); } } diff --git "a/include/class-cli\\ParamValuedLong.php" "b/include/class-cli\\ParamValuedLong.php" index 4a19f76..4eb46d5 100644 --- "a/include/class-cli\\ParamValuedLong.php" +++ "b/include/class-cli\\ParamValuedLong.php" @@ -1,36 +1,36 @@ . # command line interface namespace cli; /** * A command line parameter with a long-name and a value */ class ParamValuedLong extends ParamValued { /** * Constructor * * @param $long_name string Long name * @param $description string Description */ - public function __construct( $long_name, $description ) { + public function __construct( $long_name, $description = null ) { parent::__construct( $long_name, null, $description ); } } diff --git a/include/functions.php b/include/functions.php index a5046c7..b9443c0 100644 --- a/include/functions.php +++ b/include/functions.php @@ -1,128 +1,138 @@ . /** * Shortcuts very useful when you are creating a bot */ /** * Get a single wiki from its UID * * Some known UIDs: * wikidatawiki - Wikidata * commonswiki - Wikimedia Commons * metawiki - Meta-wiki * itwiki - Wikipedia (it) * * @param string $uid * @return mw\StaticSite */ function wiki( $uid ) { return \web\MediaWikis::findFromUID( $uid ); } /** * Get Wikidata * * @return wm\Wikidata */ function wikidata() { return wiki( 'wikidatawiki' ); } /** * Get Wikimedia Meta-wiki * * @return wm\MetaWiki */ function meta() { return wiki( 'metawiki' ); } /** * Get Wikimedia Commons * * @return wm\Wikidata */ function commons() { return wiki( 'commonswiki' ); } /** * Get the Italian Wikipedia * * @return wm\WikipediaIt */ function itwiki() { return wiki( 'itwiki' ); } /** * Get the Wikimedia CH members wiki * * @return web\WikimediaCH */ function wmch() { return wiki( 'wmch' ); } /** * Merge your custom page objects with the API response pages * * Useful when you try to retrieve informations from many pages * with less request as possible. * * @param $response_query object * @param $my_stuff array * @param $query_containers array|string e.g. 'query' * @param $page_containers string e.g. 'pages' or 'users' * @return array */ function response_matcher( $response_query, $my_stuff, $query_containers = [], $page_container = null ) { return new \mw\API\PageMatcher( $response_query, $my_stuff, $query_containers, $page_container ); } /** * Enable debug mode * * @param $status status Enable debug or not */ function bozmw_debug( $status = true ) { \cli\Log::$DEBUG = $status; } /** * Serialize some data and write into a file * * @param $file string File path * @param $data mixed Your data */ function file_put_data( $file, $data ) { $data_raw = serialize( $data ); file_put_contents( $file, $data_raw ); } /** * Unserialize some data from a file * * @param $file string File path * @return mixed Data */ function file_get_data( $file ) { $contents = file_get_contents( $file ); return unserialize( $contents ); } + +/** + * Shortcut to get the Opts class + * + * It's useful to get and set your command line argument list + */ +function cli_options() { + return \cli\Opts::instance(); +} + diff --git a/phpunit/CliTest.php b/phpunit/CliTest.php new file mode 100644 index 0000000..1a58814 --- /dev/null +++ b/phpunit/CliTest.php @@ -0,0 +1,100 @@ +addFlag( "luser", "l", "Check if you are a luser or not" ) + ->addValued( "asd", "a", "Set your asd message", "FUCK YOU" ) + ->addFlag( "lamer", "z", "Check if you are a lamer or not" ); + + // check the asd argument (unpresent, so get default) + $asd = $options->get( 'asd' ); + + $this->assertEquals( $asd, "FUCK YOU" ); + } + + /** + * Test the bracket and glue + */ + public function testAddArgsWithoutDefaultButSuggestedLater() { + + $options = new \cli\Opts(); + + // register some dummy parameters + $options->addValued( "asd", "a", "Set your asd message" ); + + // check the asd argument (unpresent, so get default) + $asd = $options->get( 'asd', "DEFAULT ASD" ); + + $this->assertEquals( $asd, "DEFAULT ASD" ); + } + + /** + * Test the bracket and glue + */ + public function testAddArgsWithoutDefaultAtAll() { + + $options = new \cli\Opts(); + + // register some dummy parameters + $options->addValued( "asd", "a", "Set your asd message" ); + + // check the asd argument (unpresent, so get default) + $asd = $options->get( 'asd' ); + + $this->assertEquals( $asd, null ); + } + + /** + * Test the bracket and glue + */ + public function testAddArgsAndGetWithDefault() { + + $options = new \cli\Opts(); + + // register some dummy parameters + $options->addFlag( "luser", "l", "Check if you are a luser or not" ); + + // NOTE: the getArg() is deprecated but should be available + $asd = $options->getArg( 'luser', 'miao' ); + + $this->assertEquals( $asd, "miao" ); + } + + /** + * Test the bracket and glue + */ + public function testGetAll() { + + $options = new \cli\Opts(); + + // register some dummy parameters + $options + ->addFlag( "luser", "l", "Check if you are a luser or not" ) + ->addValued( "asd", "a", "Set your asd message", "FUCK YOU" ) + ->addFlag( "lamer", null, "Check if you are a lamer or not" ); + + // check the asd argument + $all = $options->getAll(); + + $this->assertEquals( 3, count( $all ) ); + } + + public function testCliShortcut() { + $this->assertEquals( cli_options() instanceof \cli\Opts, true ); + } + +} diff --git a/phpunit/README.md b/phpunit/README.md new file mode 100644 index 0000000..eef1711 --- /dev/null +++ b/phpunit/README.md @@ -0,0 +1,7 @@ +# How to run a test + +From the parent directory: + +``` +phpunit --bootstrap=phpunit/load.php --testdox phpunit +``` diff --git a/phpunit/load.php b/phpunit/load.php new file mode 100644 index 0000000..149f66c --- /dev/null +++ b/phpunit/load.php @@ -0,0 +1,8 @@ +