Doc fixes;

Added support for associative arrays at Util::escapeValue();
Adjusted the console's decoded length column to be 11 characters - the maximum protocol supported length (as opposed to the maximum RouterOS supported length).

Author: boenrobot

bin/roscon.php

@@ -207,7 +207,7 @@
     $c_sep = ' | ';
     $c_columns = array(
         'mode' => 4,
-        'length' => 10,
+        'length' => 11,
         'encodedLength' => 12
     );
     $c_columns['contents'] = $cmd->options['size'] - 1//row length
@@ -319,11 +319,8 @@
             );
         }
 
-        $dislayedLength = $length > 9999999999
-            ? '0x' . strtoupper(dechex($length))
-            : $length;
         $details = str_pad(
-            $dislayedLength,
+            $length,
             $c_columns['length'],
             ' ',
             STR_PAD_LEFT

src/PEAR2/Net/RouterOS/Client.php

@@ -44,17 +44,17 @@
 class Client
 {
     /**
-     * Used in {@link isRequestActive()} to limit search only to requests
-     * that have a callback.
+     * Used in {@link static::isRequestActive()} to limit search only to
+     * requests that have a callback.
      */
     const FILTER_CALLBACK = 1;
     /**
-     * Used in {@link isRequestActive()} to limit search only to requests
-     * that use the buffer.
+     * Used in {@link static::isRequestActive()} to limit search only to
+     * requests that use the buffer.
      */
     const FILTER_BUFFER = 2;
     /**
-     * Used in {@link isRequestActive()} to indicate no limit in search.
+     * Used in {@link static::isRequestActive()} to indicate no limit in search.
      */
     const FILTER_ALL = 3;
 
@@ -438,8 +438,9 @@ public function sendSync(Request $request)
      * 
      * @return ResponseCollection A collection of {@link Response} objects that
      *     haven't been passed to a callback function or previously extracted
-     *     with {@link extractNewResponses()}. Returns an empty collection when
-     *     $tag is set to NULL (responses can still be extracted).
+     *     with {@link static::extractNewResponses()}. Returns an empty
+     *     collection when $tag is set to NULL (responses can still be
+     *     extracted).
      */
     public function completeRequest($tag = null)
     {
@@ -590,7 +591,7 @@ public function getPendingRequestsCount()
      * to the "/cancel" command is highly reccomended, as it also updates the
      * counter of pending requests properly. Note that canceling a request also
      * removes any responses for it that were not previously extracted with
-     * {@link extractNewResponses()}.
+     * {@link static::extractNewResponses()}.
      * 
      * @param string $tag Tag of the request to cancel. Setting NULL will cancel
      *     all requests.
@@ -692,8 +693,8 @@ public function isStreamingResponses()
      * Closes the opened connection, even if it is a persistent one.
      * 
      * Closes the opened connection, even if it is a persistent one. Note that
-     * {@link extractNewResponses()} can still be used to extract responses
-     * collected prior to the closing.
+     * {@link static::extractNewResponses()} can still be used to extract
+     * responses collected prior to the closing.
      * 
      * @return bool TRUE on success, FALSE on failure.
      */

src/PEAR2/Net/RouterOS/Communicator.php

@@ -231,16 +231,16 @@ public static function iconvStream($in_charset, $out_charset, $stream)
      * Sets the default charset(s) for new connections.
      * 
      * @param mixed $charset     The charset to set. If $charsetType is
-     *     {@link CHARSET_ALL}, you can supply either a string to use for all
-     *     charsets, or an array with the charset types as keys, and the
+     *     {@link self::CHARSET_ALL}, you can supply either a string to use for
+     *     all charsets, or an array with the charset types as keys, and the
      *     charsets as values.
      * @param int   $charsetType Which charset to set. Valid values are the
      *     CHARSET_* constants. Any other value is treated as
-     *     {@link CHARSET_ALL}.
+     *     {@link self::CHARSET_ALL}.
      * 
      * @return string|array The old charset. If $charsetType is
-     *     {@link CHARSET_ALL}, the old values will be returned as an array with
-     *     the types as keys, and charsets as values.
+     *     {@link self::CHARSET_ALL}, the old values will be returned as an
+     *     array with the types as keys, and charsets as values.
      * @see setCharset()
      */
     public static function setDefaultCharset(
@@ -267,11 +267,11 @@ public static function setDefaultCharset(
      * 
      * @param int $charsetType Which charset to get. Valid values are the
      *     CHARSET_* constants. Any other value is treated as
-     *     {@link CHARSET_ALL}.
+     *     {@link self::CHARSET_ALL}.
      * 
      * @return string|array The current charset. If $charsetType is
-     *     {@link CHARSET_ALL}, the current values will be returned as an array
-     *     with the types as keys, and charsets as values.
+     *     {@link self::CHARSET_ALL}, the current values will be returned as an
+     *     array with the types as keys, and charsets as values.
      * @see setDefaultCharset()
      */
     public static function getDefaultCharset($charsetType)
@@ -284,23 +284,23 @@ public static function getDefaultCharset($charsetType)
      * Sets the charset(s) for this connection.
      * 
      * Sets the charset(s) for this connection. The specified charset(s) will be
-     * used for all future words. When sending, {@link CHARSET_LOCAL} is
-     * converted to {@link CHARSET_REMOTE}, and when receiving,
-     * {@link CHARSET_REMOTE} is converted to {@link CHARSET_LOCAL}. Setting
-     * NULL to either charset will disable charset convertion, and data will be
-     * both sent and received "as is".
+     * used for all future words. When sending, {@link self::CHARSET_LOCAL} is
+     * converted to {@link self::CHARSET_REMOTE}, and when receiving,
+     * {@link self::CHARSET_REMOTE} is converted to {@link self::CHARSET_LOCAL}.
+     * Setting  NULL to either charset will disable charset convertion, and data
+     * will be both sent and received "as is".
      * 
      * @param mixed $charset     The charset to set. If $charsetType is
-     *     {@link CHARSET_ALL}, you can supply either a string to use for all
-     *     charsets, or an array with the charset types as keys, and the
+     *     {@link self::CHARSET_ALL}, you can supply either a string to use for
+     *     all charsets, or an array with the charset types as keys, and the
      *     charsets as values.
      * @param int   $charsetType Which charset to set. Valid values are the
-     *     Communicator::CHARSET_* constants. Any other value is treated as
-     *     {@link CHARSET_ALL}.
+     *     CHARSET_* constants. Any other value is treated as
+     *     {@link self::CHARSET_ALL}.
      * 
      * @return string|array The old charset. If $charsetType is
-     *     {@link CHARSET_ALL}, the old values will be returned as an array with
-     *     the types as keys, and charsets as values.
+     *     {@link self::CHARSET_ALL}, the old values will be returned as an
+     *     array with the types as keys, and charsets as values.
      * @see setDefaultCharset()
      */
     public function setCharset($charset, $charsetType = self::CHARSET_ALL)
@@ -325,11 +325,11 @@ public function setCharset($charset, $charsetType = self::CHARSET_ALL)
      * 
      * @param int $charsetType Which charset to get. Valid values are the
      *     CHARSET_* constants. Any other value is treated as
-     *     {@link CHARSET_ALL}.
+     *     {@link self::CHARSET_ALL}.
      * 
      * @return string|array The current charset. If $charsetType is
-     *     {@link CHARSET_ALL}, the current values will be returned as an array
-     *     with the types as keys, and charsets as values.
+     *     {@link self::CHARSET_ALL}, the current values will be returned as an
+     *     array with the types as keys, and charsets as values.
      * @see getDefaultCharset()
      * @see setCharset()
      */

src/PEAR2/Net/RouterOS/Query.php

@@ -71,7 +71,7 @@ class Query
 
     /**
      * This class is not to be instantiated normally, but by static methods
-     * instead. Use {@link where()} to create an instance of it.
+     * instead. Use {@link static::where()} to create an instance of it.
      */
     private function __construct()
     {

src/PEAR2/Net/RouterOS/ResponseCollection.php

@@ -65,7 +65,7 @@ class ResponseCollection implements ArrayAccess, SeekableIterator, Countable
     /**
      * @var array An array with all distinct arguments across all
      *     {@link Response} objects. Created at the first call of
-     *     {@link getArgumentMap()}.
+     *     {@link static::getArgumentMap()}.
      */
     protected $argumentMap = null;
 

src/PEAR2/Net/RouterOS/Util.php

@@ -72,12 +72,12 @@ class Util implements Countable
      * determining the type in the same way RouterOS would determine it for a
      * literal.
      * 
-     * This method is intended to be the very opposite of {@link escapeValue()}.
-     * That is, results from that method, if given to this method, should
-     * produce equivalent results.
+     * This method is intended to be the very opposite of
+     * {@link static::escapeValue()}. hat is, results from that method, if
+     * given to this method, should produce equivalent results.
      * 
      * @param string $value The value to be parsed. Must be a literal of a
-     *     value, e.g. what {@link escapeValue()} will give you.
+     *     value, e.g. what {@link static::escapeValue()} will give you.
      * 
      * @return mixed Depending on RouterOS type detected:
      *     - "nil" or "nothing" - NULL.
@@ -196,8 +196,12 @@ public static function escapeValue($value)
                 break;
             }
             $result = '';
-            foreach ($value as $val) {
-                $result .= ';' . static::escapeValue($val);
+            foreach ($value as $key => $val) {
+                $result .= ';';
+                if (!is_int($key)) {
+                    $result .= static::escapeValue($key) . '=';
+                }
+                $result .= static::escapeValue($val);
             }
             $value = '{' . substr($result, 1) . '}';
             break;
@@ -332,7 +336,7 @@ public function changeMenu($newMenu = '')
      * @param array  $params An array of local variables to make available in
      *     the script. Variable names are array keys, and variable values are
      *     array values. Array values are automatically processed with
-     *     {@link escapeValue()}.
+     *     {@link static::escapeValue()}.
      *     Note that the script's (generated) name is always added as the
      *     variable "_", which you can overwrite from here.
      * @param string $policy Allows you to specify a policy the script must
@@ -366,13 +370,13 @@ public function exec(
      * cache may end up being out of date. By calling this method right before
      * targeting an item with a number, you can ensure number accuracy.
      * 
-     * Note that Util's {@link move()} and {@link remove()} methods
-     * automatically clear the cache before returning, while {@link add()} adds
-     * the new item's ID to the cache as the next number. A change in the menu
-     * also clears the cache.
+     * Note that Util's {@link static::move()} and {@link static::remove()}
+     * methods automatically clear the cache before returning, while
+     * {@link static::add()} adds the new item's ID to the cache as the next
+     * number. A change in the menu also clears the cache.
      * 
      * Note also that the cache is being rebuilt unconditionally every time you
-     * use {@link find()} with a callback.
+     * use {@link static::find()} with a callback.
      * 
      * @return $this The Util object itself.
      */
@@ -527,7 +531,8 @@ public function get($number, $value_name)
      * 
      * Zero or more arguments can be specified, each being a criteria.
      * If zero arguments are specified, enables all items.
-     * See {@link find()} for a description of what criteria are accepted.
+     * See {@link static::find()} for a description of what criteria are
+     * accepted.
      * 
      * @return ResponseCollection returns the response collection, allowing you
      *     to inspect errors, if any.
@@ -542,7 +547,8 @@ public function enable()
      * 
      * Zero or more arguments can be specified, each being a criteria.
      * If zero arguments are specified, disables all items.
-     * See {@link find()} for a description of what criteria are accepted.
+     * See {@link static::find()} for a description of what criteria are
+     * accepted.
      * 
      * @return ResponseCollection Returns the response collection, allowing you
      *     to inspect errors, if any.
@@ -557,7 +563,8 @@ public function disable()
      * 
      * Zero or more arguments can be specified, each being a criteria.
      * If zero arguments are specified, removes all items.
-     * See {@link find()} for a description of what criteria are accepted.
+     * See {@link static::find()} for a description of what criteria are
+     * accepted.
      * 
      * @return ResponseCollection Returns the response collection, allowing you
      *     to inspect errors, if any.
@@ -576,7 +583,7 @@ public function remove()
      * which match certain criteria.
      * 
      * @param mixed $numbers   Targeted items. Can be any criteria accepted by
-     *     {@link find()} or NULL in case the menu is one without items
+     *     {@link static::find()} or NULL in case the menu is one without items
      *     (e.g. "/system identity").
      * @param array $newValues An array with the names of each property to set
      *     as an array key, and the new value as an array value.
@@ -597,10 +604,10 @@ public function set($numbers, array $newValues)
     }
 
     /**
-     * Alias of {@link set()}
+     * Alias of {@link static::set()}
      * 
      * @param mixed $numbers   Targeted items. Can be any criteria accepted by
-     *     {@link find()}.
+     *     {@link static::find()}.
      * @param array $newValues An array with the names of each changed property
      *     as an array key, and the new value as an array value.
      * 
@@ -620,7 +627,7 @@ public function edit($numbers, array $newValues)
      * reserved word.
      * 
      * @param mixed  $numbers    Targeted items. Can be any criteria accepted
-     *     by {@link find()}.
+     *     by {@link static::find()}.
      * @param string $value_name The name of the value you want to unset.
      * 
      * @return ResponseCollection Returns the response collection, allowing you
@@ -681,11 +688,11 @@ public function add(array $values)
      * be a move command on that menu. If in doubt, check from a terminal.
      * 
      * @param mixed $numbers     Targeted items. Can be any criteria accepted
-     *     by {@link find()}.
+     *     by {@link static::find()}.
      * @param mixed $destination item before which the targeted items will be
-     *     moved to. Can be any criteria accepted by {@link find()}. If multiple
-     *     items match the criteria, the targeted items will move above the
-     *     first match.
+     *     moved to. Can be any criteria accepted by {@link static::find()}.
+     *     If multiple items match the criteria, the targeted items will move
+     *     above the first match.
      * 
      * @return ResponseCollection Returns the response collection, allowing you
      *     to inspect errors, if any.
@@ -708,8 +715,8 @@ public function move($numbers, $destination)
      * 
      * Counts items at the current menu. This executes a dedicated command
      * ("print" with a "count-only" argument) on RouterOS, which is why only
-     * queries are allowed as a criteria, in contrast with {@link find()},
-     * where numbers and callbacks are allowed also.
+     * queries are allowed as a criteria, in contrast with
+     * {@link static::find()}, where numbers and callbacks are allowed also.
      * 
      * @param Query $query A query to filter items by. Without it, all items
      *     are included in the count.
@@ -849,7 +856,8 @@ public function fileGetContents($filename, $tmpScriptName = null)
      * @param string $what What action to perform.
      * @param array  $args Zero or more arguments can be specified, each being
      *     a criteria. If zero arguments are specified, removes all items.
-     *     See {@link find()} for a description of what criteria are accepted.
+     *     See {@link static::find()} for a description of what criteria are
+     *     accepted.
      * 
      * @return ResponseCollection Returns the response collection, allowing you
      *     to inspect errors, if any.