Added ParserException, used in Script for parser errors on complex values;

Doc fix at Util::getAll().

Author: boenrobot

src/PEAR2/Net/RouterOS/ParserException.php

@@ -0,0 +1,42 @@
+<?php
+
+/**
+ * ~~summary~~
+ *
+ * ~~description~~
+ *
+ * PHP version 5
+ *
+ * @category  Net
+ * @package   PEAR2_Net_RouterOS
+ * @author    Vasil Rangelov <[email protected]>
+ * @copyright 2011 Vasil Rangelov
+ * @license   http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
+ * @version   GIT: $Id$
+ * @link      http://pear2.php.net/PEAR2_Net_RouterOS
+ */
+/**
+ * The namespace declaration.
+ */
+namespace PEAR2\Net\RouterOS;
+
+/**
+ * Base of this class.
+ */
+use DomainException;
+
+/**
+ * Exception thrown when a value can't be parsed properly.
+ *
+ * @category Net
+ * @package  PEAR2_Net_RouterOS
+ * @author   Vasil Rangelov <[email protected]>
+ * @license  http://www.gnu.org/copyleft/lesser.html LGPL License 2.1
+ * @link     http://pear2.php.net/PEAR2_Net_RouterOS
+ */
+class ParserException extends DomainException implements Exception
+{
+    const CODE_DATETIME = 1;
+    const CODE_DATEINTERVAL = 2;
+    const CODE_ARRAY = 3;
+}

src/PEAR2/Net/RouterOS/Script.php

@@ -98,22 +98,19 @@ public static function parseValue($value, DateTimeZone $timezone = null)
             return $value;
         }
 
-        $value = static::parseValueToArray($value, $timezone);
-        if (!is_string($value)) {
-            return $value;
-        }
-
-        $value = static::parseValueToDateInterval($value);
-        if (!is_string($value)) {
-            return $value;
-        }
-
-        $value = static::parseValueToDateTime($value, $timezone);
-        if (!is_string($value)) {
-            return $value;
+        try {
+            return static::parseValueToArray($value, $timezone);
+        } catch (ParserException $e) {
+            try {
+                return static::parseValueToDateInterval($value);
+            } catch (ParserException $e) {
+                try {
+                    return static::parseValueToDateTime($value, $timezone);
+                } catch (ParserException $e) {
+                    return static::parseValueToString($value);
+                }
+            }
         }
-
-        return static::parseValueToString($value);
     }
 
     /**
@@ -181,23 +178,22 @@ public static function parseValueToSimple($value)
      * @param DateTimeZone|null $timezone The timezone which the resulting
      *     DateTime object will use. Defaults to UTC.
      *
-     * @return string|DateTime Depending on RouterOS type detected:
+     * @return DateTime Depending on RouterOS type detected:
      *     - "date" (pseudo type; string in the form "M/j/Y") - a DateTime
      *         object with the specified date, at midnight UTC time (regardless
      *         of timezone provided).
      *     - "datetime" (pseudo type; string in the form "M/j/Y H:i:s") - a
-     *         DateTime object with the specified date and time.
-     *     - Unrecognized type - casted to a string, unmodified.
+     *         DateTime object with the specified date and time,
+     *         with the specified timezone.
+     * 
+     * @throws ParserException When the value is not of a recognized type.
      */
     public static function parseValueToDateTime(
         $value,
         DateTimeZone $timezone = null
     ) {
         $value = (string)$value;
-        if ('' === $value) {
-            return $value;
-        }
-        if (preg_match(
+        if ('' !== $value && preg_match(
             '#^
                 (?<mon>jan|feb|mar|apr|may|jun|jul|aug|sep|oct|nov|dec)
                 /
@@ -228,7 +224,10 @@ public static function parseValueToDateTime(
                 return $value;
             }
         }
-        return $value;
+        throw new ParserException(
+            'The supplied value can not be converted to a DateTime',
+            ParserException::CODE_DATETIME
+        );
     }
 
     /**
@@ -239,18 +238,14 @@ public static function parseValueToDateTime(
      * @param string $value The value to be parsed. Must be a literal of a
      *     value, e.g. what {@link static::escapeValue()} will give you.
      *
-     * @return string|DateInterval|DateTime Depending on RouterOS type detected:
-     *     - "time" - a {@link DateInterval} object.
-     *     - Unrecognized type - casted to a string, unmodified.
+     * @return DateInterval The value as a DateInterval object.
+     * 
+     * @throws ParserException When the value is not of a recognized type.
      */
     public static function parseValueToDateInterval($value)
     {
         $value = (string)$value;
-        if ('' === $value) {
-            return $value;
-        }
-
-        if (preg_match(
+        if ('' !== $value && preg_match(
             '/^
                 (?:(\d+)w)?
                 (?:(\d+)d)?
@@ -323,8 +318,10 @@ public static function parseValueToDateInterval($value)
             }
             //@codeCoverageIgnoreEnd
         }
-
-        return $value;
+        throw new ParserException(
+            'The supplied value can not be converted to DateInterval',
+            ParserException::CODE_DATEINTERVAL
+        );
     }
 
     /**
@@ -338,11 +335,11 @@ public static function parseValueToDateInterval($value)
      * @param DateTimeZone|null $timezone The timezone which any resulting
      *     DateTime object within the array will use. Defaults to UTC.
      *
-     * @return string|array Depending on RouterOS type detected:
-     *     - "array" - an array, with the and values processed recursively,
+     * @return array An array, with the keys and values processed recursively,
      *         the keys with {@link static::parseValueToSimple()},
-     *         and the values with {@link static::parseValue()}
-     *     - Unrecognized type - casted to a string, unmodified.
+     *         and the values with {@link static::parseValue()}.
+     * 
+     * @throws ParserException When the value is not of a recognized type.
      */
     public static function parseValueToArray(
         $value,
@@ -396,7 +393,10 @@ public static function parseValueToArray(
             }
             return $result;
         }
-        return $value;
+        throw new ParserException(
+            'The supplied value can not be converted to an array',
+            ParserException::CODE_DATETIME
+        );
     }
 
     /**

src/PEAR2/Net/RouterOS/Util.php

@@ -769,6 +769,8 @@ public function count($mode = COUNT_NORMAL, Query $query = null)
      *     allowing the results to be observed.
      *     If you need to use those arguments, use {@link static::newRequest()},
      *     and pass the resulting {@link Request} to {@link Client::sendAsync()}.
+     *     The "count-only" argument is also prohibited, as results from it
+     *     would not be consumable. Use {@link static::count()} for that.
      * @param Query|null                                      $query A query to
      *     filter items by.
      *     NULL to get all items.
@@ -778,7 +780,7 @@ public function count($mode = COUNT_NORMAL, Query $query = null)
      *     when there are no matching items. FALSE on failure.
      *
      * @throws NotSupportedException If $args contains prohibited arguments
-     *     ("follow" or "follow-only").
+     *     ("follow", "follow-only" or "count-only").
      */
     public function getAll(array $args = array(), Query $query = null)
     {
@@ -890,7 +892,7 @@ public function filePutContents($filename, $data, $overwrite = false)
             return Communicator::seekableStreamLength($data) == $fileSize;
         } else {
             return sprintf('%u', strlen((string)$data)) === $fileSize;
-        };
+        }
     }
 
     /**