Added new set_domain_name method documentation, new documentation for…

… CLI class

Fixed CLI output for Windows
Allow custom message for invalid options, fixed cli read function
documentation.

modules/minion/classes/Kohana/Minion/CLI.php

@@ -10,7 +10,8 @@
 class Kohana_Minion_CLI {
 
 	public static $wait_msg = 'Press any key to continue...';
-
+	public static $invalid_option_msg = 'This is not a valid option. Please try again.';
+
 	protected static $foreground_colors = [
 		'black'        => '0;30',
 		'dark_gray'    => '1;30',
@@ -115,14 +116,11 @@ public static function options($options = NULL)
 	 *
 	 * Usage:
 	 *
-	 * // Waits for any key press
-	 * Minion_CLI::read();
-	 *
 	 * // Takes any input
 	 * $color = Minion_CLI::read('What is your favorite color?');
 	 *
 	 * // Will only accept the options in the array
-	 * $ready = Minion_CLI::read('Are you ready?', array('y','n'));
+	 * $ready = Minion_CLI::read('Are you ready?', ['y','n']);
 	 *
 	 * @param  string  $text    text to show user before waiting for input
 	 * @param  array   $options array of options the user is shown
@@ -131,21 +129,24 @@ public static function options($options = NULL)
 	public static function read($text = '', array $options = NULL)
 	{
 		// If a question has been asked with the read
-		$options_output = '';
 		if ( ! empty($options))
 		{
-			$options_output = ' [ '.implode(', ', $options).' ]';
+			$text .= ' [ '.implode(', ', $options).' ]';
+		}
+		if ($text != '')
+		{
+			$text .= ': ';
 		}
 
-		fwrite(STDOUT, $text.$options_output.': ');
+		fwrite(STDOUT, $text);
 
 		// Read the input from keyboard.
 		$input = trim(fgets(STDIN));
 
 		// If options are provided and the choice is not in the array, tell them to try again
 		if ( ! empty($options) && ! in_array($input, $options))
 		{
-			Minion_CLI::write('This is not a valid option. Please try again.');
+			Minion_CLI::write(Minion_CLI::$invalid_option_msg);
 
 			$input = Minion_CLI::read($text, $options);
 		}
@@ -233,7 +234,15 @@ public static function write_replace($text = '', $end_line = FALSE)
 	{
 		// Append a newline if $end_line is TRUE
 		$text = $end_line ? $text.PHP_EOL : $text;
-		fwrite(STDOUT, "\r\033[K".$text);
+
+		if (Kohana::$is_windows)
+		{
+			fwrite(STDOUT, "\r".$text);
+		}
+		else
+		{
+			fwrite(STDOUT, "\r\033[K".$text);
+		}
 	}
 
 	/**
@@ -247,7 +256,7 @@ public static function write_replace($text = '', $end_line = FALSE)
 	 * @param int $seconds number of seconds
 	 * @param bool $countdown show a countdown or not
 	 */
-	public static function wait($seconds = 0, $countdown = false)
+	public static function wait($seconds = 0, $countdown = FALSE)
 	{
 		if ($countdown === TRUE)
 		{

modules/minion/guide/minion/cli.md

@@ -0,0 +1,87 @@
+# CLI
+
+The module contains helper functions to read and write to the CLI.
+
+# User input
+
+## Read input
+
+It is possible to read data from the CLI, the `read` method will wait for the user input and return the string:
+
+	// Prompt 'how many items:'
+	$result = Minion_CLI::read('How many items');
+
+
+## Limit the number of choices
+
+To limit the amount of possible choices for the user input, additional options can be added to the `read` method.
+If an invalid option is entered the `$invalid_option_msg` will be displayed (default value *'This is not a valid option. Please try again.'*).
+
+	<?php
+
+	class Minion_Task_Demo extends Minion_Task
+	{
+		// Override the default message
+		public static $invalid_option_msg = 'Oops this is not a valid option!';
+
+		protected function _execute(array $params)
+		{
+			// Wait for <enter>
+			$result = Minion_CLI::read('Are you sure', ['y', 'n']);
+		}
+	}
+
+
+## Wait for input
+
+To wait for <enter> the `wait` method can be used, the default message that will be *Press any key to continue...*, this can be replaced by overriding the `$wait_msg` variable.
+
+	<?php
+
+	class Minion_Task_Demo extends Minion_Task
+	{
+		// Override the default message
+		public static $wait_msg = 'Press <enter> to ...';
+
+		protected function _execute(array $params)
+		{
+			// Wait for <enter>
+			Minion_CLI::wait();
+		}
+	}
+
+To wait an amount of seconds before the user can continue the number of seconds can be added. To display a counter the second argument should be set to `TRUE`.
+
+	<?php
+
+	class Minion_Task_Demo extends Minion_Task
+	{
+		// Wait 10 seconds
+		Minion_CLI::wait(10, TRUE);
+	}
+
+# Console output
+
+## Simple output
+
+To output a simple text the `write` method is available.
+
+	Minion_CLI::write('Done sending emails');
+
+
+Under Linux there is to option to colorize the output.
+The first argument is the foreground color; valid colors are `black`, `dark_gray`, `blue`, `light_blue`, `green`, `light_green`, `cyan`, `light_cyan`, `red`, `light_red`, `purple`, `light_purple`, `brown`, `yellow`, `light_gray` and `white`.
+The second argument is the background color; valid background colors are `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan` and `light_gray`.
+
+	Minion_CLI::write(Minion_CLI::color('Something went wrong', 'white', 'red'));
+
+
+## Replacing text
+
+It is possible to write a text to the console and overwriting it later.
+
+	Minion_CLI::write_replace('Updating database');
+	// ... 
+	Minion_CLI::write_replace('Update finished', TRUE);
+
+[!!] Under Windows it is not possible to clear the line, this means that all texts should have the same length and padded with spaces to clear old messages.

modules/minion/guide/minion/menu.md

@@ -1,3 +1,4 @@
 ## [Minion]()
  - [Setup](setup)
- - [Writing a Task](tasks)
+ - [Writing a Task](tasks)
+ - [CLI](cli)

modules/minion/guide/minion/setup.md

@@ -1,3 +1,5 @@
 # Minion Setup
 
-[!!] Since Kohana `3.3.x`, minion requires no additional setup to use.
+[!!] Since Kohana `3.3.x`, minion requires no additional setup to use.
+
+[!!] If your code uses links check the [using links](tasks#using-links) under tasks for domain configuration.

modules/minion/guide/minion/tasks.md

@@ -6,10 +6,10 @@ Writing a task in minion is very easy. Simply create a new class called `Task_<T
 
 	class Task_Demo extends Minion_Task
 	{
-		protected $_options = array(
+		protected $_options = [
 			'foo' => 'bar',
 			'bar' => NULL,
-		);
+		];
 
 		/**
 		 * This is a demo task
@@ -26,8 +26,8 @@ Writing a task in minion is very easy. Simply create a new class called `Task_<T
 You'll notice a few things here:
 
  - You need a main `_execute()` method. It should take one array parameter.
-   - This parameter contains any command line options passed to the task.
-   - For example, if you call the task above with `./minion --task=demo --foo=foobar` then `$params` will contain: `array('foo' => 'foobar', 'bar' => NULL)`
+	 - This parameter contains any command line options passed to the task.
+	 - For example, if you call the task above with `./minion --task=demo --foo=foobar` then `$params` will contain: `array('foo' => 'foobar', 'bar' => NULL)`
  - It needs to have a `protected $_options` array. This is a list of parameters you want to accept for this task. Any parameters passed to the task not in this list will be rejected.
 
 ## Namespacing Tasks
@@ -69,3 +69,13 @@ Tasks can have built-in help. Minion will read class docblocks that you specify:
 	class Minion_Task_Demo extends Minion_Task
 
 The `@` tags in the class comments will also be displayed in a human readable format. When writing your task comments, you should specify how to use it, and any parameters it accepts.
+
+# Using links
+
+If the output task contains links which are generated using the build in URL functions you should configure the domain name for the task.
+The `Minion_Task::set_domain_name()` method takes care of this.
+
+There are two options to set the domain:
+
+ - As an argument of the function `Minion_Task::set_domain_name('https://www.example.org')`.
+ - Using the site configuration: add the configuration parameter `minion_domain_name` to the `site.php` config file (`'minion_domain_name' => 'https://www.example.org'`) and call the method in your task without an argument `Minion_Task::set_domain_name()`.