Merge pull request #19 from amco/group_helpers

Group helpers. Resolves #16.

Demo/librato-iOS Demo/LibratoDemoAppDelegate.m

@@ -22,6 +22,8 @@ - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(
     [eventTracker counterMetricExample];
     [eventTracker multipleMetricSubmissionExample];
     [eventTracker dictionaryCreationExample];
+    [eventTracker groupDictionaryExample];
+    [eventTracker groupContextExample];
     [eventTracker gaugeMetricExample];
 
     return YES;

Demo/librato-iOS Demo/LibratoDemoEventTracker.h

@@ -19,6 +19,8 @@
 - (void)counterMetricExample;
 - (void)multipleMetricSubmissionExample;
 - (void)dictionaryCreationExample;
+- (void)groupDictionaryExample;
+- (void)groupContextExample;
 - (void)gaugeMetricExample;
 
 @end

Demo/librato-iOS Demo/LibratoDemoEventTracker.m

@@ -81,6 +81,42 @@ - (void)dictionaryCreationExample
 }
 
 
+/*
+ Uses the group helper to build a number of metrics under a common namespace.
+ Different than setting the global namespace as this is only used for this group of metrics and the global namespace will automatically be applied to these as well.
+ Metrics will be created in the order they are entered in the dictionary hash.
+ 
+ The group prefix is the first argument and is joined to each metric named with a period.
+ The dictionary's key value is the metric name as an NSString and the value is an NSNumber value.
+ 
+ If the group is named "foo" and the first metric is named "bar" it will be submitted with the name "foo.bar"
+*/
+- (void)groupDictionaryExample
+{
+    NSDictionary *valueDict = @{
+                                @"repos": @32,
+                                @"stars": @331,
+                                @"friends": @172
+                                };
+    NSArray *metrics = [LibratoDemoEventTracker.sharedInstance groupNamed:@"user" valued:valueDict];
+    [LibratoDemoEventTracker.sharedInstance submit:metrics];
+}
+
+
+/*
+ Provides a Librato context that automatically namespaces any metrics created within that context.
+*/
+- (void)groupContextExample
+{
+    [LibratoDemoEventTracker.sharedInstance groupNamed:@"user" context:^(Librato *l) {
+        LibratoMetric *logins = [LibratoMetric metricNamed:@"logins" valued:@12 options:nil];
+        LibratoMetric *logouts = [LibratoMetric metricNamed:@"logouts" valued:@7 options:nil];
+        LibratoMetric *timeouts = [LibratoMetric metricNamed:@"timeouts" valued:@5 options:nil];
+        [l submit:@[logins, logouts, timeouts]];
+    }];
+}
+
+
 /*
  Creates a series of counter measurements and submits them as a gague metric
 */

librato-iOS/Librato.h

@@ -21,24 +21,31 @@ extern NSString *const LIBRATO_LOCALIZABLE;
 
 @interface Librato : NSObject
 
+
+typedef void (^LibratoMetricContext)(Librato *l);
+
+
 @property (nonatomic, strong) LibratoClient *client;
 @property (nonatomic, strong) NSString *prefix;
 
 + (NSDate *)minimumMeasureTime;
 
 - (instancetype)initWithEmail:(NSString *)email token:(NSString *)apiKey prefix:(NSString *)prefix;
 
+- (LibratoClient *)client;
+- (void)authenticateEmail:(NSString *)emailAddress APIKey:(NSString *)apiKey;
 - (NSString *)APIEndpoint;
 - (void)setAPIEndpoint:(NSString *)APIEndpoint;
-- (void)authenticateEmail:(NSString *)emailAddress APIKey:(NSString *)apiKey;
-- (LibratoClient *)client;
-- (LibratoConnection *)connection;
 - (NSString *)persistence;
 - (void)setPersistence:(NSString *)persistence;
 - (id<LibratoPersister>)persister;
+- (LibratoConnection *)connection;
 - (void)getMetric:(NSString *)name options:(NSDictionary *)options;
 - (void)getMeasurements:(NSString *)named options:(NSDictionary *)options;
 - (void)updateMetricsNamed:(NSString *)name options:(NSDictionary *)options;
 - (void)updateMetrics:(NSDictionary *)metrics;
