Merge pull request #7 from chop1k/v2.1.0-dev

v2.1.0

README.md

@@ -8,6 +8,8 @@ Package for console scripts and applications.
 - [Basic usage](docs/basic_usage.md)
 - [Source](docs/source.md)
 - [Distributor](docs/distributor.md)
+- [Formatter](docs/formatter.md)
+- [Argument](docs/argument.md)
 - [Changelog](docs/changelog.md)
 
 ## What can you do using Consolly?

composer.json

@@ -5,7 +5,7 @@
   "keywords": ["console", "cli", "framework", "package", "tools"],
   "minimum-stability": "stable",
   "license": "MIT",
-  "version": "v2.0.1",
+  "version": "v2.1.0",
   "authors": [
     {
       "name": "chop1k",

docs/argument.md

@@ -0,0 +1,35 @@
+# Argument
+Argument is a helper class used by Distributor and Formatter.
+
+You have to use this class if you want to override Distributor or Formatter instead of implementing the appropriate interfaces, because both use the constants and the methods of this class everywhere.
+
+Argument defines argument-types:
+- TYPE_OPTION - Option type. The option looks like "--option".
+- TYPE_ABBREVIATION - Abbreviated option type. The abbreviation looks like "-a".
+- TYPE_ABBREVIATIONS - List of abbreviated options. The options look like "-abs".
+- TYPE_VALUE - Value type. The value looks like "value".
+- TYPE_PURE_VALUE - Pure value type. It looks like value type but without quotes.
+- TYPE_EQUAL_SEPARATED_OPTION - Equal-separated option type. It looks like "--option=value".
+- TYPE_EQUAL_SEPARATED_ABBREVIATION - Equal-separated abbreviation type. It looks like "-a=value".
+- TYPE_EQUAL_SEPARATED_ABBREVIATIONS - Equal-separated abbreviations type. It looks like "-abs=value".
+
+Argument defines functions for defining types:
+- isOption - Returns true if argument is option.
+- isAbbreviation - Returns true if the argument is an abbreviated option.
+- isAbbreviations - Returns true if the argument is an array of abbreviated options.
+- isValue - Returns true if the argument is a value.
+- isPureValue - Returns true if the argument is a pure value.
+- isEqualSeparated - Returns true if option is an equal separated option.
+- isCommand - Returns true if the argument is a command.
+- isUtility - Returns true if the argument is a utility.
+
+Argument defines functions for type conversion:
+- toOption - Adds prefix to the argument and returns it.
+- toAbbreviation - Adds prefix to the argument and returns it.
+- toValue - Adds quotes to the argument and returns it.
+- toPureValue - Clears the argument and returns it.
+- toEqualSeparated - Adds equal-separation between option and value.
+
+Other methods:
+- clear - Trims special symbols.
+- explodeEqualSeparated - Shortcut for exploding a given argument if the argument is equal separated option.

docs/basic_usage.md

@@ -1,6 +1,6 @@
 # Basic usage
-For use consolly you should create a commands, and an options for the commands.
-Alter that you should add your options to the command, create consolly class, add command to main Consolly class and execute the handle() method of the consolly class.
+For use consolly you should create commands and options for the commands.
+Alter that you should add your options to the command, create Consolly instance, add command to the Consolly class and execute the handle() method of the consolly instance.
 
 ## Commands
 All commands must implement CommandInterface or extend Command class.
@@ -77,7 +77,7 @@ CommandInterface defines methods:
 - handle() - Method which will be executed if the command specified.
 
 ## Options
-Option is string like "-o" "--option" which are in front of the command. Option can require value and be required, can be equal separated and abbreviated.
+Option is string like "-o" or "--option" which are in front of the command. Option can require value and be required, can be equal separated and abbreviated.
 All options must implement OptionInterface interface.
 
 ### Creating option via Option class
@@ -171,21 +171,25 @@ If no command found, consolly will use the default command. If no default comman
 
 Default command - the command, which will be used if the command was not found by the distributor.
 
-After that, consolly will execute handleOptions() method of the distributor.
-Distributor will handle an options, after that consolly will pass a result of the getNextArguments() method of the distributor to the handle() method of the command.
+After that, consolly will execute handleArguments() method of the distributor.
+Distributor will handle an arguments, after that consolly will pass a result of the getNextArguments() method of the distributor to the handle() method of the command.
 In the end, consolly will return a result of the handle() method of the command.
 
 ```php
 use Consolly\Consolly;
 use Consolly\Distributor\Distributor;
+use Consolly\Formatter\Formatter;
 use Consolly\Source\ConsoleArgumentsSource;
 
 $consolly = new Consolly(
     new ConsoleArgumentsSource([]), // default source
-    new Distributor(), // default distributor
+    new Distributor(new Formatter()), // default distributor with default formatter
     new MyDefaultCommand()
 );
 
+// Or you can use preset.
+$consolly = Consolly::default([], new MyDefaultClass());
+
 // you also can use accessors to set default command.
 
 $consolly->addCommand(new MyCommand());
@@ -199,8 +203,6 @@ This way, you can create nested commands.
 ```php
 use Consolly\Command\Command;
 use Consolly\Consolly;
-use Consolly\Distributor\Distributor;
-use Consolly\Source\ConsoleArgumentsSource;
 
 class MyCommand extends Command
 {
@@ -213,10 +215,7 @@ class MyCommand extends Command
 
     public function handle(array $nextArgs)
     {
-        $consolly = new Consolly(
-            new ConsoleArgumentsSource($nextArgs, false),
-            new Distributor()
-        );
+        $consolly = Consolly::default($nextArgs);
 
         $consolly->addCommand(new MyNestedCommand());
         $consolly->addCommand(new AlsoMyNestedCommand());

docs/changelog.md

@@ -1,6 +1,32 @@
 # Changelog
 Here is a list of versions with changes from first to last.
 
+## v2.1.0
+- Added FormatterInterface and Formatter with test:
+- DistributorInterface and Distributor:
+  - handleOptions() renamed to handleArguments().
+- Distributor:
+  - Now requires implementation of FormatterInterface.
+  - Minor changes in test.
+  - Added new type of value "pure-type". Now you can use value without quotes.
+- ConsoleArgumentsSource:
+  - Removed $ignoreFirst flag. Now the developer is obliged to take care of this himself.
+- Consolly
+  - Added static method default().
+- Argument:
+  - Added type constants which used by Formatter and Distributor.
+  - Added additional functions.
+  - Improved the accuracy of defining the argument type.
+  - Added test.
+
+## v2.0.1
+Fixes:
+- Fixed useless LogicException thrown in the distributor's getNextArguments method after the distributor received an empty array of commands.
+- Fixed uninitialized variable $commands in Consolly class.
+
+Other:
+- Added regression tests for the cases described above.
+
 ## v2.0.0
 - Added more abstraction layers.
   - Added a DistributorInterface with implementation.

docs/distributor.md

@@ -22,12 +22,12 @@ class MyDistributor implements DistributorInterface
     public function getCommand(): ?CommandInterface
     {
         // here you should find the command and return it.
-        // if the command was not found it should return null, then default command will be user 
+        // if the command was not found it should return null, then default command will be used.
     }
 
-    public function handleOptions(CommandInterface $command): void
+    public function handleArguments(CommandInterface $command): void
     {
-        // here you should handle options and arguments, find and set value, set indication and other.
+        // here you should handle arguments, find and set value, set indication and other.
     }
 
     public function getNextArguments(): array
@@ -44,28 +44,39 @@ Next executes the setArguments() method, where you can handle the arguments, giv
 
 Then executes the getCommand() method, which should return the command or null if command was not found.
 
-After that, executes handleOption() method and passes the command. It can be a command, returned by the getCommand() method, or default command if specified.
-The handleOptions() method should handle the arguments and distribute them.
+After that, executes handleArguments() method and passes the command. It can be a command, returned by the getCommand() method, or default command if specified.
+The handleArguments() method should handle the arguments and distribute them.
 
 In the end, the getNextArguments() method executes. It should return an array of next arguments, which will be passed to the handle() method of the command.
 
 ## Distributor
 The Distributor is a default implementation of the DistributorInterface interface.
 
+A formatter is used to work with arguments.
+
 Distributor distributes arguments according to the rules below:
-- Command is a plaintext without quotes or dashes.
-- Value is a text quoted by ' or ". It looks like "value".
+- Command and is a plaintext without quotes or dashes.
+- Utility is same as command and pure value. By default, utility is not used.
+- Value is a text quoted by ' or ". It looks like "value". Is necessary to distinguish a value from a command.
+- Pure value is a text without quotes, spaces, dashes and other.
 - Option is a text starts with one or two dashes. It looks like -o --option --equalSeparatedOption=value.
-
-All text after command will be transferred as $nextArgs.
+- Equal-separated option provides an option(s) with values in one argument.
 
 ```bash
+# All text after command will be transferred as $nextArgs.
+
 # Full-name option with value and nested command.
 myscript --my-option "myvalue" command --my-nested-option nested-command
 
+# Full-name option with pure-value and nested command.
+myscript --my-option myvalue command --my-nested-option nested-command
+
 # Abbreviated option with value and nested command.
 myscript -o "myvalue" command -n nested-command
 
+# Abbreviated option with pure-value and nested command.
+myscript -o myvalue command -n nested-command
+
 # Equal-separated option with value and nested command.
 myscript --my-option=myvalue command --my-nested-option nested-command
 
@@ -82,5 +93,16 @@ myscript -fst "first option value" "second option value" "third option value" co
 myscript -fst=options_value command
 ```
 
-If you use ConsoleArgumentsSource, it will ignore first argument "myscript".
-To turn off this, you should set $ignoreFirst parameter to false. You can do this via the constructor or an accessor.
+It's recommended to not specify pure-value same as commands, because distributor by default finds first match of the command name.
+
+```bash
+# It this case, first command word will be regarded as a command.
+# Values after the command will be used as next arguments.
+myscript --my-option command command
+
+# To avoid this you can enclose a value in quotes.
+myscript --my-option "command" command
+
+# Or you can use equal-separated options.
+myscript --my-option=command command
+```

docs/formatter.md

@@ -0,0 +1,106 @@
+# Formatter
+Formatter is used by Distributor to formatting given arguments to given types. Also, it defines a type of the argument and returns it.
+
+Formatter implements FormatterInterface interface.
+
+```php
+use Consolly\Formatter\FormatterInterface;
+
+class MyFormatter implements FormatterInterface
+{
+    public function format($value, string $type): string
+    {
+        // here you should format the value to given type.
+    }
+
+    public function parse(string $argument): string
+    {
+        // here you should define type and return it.
+    }
+}
+```
+
+## Formatter class
+Formatter class is a default implementation of FormatterInterface interface which used by default by Distributor class.
+
+Formatter and Distributor both uses Argument helper class.
+
+```php
+use Consolly\Formatter\Formatter;
+use Consolly\Helper\Argument;
+
+$formatter = new Formatter();
+
+// will return --option.
+$formatter->format('option', Argument::TYPE_OPTION);
+
+// will return -a.
+$formatter->format('a', Argument::TYPE_ABBREVIATION);
+
+// will return -abs.
+$formatter->format('abs', Argument::TYPE_ABBREVIATIONS);
+
+// will return "value".
+$formatter->format('value', Argument::TYPE_VALUE);
+
+// will return value.
+$formatter->format('value', Argument::TYPE_PURE_VALUE);
+$formatter->format('"value"', Argument::TYPE_PURE_VALUE);
+
+// will return --option=value
+$formatter->format(['option', 'value'], Argument::TYPE_EQUAL_SEPARATED_OPTION);
+
+// will return -a=value
+$formatter->format(['a', 'value'], Argument::TYPE_EQUAL_SEPARATED_ABBREVIATION);
+
+// will return -abs=value
+$formatter->format(['abs', 'value'], Argument::TYPE_EQUAL_SEPARATED_ABBREVIATIONS);
+
+// will return value of Argument::TYPE_ABBREVIATION constant.
+$formatter->parse('-a');
+
+// will return value of Argument::TYPE_ABBREVIATIONS constant.
+$formatter->parse('-abs');
+
+// will return value of Argument::TYPE_VALUE constant.
+$formatter->parse('"value"');
+
+// will return value of Argument::TYPE_VALUE constant.
+$formatter->parse("'value'");
+
+// will return value of Argument::TYPE_PURE_VALUE constant.
+$formatter->parse('value');
+
+// will return value of Argument::EQUAL_SEPARATED_OPTION constant.
+$formatter->parse('--option=value');
+
+// will return value of Argument::EQUAL_SEPARATED_ABBREVIATION constant.
+$formatter->parse('-a=value');
+
+// will return value of Argument::EQUAL_SEPARATED_ABBREVIATIONS constant.
+$formatter->parse('-abs=value');
+```
+
+By default, the formatter does not distinguish the command and utility from pure value, because in order to distinguish a command or utility from a pure value, you need to know the location and type of the remaining arguments, the formatter is not able to do this because it only takes one value. 
+
+```php
+use Consolly\Formatter\Formatter;
+use Consolly\Helper\Argument;
+
+$formatter = new Formatter();
+
+// will return utility.
+$formatter->format('utility', Argument::TYPE_UTILITY);
+
+// will return command.
+$formatter->format('command', Argument::TYPE_COMMAND);
+
+// will return value of Argument::TYPE_PURE_VALUE constant.
+$formatter->parse('utility');
+
+// will return value of Argument::TYPE_PURE_VALUE constant.
+$formatter->parse('command');
+
+```
+
+You can override the formatter isCommand, isUtility, toCommand, toUtility methods and write custom handling logic.

docs/source.md

@@ -30,8 +30,4 @@ use Consolly\Source\ConsoleArgumentsSource;
 $source = new ConsoleArgumentsSource($argv);
 
 $arguments = $source->getArguments(); // returns the $argv
-```
-
-By default, it ignores first argument of the $arguments.
-To turn off this, you should set $ignoreFirst parameter to false.
-You can do this via the constructor or an accessor.
+```