Skip to content

Commit

Permalink
Doc fixes;
Browse files Browse the repository at this point in the history 
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).
  • Loading branch information
@boenrobot
boenrobot committed Oct 16, 2013
1 parent 68a0459 commit aa5d741
Show file tree
Hide file tree
Showing 6 changed files with 71 additions and 65 deletions.
7 changes: 2 additions & 5 deletions bin/roscon.php
View file
Expand Up @@ -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
Expand Down Expand Up @@ -319,11 +319,8 @@
);
}

$dislayedLength = $length > 9999999999
? '0x' . strtoupper(dechex($length))
: $length;
$details = str_pad(
$dislayedLength,
$length,
$c_columns['length'],
' ',
STR_PAD_LEFT
Expand Down
21 changes: 11 additions & 10 deletions src/PEAR2/Net/RouterOS/Client.php
View file
Expand Up @@ -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;

Expand Down Expand Up @@ -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)
{
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
*/
Expand Down
44 changes: 22 additions & 22 deletions src/PEAR2/Net/RouterOS/Communicator.php
View file
Expand Up @@ -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(
Expand All @@ -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)
Expand All @@ -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)
Expand 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()
*/
Expand Down
2 changes: 1 addition & 1 deletion src/PEAR2/Net/RouterOS/Query.php
View file
Expand Up @@ -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()
{
Expand Down
2 changes: 1 addition & 1 deletion src/PEAR2/Net/RouterOS/ResponseCollection.php
View file
Expand Up @@ -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;

Expand Down
60 changes: 34 additions & 26 deletions src/PEAR2/Net/RouterOS/Util.php
View file
Expand Up @@ -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.
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
*/
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
*
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down

0 comments on commit aa5d741

Please sign in to comment.