From f28f2aabbfad66fb4e73db28d577e5d0b69cc973 Mon Sep 17 00:00:00 2001
From: Thomas Gelf <thomas@gelf.net>
Date: Thu, 25 Jun 2015 15:26:01 +0200
Subject: [PATCH] GraphiteUtil: cleanup, comments

---
 library/Graphite/GraphiteUtil.php | 53 +++++++++++++++++++++++++++++--
 1 file changed, 51 insertions(+), 2 deletions(-)

diff --git a/library/Graphite/GraphiteUtil.php b/library/Graphite/GraphiteUtil.php
index 1501715..120967e 100644
--- a/library/Graphite/GraphiteUtil.php
+++ b/library/Graphite/GraphiteUtil.php
@@ -2,10 +2,34 @@
 
 namespace Icinga\Module\Graphite;
 
+/**
+ * Utility class offering Graphite-related helpers
+ */
 class GraphiteUtil
 {
+    /**
+     * Regex pattern matching $varname
+     *
+     * @var string
+     */
     protected static $variablePattern = '/\$(\w+)/';
 
+    /**
+     * Extract a list of variable names from a given filter string
+     *
+     * Example
+     * -------
+     * <code>
+     * $pattern = 'base.$group.$hostname.*.value';
+     * echo implode(', ', GraphiteUtil::extractVariableNames($pattern));
+     *
+     * // Gives: group, hostname
+     * </code>
+     *
+     * @param  string $pattern Filter pattern
+     *
+     * @return array
+     */
     public static function extractVariableNames($pattern)
     {
         if (preg_match_all(self::$variablePattern, $pattern, $m)) {
@@ -15,7 +39,32 @@ class GraphiteUtil
         return array();
     }
 
-    public static function extractVars($string, $pattern)
+    /**
+     * Extracts a key/value list with all variables filled in a given metric
+     * for a given filter pattern
+     *
+     * Example
+     * -------
+     * <code>
+     * $pattern = 'base.$group.$hostname.*.value';
+     * $metric  = 'base.servers.www1.whatever.value';
+     * print_r(GraphiteUtil::extractVars($metric, $pattern));
+     * </code>
+     *
+     * Output
+     * ------
+     *     Array
+     *     (
+     *         [group] => servers
+     *         [hostname] => www1
+     *     )
+     *
+     * @param  string $metric  Metric string
+     * @param  string $pattern Filter pattern
+     *
+     * @return array
+     */
+    public static function extractVars($metric, $pattern)
     {
         $vars = array();
         $varnames = self::extractVariableNames($pattern);
@@ -27,7 +76,7 @@ class GraphiteUtil
             }
 
             $regex = '/' . implode('([^\.]+?)', $parts) . '/';
-            if (preg_match($regex, $string, $m)) {
+            if (preg_match($regex, $metric, $m)) {
                 array_shift($m);
                 $vars = array_combine($varnames, $m);
             }