+- (NSArray *)groupNamed:(NSString *)name valued:(NSDictionary *)values;
+- (NSArray *)groupNamed:(NSString *)name context:(LibratoMetricContext)context;
+- (void)submit;
 - (void)submit:(id)metrics;
 @end

librato-iOS/Librato.m

@@ -24,6 +24,7 @@ + (NSDate *)minimumMeasureTime
 }
 
 
+#pragma mark - Lifecycle
 - (instancetype)initWithEmail:(NSString *)email token:(NSString *)apiKey prefix:(NSString *)prefix
 {
     if((self = [super init]))
@@ -36,39 +37,35 @@ - (instancetype)initWithEmail:(NSString *)email token:(NSString *)apiKey prefix:
 }
 
 
-- (NSString *)APIEndpoint
-{
-    return self.client.APIEndpoint;
-}
-
-
-- (void)setAPIEndpoint:(NSString *)APIEndpoint
+- (LibratoClient *)client
 {
-    self.client.APIEndpoint = APIEndpoint;
+    if (!_client)
+    {
+        _client = LibratoClient.new;
+        _client.queue = [LibratoQueue.alloc initWithOptions:@{@"client": _client, @"prefix": self.prefix}];
+    }
+
+    return _client;
 }
 
 
+#pragma mark - Setup
 - (void)authenticateEmail:(NSString *)emailAddress APIKey:(NSString *)apiKey
 {
     [self.client authenticateEmail:emailAddress APIKey:apiKey];
 }
 
 
-- (LibratoClient *)client
+#pragma mark - Property accessors
+- (NSString *)APIEndpoint
 {
-    if (!_client)
-    {
-        _client = LibratoClient.new;
-        _client.queue = [LibratoQueue.alloc initWithOptions:@{@"client": _client, @"prefix": self.prefix}];
-    }
-
-    return _client;
+    return self.client.APIEndpoint;
 }
 
 
-- (LibratoConnection *)connection
+- (void)setAPIEndpoint:(NSString *)APIEndpoint
 {
-    return self.client.connection;
+    self.client.APIEndpoint = APIEndpoint;
 }
 
 
@@ -90,6 +87,12 @@ - (void)setPersistence:(NSString *)persistence
 }
 
 
+- (LibratoConnection *)connection
+{
+    return self.client.connection;
+}
+
+
 - (void)getMetric:(NSString *)name options:(NSDictionary *)options
 {
     [self.client getMetric:name options:options];
@@ -114,12 +117,44 @@ - (void)updateMetrics:(NSDictionary *)metrics
 }
 
 
+#pragma mark - Helpers
+- (NSArray *)groupNamed:(NSString *)name valued:(NSDictionary *)values
+{
+    __block NSMutableArray *metrics = NSMutableArray.array;
+    __block LibratoMetric *metric;
+    [values enumerateKeysAndObjectsUsingBlock:^(NSString *entry, NSNumber *value, BOOL *stop) {
+        metric = [LibratoMetric metricNamed:[NSString stringWithFormat:@"%@.%@", name, entry] valued:value options:nil];
+        [metrics addObject:metric];
+    }];
+
+    return metrics;
+}
+
+
+- (NSArray *)groupNamed:(NSString *)name context:(LibratoMetricContext)context
+{
+    NSString *originalPrefix = self.client.queue.prefix;
+    self.client.queue.prefix = (originalPrefix.length ? [NSString stringWithFormat:@"%@.%@", originalPrefix, name] : name);
+    context(self);
+    self.client.queue.prefix = originalPrefix;
+    [self submit];
+}
+
+
+#pragma mark - Submission
+- (void)submit
+{
+    [self.client.queue submit];
+}
+
+
 - (void)submit:(id)metrics
 {
     [self.client submit:metrics];
 }
 
 
+#pragma mark - Overrides
 - (NSString *)description
 {
     return [NSString stringWithFormat:@"<%@: %p, persister: %@, prefix: %@>", NSStringFromClass([self class]), self, self.client.persister, self.prefix];