meta_events 1.1.2 → 1.2.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NDEzNzUyNjM1MmVhOGM1YmRhODUzYTI3Njg0ZDk4Mjc3MDY3OWFjYQ==
+    NzJiMzIzNTY1ZGVhZTQwZjFmYWE1YWM5NTY3YzRhYjMyNDMyZDgwYw==
   data.tar.gz: !binary |-
-    NjE4N2Q4MDc1YjFmNmM0MDUxZDEwYzA5NzQ5ODY2ZjNlMDQ1NTgyMA==
+    Y2FkY2IxOTdhNTFmODVhMTQ1YTk1ODUxNzViNDIxNGNkOGFhMTk5ZQ==
 SHA512:
   metadata.gz: !binary |-
-    NGY3ZGFkYzU5MjE0MmI0YjZhNDRmZGRhMjM3NWM4MmJjNmNmZDlmMGY1MzQw
-    NzM5MWVhNzU0ODEyMTZmZDU1Y2NjZDZiMTRlYmNmZTNjMDFkMmMwMGIzMWUz
-    MjNmNTRkZDg4OTc5Mzg2ZGJjMTNiNzM0YjQyNWNhMjBhOTU3MDI=
+    MDA0ZjdjYWYwZTFiODRjZTdlNzk5YmJlOTc0ZGExZmQwOThlOWE0MWZjZWQ1
+    OTIzZjgxN2ZhY2M2OTM5YjVjMzUyY2I2NDE3ZWYwZDVjZTU0NmM1MTAyMWYx
+    NjBiNDFmMjhmMTljM2I5OTQ0ODRlNjA0MmIwZTA4MjljYmM5YjQ=
   data.tar.gz: !binary |-
-    ZDRhYzExNDUyOTA1ODFkMDFkYmY5ODllZDcxZGIyOWE2N2M0ZTFlN2ZjYWYz
-    NDAwNTY3Njk2YWUyMDA3MzhmMjMyMjQzMjBiZGM0ZmNiNGVhNjNmNjZkYzVh
-    Njc0ZWRmOTQwYWFlNDhkYzMyZTk2ZThlOWY5NTEyMGYyMTc2YTk=
+    YTU5Y2NlMmIyZWUxODIzODI4ZWMzZTk2OTM3ZTViMmY1OGM4MTBkYjU5OGEy
+    MjkzMmQwZjBkMWM3Y2ZjOTM4MmJiNWZiMGI0YWY3MjE5ZmJkMDk2NzdmNDgy
+    MTkwYzBmYThlNGQ4MDZiMTcyYjRhYjBiYzdhNmE0ZmNhZDczYWE=

data/.travis.yml

@@ -1,6 +1,6 @@
 rvm:
-    - "2.1.1"
+    - "2.1.2"
     - "2.0.0"
     - "1.9.3"
     - "1.8.7"
-    - "jruby-1.7.11"
+    - "jruby-1.7.12"

data/CHANGES.md

@@ -1,5 +1,18 @@
 # `meta_events` Changelog
 
+### 1.2.0, 30 June 2014
+
+* You can now customize the separator used in nested properties by passing (_e.g._) `:property_separator => ' '` to
+  the declaration of a `version` in the definition DSL. This allows you to get nested properties named things like
+  `user age`, `user name`, and so on, rather than `user_age` and `user_name`. (Thanks to
+  [Harm de Wit](https://github.com/harmdewit) for the idea.)
+* If you passed in a `Time` object to an `#event!` call, `meta_events` was calling `#utc` on it to normalize it to
+  UTC...and `Time#utc` (unbeknownst to me) _modifies_ its receiver, which is really bad. Now we call `Time#getutc`
+  instead, which doesn't do that. (Big shout-out to [Pete Sharum](https://github.com/petesharum) for catching and
+  fixing this, along with a spec for the fix!)
+* Added syntax highlighting to the README.
+* Bumped versions of Ruby we test against under Travis to the latest ones.
+
 ### 1.1.2, 29 May 2014
 
 * The `:external_name` on an Event was not correctly passed (instead of the fully-qualified event name) when using

data/CONTRIBUTORS.md

@@ -0,0 +1,17 @@
+# Contributors to `meta_events`
+
+Created and maintained by [Andrew Geweke](https://github.com/ageweke) under the support of the wonderful folks at
+[Swiftype, Inc.](https://swiftype.com/).
+
+Additional contributions by:
+
+* [Aaron Lerch](https://github.com/aaronlerch): Support for custom external event names, so that end users of
+  Mixpanel and other tools receiving data from `meta_events` can get nice, pretty, human-readable event names.
+* [Pete Sharum](https://github.com/petesharum): Fix for `Time` objects passed in; turns out `Time#utc` _modifies_ its
+  receiver, which is bad.
+* [Jesse Rusak](https://github.com/jder): doc typos and fixes for usage of `Rails.logger`.
+
+Inspiration for ideas by:
+
+* [Harm de Wit](https://github.com/harmdewit) for adding a configurable `properties_separator` on the `version` in the
+  events DSL.

data/README.md

@@ -4,16 +4,15 @@ and a powerful properties system that makes it easy to pass large numbers of con
 
 MetaEvents supports:
 
-* Ruby 1.8.7, 1.9.3, 2.0.0, 2.1.1, or JRuby 1.7.11
+* Ruby 1.8.7, 1.9.3, 2.0.0, 2.1.2, or JRuby 1.7.12
 
 These are, however, just the versions it's tested against; MetaEvents contains no code that should be at all
 particularly dependent on exact Ruby versions, and should be compatible with a broad set of versions.
 
 Current build status: ![Current Build Status](https://api.travis-ci.org/swiftype/meta_events.png?branch=master)
 
-Brought to you by the folks at [Swiftype](https://www.swiftype.com/). First version written by [Andrew Geweke](https://www.github.com/ageweke). Major contributions by:
-
-* [Aaron Lerch](https://github.com/aaronlerch): support for sending human-readable event names to Mixpanel via `:external_name` in the DSL on an Event, or via `:external_name` in `MetaEvents::Tracker#initialize` or `MetaEvents::Tracker.default_external_name`.
+Brought to you by the folks at [Swiftype](https://www.swiftype.com/). First version written by
+[Andrew Geweke](https://www.github.com/ageweke). For additional contributors, see [CONTRIBUTORS](CONTRIBUTORS.md).
 
 ### Background
 
@@ -61,13 +60,15 @@ First, let's declare an event that we want to fire. Create `config/meta_events.r
 configures this as your events file if you're using Rails; if not, use `MetaEvents::Tracker.default_definitions =` to
 set the path to whatever file you like):
 
-    global_events_prefix :ab
+```ruby
+global_events_prefix :ab
 
-    version 1, "2014-02-04" do
-      category :user do
-        event :signed_up, "2014-02-04", "user creates a brand-new account"
-      end
-    end
+version 1, "2014-02-04" do
+  category :user do
+    event :signed_up, "2014-02-04", "user creates a brand-new account"
+  end
+end
+```
 
 Let's walk through this:
 
@@ -95,25 +96,29 @@ that's signed in, which is almost always just the primary key from the `users` t
 currently signed in. We also pass it the IP address of the user (which can safely be `nil`); Mixpanel, for example,
 uses this for doing geolocation of users:
 
-    class ApplicationController < ActionController::Base
-      ...
-      def meta_events_tracker
-        @meta_events_tracker ||= MetaEvents::Tracker.new(current_user.try(:id), request.remote_ip)
-      end
-      ...
-    end
+```ruby
+class ApplicationController < ActionController::Base
+  ...
+  def meta_events_tracker
+    @meta_events_tracker ||= MetaEvents::Tracker.new(current_user.try(:id), request.remote_ip)
+  end
+  ...
+end
+```
 
 Now, from the controller, we can fire an event and pass a couple of properties:
 
-    class UsersController < ApplicationController
-      ...
-      def create
-        ...
-        meta_events_tracker.event!(:user, :signed_up, { :user_gender => @new_user.gender, :user_age => @new_user.age })
-        ...
-      end
-      ...
-    end
+```ruby
+class UsersController < ApplicationController
+  ...
+  def create
+    ...
+    meta_events_tracker.event!(:user, :signed_up, { :user_gender => @new_user.gender, :user_age => @new_user.age })
+    ...
+  end
+  ...
+end
+```
 
 We're just about all done; but, right now, the event isn't actually going anywhere, because we haven't configured any
 _event receivers_.
@@ -129,7 +134,9 @@ transparently), and `Time` objects.
 Fortunately, the [Mixpanel](https://github.com/mixpanel/mixpanel-ruby) Gem complies with this interface perfectly.
 So, in `config/environments/production.rb` (or any other file that loads before your first event gets fired):
 
-    MetaEvents::Tracker.default_event_receivers << Mixpanel::Tracker.new("0123456789abcdef")
+```ruby
+MetaEvents::Tracker.default_event_receivers << Mixpanel::Tracker.new("0123456789abcdef")
+```
 
 (where `0123456789abcdef` is actually your Mixpanel API token)
 
@@ -137,7 +144,9 @@ In our development environment, we may or may not want to include Mixpanel itsel
 Mixpanel event receiver, above); however, we might also want to print events to the console or some other file as
 they are fired. So, in `config/environments/development.rb`:
 
-    MetaEvents::Tracker.default_event_receivers << MetaEvents::TestReceiver.new
+```ruby
+MetaEvents::Tracker.default_event_receivers << MetaEvents::TestReceiver.new
+```
 
 This will print events as they are fired to your Rails log (_e.g._, `log/development.log`); you can pass an argument
 to the constructor of `TestReceiver` that's a `Logger`, an `IO` (_e.g._, `STDOUT`, `STDERR`, an open `File` object),
@@ -186,13 +195,17 @@ picks up these attributes, decodes them, and calls any function you want with th
 
 As an example, in a view, you simply convert:
 
-    <%= link_to("go here", user_awesome_path, :class => "my_class") %>
+```html+erb
+<%= link_to("go here", user_awesome_path, :class => "my_class") %>
+```
 
 ...to:
 
-    <%= meta_events_tracked_link_to("go here", user_awesome_path, :class => "my_class",
-                                    :meta_event => { :category => :user, :event => :awesome,
-                                                     :properties => { :color => 'green' } }) %>
+```html+erb
+<%= meta_events_tracked_link_to("go here", user_awesome_path, :class => "my_class",
+                                :meta_event => { :category => :user, :event => :awesome,
+                                                 :properties => { :color => 'green' } }) %>
+```
 
 (Not immediately obvious: the `:meta_event` attribute is just part of the `html_options` `Hash` that
 `link_to` accepts, not an additional parameter. `meta_events_tracked_link_to` accepts exactly the same parameters as
@@ -200,12 +213,16 @@ As an example, in a view, you simply convert:
 
 This automatically turns the generated HTML from:
 
-    <a href="/users/awesome" class="my_class">go here</a>
+```html
+<a href="/users/awesome" class="my_class">go here</a>
+```
 
 to something like this:
 
-    <a href="/users/awesome" class="my_class mejtp_trk" data-mejtp-event="ab1_user_awesome"
-       data-mejtp-prp="{&quot;ip&quot;:&quot;127.0.0.1&quot;,&quot;color&quot;:&quot;green&quot;,&quot;implicit_prop_1&quot;:&quot;someValue&quot;}">go here</a>
+```html
+<a href="/users/awesome" class="my_class mejtp_trk" data-mejtp-event="ab1_user_awesome"
+   data-mejtp-prp="{&quot;ip&quot;:&quot;127.0.0.1&quot;,&quot;color&quot;:&quot;green&quot;,&quot;implicit_prop_1&quot;:&quot;someValue&quot;}">go here</a>
+```
 
 `mejtp` stands for "MetaEvents JavaScript Tracking Prefix", and is simply a likely-unique prefix for these values.
 (You can change it with `MetaEvents::Helpers.meta_events_javascript_tracking_prefix 'foo'`.) `mejtp_trk` is the class
@@ -214,15 +231,19 @@ of the event, and a JSON-encoded string of all the properties (both implicit and
 
 Now, add this to a Javascript file in your application:
 
-    //= require meta_events
+```javascript
+//= require meta_events
+```
 
 And, finally, call something like this:
 
-    $(document).ready(function() {
-      MetaEvents.forAllTrackableElements(document, function(id, element, eventName, properties) {
-        mixpanel.track_links("#" + id, eventName, properties);
-      })
-    });
+```javascript
+$(document).ready(function() {
+  MetaEvents.forAllTrackableElements(document, function(id, element, eventName, properties) {
+    mixpanel.track_links("#" + id, eventName, properties);
+  })
+});
+```
 
 `MetaEvents.forAllTrackableElements` accepts a root element to start searching at, and a callback function. It finds
 all elements with class `mejtp_trk` on them underneath that element, extracts the event name and properties, and adds
@@ -248,48 +269,56 @@ extra work &mdash; otherwise, how would we get those properties? However, it's n
 First off, make sure you get this into your layout in a `<script>` tag somewhere &mdash; at the bottom of the page is
 perfectly fine:
 
-    <%= meta_events_frontend_events_javascript %>
+```html+erb
+<%= meta_events_frontend_events_javascript %>
+```
 
 This allows MetaEvents to pass event data properly from the backend to the frontend for any events you'll be firing.
 
 Now, as an example, let's imagine we implement a JavaScript game on our site, and want to fire events when the user
 wins, loses, or gets a new high score. First, let's define those in our DSL:
 
-    global_events_prefix :ab
+```ruby
+global_events_prefix :ab
 
-    version 1, "2014-02-11" do
-      category :jsgame do
-        event :won, "2014-02-11", "user won a game!"
-        event :lost, "2014-02-11", "user lost a game"
-        event :new_high_score, "2014-02-11", "user got a new high score"
-      end
-    end
+version 1, "2014-02-11" do
+  category :jsgame do
+    event :won, "2014-02-11", "user won a game!"
+    event :lost, "2014-02-11", "user lost a game"
+    event :new_high_score, "2014-02-11", "user got a new high score"
+  end
+end
+```
 
 Now, in whatever controller action renders the page that the game is on, we need to _register_ these events. This
 tells the front-end integration that we might fire them from the resulting page; it therefore embeds JavaScript in the
 page that defines the set of properties for those events, so that the front end has access to the data it needs:
 
-    class GameController < ApplicationController
-      def game
-        ...
-        meta_events_define_frontend_event(:jsgame, :won, { :winning_streak => current_winning_streak })
-        meta_events_define_frontend_event(:jsgame, :lost, { :losing_streak => current_losing_streak })
-        meta_events_define_frontend_event(:jsgame, :new_high_score, { :previous_high_score => current_high_score })
-        ...
-      end
-    end
+```ruby
+class GameController < ApplicationController
+  def game
+    ...
+    meta_events_define_frontend_event(:jsgame, :won, { :winning_streak => current_winning_streak })
+    meta_events_define_frontend_event(:jsgame, :lost, { :losing_streak => current_losing_streak })
+    meta_events_define_frontend_event(:jsgame, :new_high_score, { :previous_high_score => current_high_score })
+    ...
+  end
+end
+```
 
 This will allow us to make the following calls in the frontend, from our game code:
 
-    if (wonGame) {
-      MetaEvents.event('jsgame_won');
-    } else {
-      MetaEvents.event('jsgame_lost');
-    }
+```javascript
+if (wonGame) {
+  MetaEvents.event('jsgame_won');
+} else {
+  MetaEvents.event('jsgame_lost');
+}
 
-    if (currentScore > highScore) {
-      MetaEvents.event('jsgame_new_high_score', { score: currentScore });
-    }
+if (currentScore > highScore) {
+  MetaEvents.event('jsgame_new_high_score', { score: currentScore });
+}
+```
 
 What's happened here is that `meta_events_define_frontend_event` took the set of properties you passed, merged them
 with any implicit properties defined, and passed them to the frontend via the `meta_events_frontend_events_javascript`
@@ -304,21 +333,24 @@ event alias; they will all be merged together, along with the properties supplie
 If you need to be able to fire the exact same event with _different_ sets of properties from different places in a
 single page, you can alias the event using the `:name` property:
 
-    class GameController < ApplicationController
-      def game
-        ...
-        meta_events_define_frontend_event(:jsgame, :paused_game, { :while => :winning }, { :name => :paused_while_winning })
-        meta_events_define_frontend_event(:jsgame, :paused_game, { :while => :losing }, { :name => :paused_while_losing })
-        ...
-      end
-    end
-
+```ruby
+class GameController < ApplicationController
+  def game
     ...
-    if (winning) {
-      MetaEvents.event('paused_while_winning');
-    } else {
-      MetaEvents.event('paused_while_losing');
-    }
+    meta_events_define_frontend_event(:jsgame, :paused_game, { :while => :winning }, { :name => :paused_while_winning })
+    meta_events_define_frontend_event(:jsgame, :paused_game, { :while => :losing }, { :name => :paused_while_losing })
+    ...
+  end
+end
+```
+```javascript
+...
+if (winning) {
+  MetaEvents.event('paused_while_winning');
+} else {
+  MetaEvents.event('paused_while_losing');
+}
+```
 
 Both calls from the JavaScript will fire the event `ab1_jsgame_paused_game`, but one of them will pass
 `while: 'winning'`, and the other `while: 'losing'`.
@@ -382,21 +414,23 @@ going to want to pass properties about that user to any event that happens in th
 You could add these to every single call to `#event!`, but MetaEvents has a better way. When you create the
 `MetaEvents::Tracker` instance, you can define _implicit properties_. Let's add some now:
 
-    class ApplicationController < ActionController::Base
-      ...
-      def meta_events_tracker
-        implicit_properties = { }
-        if current_user
-          implicit_properties.merge!(
-            :user_gender => current_user.gender,
-            :user_age => current_user.age
-          )
-        end
-        @meta_events_tracker ||= MetaEvents::Tracker.new(current_user.try(:id), request.remote_ip,
-                                                        :implicit_properties => implicit_properties)
-      end
-      ...
+```ruby
+class ApplicationController < ActionController::Base
+  ...
+  def meta_events_tracker
+    implicit_properties = { }
+    if current_user
+      implicit_properties.merge!(
+        :user_gender => current_user.gender,
+        :user_age => current_user.age
+      )
     end
+    @meta_events_tracker ||= MetaEvents::Tracker.new(current_user.try(:id), request.remote_ip,
+                                                    :implicit_properties => implicit_properties)
+  end
+  ...
+end
+```
 
 Now, these properties will get passed on every event fired by this Tracker. (This is, in fact, the biggest
 consideration when deciding when and where you'll create new `MetaEvents::Tracker` instances: implicit properties are
@@ -410,31 +444,33 @@ properties that are defined on it. For example, imagine we have an event trigger
 another user. We have at least three entities: the 'from' user, the 'to' user, and the message itself. If we really
 want to instrument this event properly, we're going to want something like this:
 
-    meta_events_tracker.event!(:user, :sent_message, {
-      :from_user_country => from_user.country,
-      :from_user_state => from_user.state,
-      :from_user_postcode => from_user.postcode,
-      :from_user_city => from_user.city,
-      :from_user_language => from_user.language,
-      :from_user_referred_from => from_user.referred_from,
-      :from_user_gender => from_user.gender,
-      :from_user_age => from_user.age,
-
-      :to_user_country => to_user.country,
-      :to_user_state => to_user.state,
-      :to_user_postcode => to_user.postcode,
-      :to_user_city => to_user.city,
-      :to_user_language => to_user.language,
-      :to_user_referred_from => to_user.referred_from,
-      :to_user_gender => to_user.gender,
-      :to_user_age => to_user.age,
-
-      :message_sent_at => message.sent_at,
-      :message_type => message.type,
-      :message_length => message.length,
-      :message_language => message.language,
-      :message_attachments => message.attachments?
-      })
+```ruby
+meta_events_tracker.event!(:user, :sent_message, {
+  :from_user_country => from_user.country,
+  :from_user_state => from_user.state,
+  :from_user_postcode => from_user.postcode,
+  :from_user_city => from_user.city,
+  :from_user_language => from_user.language,
+  :from_user_referred_from => from_user.referred_from,
+  :from_user_gender => from_user.gender,
+  :from_user_age => from_user.age,
+
+  :to_user_country => to_user.country,
+  :to_user_state => to_user.state,
+  :to_user_postcode => to_user.postcode,
+  :to_user_city => to_user.city,
+  :to_user_language => to_user.language,
+  :to_user_referred_from => to_user.referred_from,
+  :to_user_gender => to_user.gender,
+  :to_user_age => to_user.age,
+
+  :message_sent_at => message.sent_at,
+  :message_type => message.type,
+  :message_length => message.length,
+  :message_language => message.language,
+  :message_attachments => message.attachments?
+  })
+```
 
 Needless to say, this kind of sucks. Either we're going to end up with a ton of duplicate, unmaintainable code, or
 we'll just cut back and only pass a few properties &mdash; greatly reducing the possibilities of our analytics
@@ -445,40 +481,44 @@ system.
 We can improve this situation by using a feature of MetaEvents: when properties are nested in sub-hashes, they get
 automatically expanded and their names prefixed by the outer hash key. So let's define a couple of methods on models:
 
-    class User < ActiveRecord::Base
-      def to_event_properties
-        {
-          :country => country,
-          :state => state,
-          :postcode => postcode,
-          :city => city,
-          :language => language,
-          :referred_from => referred_from,
-          :gender => gender,
-          :age => age
-        }
-      end
-    end
-
-    class Message < ActiveRecord::Base
-      def to_event_properties
-        {
-          :sent_at => sent_at,
-          :type => type,
-          :length => length,
-          :language => language,
-          :attachments => attachments?
-        }
-      end
-    end
+```ruby
+class User < ActiveRecord::Base
+  def to_event_properties
+    {
+      :country => country,
+      :state => state,
+      :postcode => postcode,
+      :city => city,
+      :language => language,
+      :referred_from => referred_from,
+      :gender => gender,
+      :age => age
+    }
+  end
+end
+
+class Message < ActiveRecord::Base
+  def to_event_properties
+    {
+      :sent_at => sent_at,
+      :type => type,
+      :length => length,
+      :language => language,
+      :attachments => attachments?
+    }
+  end
+end
+```
 
 Now, we can pass the exact same set of properties as the above example, by simply doing:
 
-    meta_events_tracker.event!(:user, :sent_message, {
-      :from_user => from_user.to_event_properties,
-      :to_user => to_user.to_event_properties,
-      :message => message.to_event_properties
-      })
+```ruby
+meta_events_tracker.event!(:user, :sent_message, {
+  :from_user => from_user.to_event_properties,
+  :to_user => to_user.to_event_properties,
+  :message => message.to_event_properties
+  })
+```
 
 **SO** much better.
 
@@ -488,7 +528,9 @@ And &mdash; tah-dah! &mdash; MetaEvents supports this syntax automatically. If y
 that object defines a method called `#to_event_properties`, then it will be called automatically, and replaced.
 Our code now looks like:
 
-    meta_events_tracker.event!(:user, :sent_message, { :from_user => from_user, :to_user => to_user, :message => message })
+```ruby
+meta_events_tracker.event!(:user, :sent_message, { :from_user => from_user, :to_user => to_user, :message => message })
+```
 
 ### How to Take the Most Advantage
 
@@ -515,14 +557,16 @@ Because there is such a wide variety of these systems available, MetaEvents does
 them &mdash; doing so would be a great deal of effort, and yet still unlikely to satisfy most users. Instead,
 MetaEvents makes it very easy to use any package you want:
 
-    class MyEventReceiver
-      def track(distinct_id, event_name, event_properties)
-        # Call Resque, Sidekiq, or anything else you want here; enqueue a job that, when run, will call:
-        #   Mixpanel::Tracker.new($my_mixpanel_api_key).track(distinct_id, event_name, event_properties)
-      end
-    end
+```ruby
+class MyEventReceiver
+  def track(distinct_id, event_name, event_properties)
+    # Call Resque, Sidekiq, or anything else you want here; enqueue a job that, when run, will call:
+    #   Mixpanel::Tracker.new($my_mixpanel_api_key).track(distinct_id, event_name, event_properties)
+  end
+end
 
-    MetaEvents::Tracker.default_event_receivers << MyEventReceiver.new
+MetaEvents::Tracker.default_event_receivers << MyEventReceiver.new
+```
 
 Voilà &mdash; asynchronous event tracking.
 
@@ -551,14 +595,16 @@ control, but that's a pain.)
 
 Rather than doing this, you can retire them:
 
-    global_events_prefix :ab
+```ruby
+global_events_prefix :ab
 
-    version 1, "2014-02-04" do
-      category :user do
-        event :logged_in_with_facebook, "2014-02-04", "user creates a brand-new account", :retired_at => "2014-06-01"
-        event :signed_up, "2014-02-04", "user creates a brand-new account"
-      end
-    end
+version 1, "2014-02-04" do
+  category :user do
+    event :logged_in_with_facebook, "2014-02-04", "user creates a brand-new account", :retired_at => "2014-06-01"
+    event :signed_up, "2014-02-04", "user creates a brand-new account"
+  end
+end
+```
 
 Given the above, trying to call `event!(:user, :logged_in_with_facebook)` will fail with an exception, because the
 event has been retired. (Note that, once again, the actual date passed to `:retired_at` is simply for record-keeping
@@ -572,15 +618,17 @@ of what things were in the past, as well as what they are today.
 You can also add notes to events. They must be tagged with the author and the time, and they can be very useful for
 documenting changes:
 
-    global_events_prefix :ab
+```ruby
+global_events_prefix :ab
 
-    version 1, "2014-02-04" do
-      category :user do
-        event :signed_up, "2014-02-04", "user creates a brand-new account" do
-          note "2014-03-17", "jsmith", "Moved sign-up button to the home page -- should increase signups significantly"
-        end
-      end
+version 1, "2014-02-04" do
+  category :user do
+    event :signed_up, "2014-02-04", "user creates a brand-new account" do
+      note "2014-03-17", "jsmith", "Moved sign-up button to the home page -- should increase signups significantly"
     end
+  end
+end
+```
 
 This allows you to record changes to events, as well as the events themselves.
 
@@ -635,28 +683,63 @@ override these external names.
 
 First, you can override them globally for all `MetaEvents::Tracker` instances:
 
-    MetaEvents::Tracker.default_external_name = lambda { |event| "#{event.category_name} #{event.name}" }
+```ruby
+MetaEvents::Tracker.default_external_name = lambda { |event| "#{event.category_name} #{event.name}" }
+```
 
 Second, you can override them for a specific `MetaEvents::Tracker` instance:
 
-    MetaEvents::Tracker.new(current_user.try(:id),
-                        request.remote_ip,
-                        :external_name => lambda { |event| "#{event.category_name} #{event.name}" }
-                       )
+```ruby
+MetaEvents::Tracker.new(current_user.try(:id),
+                    request.remote_ip,
+                    :external_name => lambda { |event| "#{event.category_name} #{event.name}" }
+                   )
+```
 
 Finally, you can override each event's external name in the events DSL:
 
-    global_events_prefix :ab
+```ruby
+global_events_prefix :ab
 
-    version 1, "2014-02-11" do
-      category :example_category do
-        event :example_event, "2014-02-11", "Example was exampled!", :external_name => 'ex. was ex.'
-      end
-    end
+version 1, "2014-02-11" do
+  category :example_category do
+    event :example_event, "2014-02-11", "Example was exampled!", :external_name => 'ex. was ex.'
+  end
+end
+```
 
 The order of precedence for determining the external event name is the DSL's `event :external_name => 'foo'`,
 `MetaEvents::Tracker.new`, `MetaEvents::Tracker.default_external_name`, built-in default.
 
+### Customizing the Nested Property Separator
+
+Similarly, while developers might be perfectly comfortable with (and even prefer) expanded properties named things
+like `user_age`, `user_name`, and so on, others might want a different separator (like a space character). When
+defining a version, you can set this, as follows:
+
+```ruby
+global_events_prefix :ab
+
+version 1, "2014-02-11", :property_separator => ' ' do
+  category :example_category do
+    event :example_event, "2014-02-11", "Example was exampled!"
+  end
+end
+```
+
+Now, assuming `@user` is a `User` object that responds to `#to_event_properties` (or is just a `Hash`):
+
+```ruby
+tracker.event!(:example_category, :example_event, :user => @user)
+```
+
+...you'll get properties named `user age`, `user name`, and so on, rather than `user_age` and `user_name`.
+
+Note that this is defined on the `version`, not the `category`, `event`, or even `#event!` call, because changing
+this is _a big deal_ &mdash; changing property names almost always breaks all kinds of analysis you might want to do
+with your analytics tool. However, the idea is that changing `version`s is a breaking change to your analytics
+system anyway, so you can certainly set it on a new `version` to something different.
+
 ## Contributing
 
 1. Fork it ( http://github.com/swiftype/meta_events/fork )

data/lib/meta_events/definition/version.rb

@@ -15,6 +15,8 @@ module MetaEvents
     class Version
       attr_reader :definition_set, :number, :introduced
 
+      DEFAULT_PROPERTY_SEPARATOR = "_"
+
       # Creates a new instance. +definition_set+ is the MetaEvents::Definition::DefinitionSet to which this Version belongs;
       # +number+ is an integer telling you, well, which version this is -- it must be unique within the DefinitionSet.
       # +introduced+ is a String that must be parseable using Time.parse; this should be the date (and time, if you
@@ -43,9 +45,10 @@ module MetaEvents
         @introduced = Time.parse(introduced)
         @categories = { }
 
-        options.assert_valid_keys(:retired_at)
+        options.assert_valid_keys(:retired_at, :property_separator)
 
         @retired_at = Time.parse(options[:retired_at]) if options[:retired_at]
+        @property_separator = options[:property_separator] || DEFAULT_PROPERTY_SEPARATOR
 
         instance_eval(&block) if block
       end
@@ -80,6 +83,23 @@ module MetaEvents
         @retired_at
       end
 
+      # Returns the string that should be used in property expansion to separate the two (or more) parts of the
+      # property name. For example, if you pass to +MetaEvents::Tracker#event!+ in +additional_properties+
+      # (or in the implicit properties taken by +MetaEvents::Tracker#initialize+) data that looks like
+      # <tt>:user => { :first_name => 'Fiona', :last_name => 'Darling' }</tt>, then, by default, you end up
+      # with properties named +user_first_name+ and +user_last_name+.
+      #
+      # If, instead, you set <tt>:property_separator => '~'</tt> on your Version, then you end up with properties
+      # named +user~first_name+ and +user~last_name+. This can be used to change property names to your liking.
+      #
+      # This is defined on the +Version+ so that you can change it if you redo your entire events system. It is not
+      # defined at a lower level, because having property names change is a _big deal_ -- it breaks data analysis
+      # in an analytics system, and so you generally should not change it unless you're changing lots of other stuff
+      # that would break analytics as well, like when defining an entire new Version.
+      def property_separator
+        @property_separator
+      end
+
       # Override #to_s, for a cleaner view.
       def to_s
         "<Version #{number}>"

data/lib/meta_events/tracker.rb

@@ -224,10 +224,10 @@ module MetaEvents
   #
   # There might be a situation where users performing analysis desire a friendlier name than the default.
   # The external name can be customized with a lambda (or any object that responds to <tt>#call(event)</tt>).
-  # To customize the external name for all MetaEvents::Tracker instances, 
+  # To customize the external name for all MetaEvents::Tracker instances,
   # specify <tt>MetaEvents::Tracker.default_external_name = lambda { |event| "custom event name" }</tt>.
-  # 
-  # To customize the external name for a specific MetaEvents::Tracker instance, pass the lambda 
+  #
+  # To customize the external name for a specific MetaEvents::Tracker instance, pass the lambda
   # in the constructor, for example:
   # <tt>MetaEvents::Tracker.new(current_user.id, request.remote_ip, :external_name => lambda {|e| "#{e.full_name}_CUSTOM" })</tt>
   #
@@ -333,7 +333,7 @@ module MetaEvents
     #                        with every event fired from this Tracker. This can use the hash-merge and object syntax
     #                        (#to_event_properties) documented above. Any properties explicitly passed with an event
     #                        that have the same name as these properties will override these properties for that event.
-    # [:external_name] If present, this should be a lambda that takes a single argument and returns a string, or an 
+    # [:external_name] If present, this should be a lambda that takes a single argument and returns a string, or an
     #                  object that responds to call(event). If +:external_name+ is not provided, it will use the
     #                  default configured for the MetaEvents::Tracker class.
     def initialize(distinct_id, ip, options = { })
@@ -351,11 +351,11 @@ module MetaEvents
       @definitions = ::MetaEvents::Definition::DefinitionSet.from(definitions)
       @version = options[:version] || self.class.default_version || raise(ArgumentError, "Must specify a :version")
       @external_name = options[:external_name] || self.class.default_external_name || raise(ArgumentError, "Must specify an :external_name")
-      raise ArgumentError, ":external_name option must respond to #call" unless @external_name.respond_to? :call
+      raise ArgumentError, ":external_name option must respond to #call" unless @external_name.respond_to?(:call)
 
       @implicit_properties = { }
-      self.class.merge_properties(@implicit_properties, { :ip => normalize_ip(ip).to_s }) if ip
-      self.class.merge_properties(@implicit_properties, options[:implicit_properties] || { })
+      self.class.merge_properties(@implicit_properties, { :ip => normalize_ip(ip).to_s }, property_separator) if ip
+      self.class.merge_properties(@implicit_properties, options[:implicit_properties] || { }, property_separator)
       self.distinct_id = distinct_id if distinct_id
 
       self.event_receivers = Array(options[:event_receivers] || self.class.default_event_receivers.dup)
@@ -411,7 +411,7 @@ module MetaEvents
       event = version_object.fetch_event(category_name, event_name)
 
       explicit = { }
-      self.class.merge_properties(explicit, additional_properties)
+      self.class.merge_properties(explicit, additional_properties, property_separator)
       properties = @implicit_properties.merge(explicit)
 
       event.validate!(properties)
@@ -440,6 +440,11 @@ module MetaEvents
       @definitions.fetch_version(version)
     end
 
+    # Returns the separator we should use when creating property names for nested properties.
+    def property_separator
+      version_object.property_separator
+    end
+
     # Accepts an IP address (or nil) in String, Integer, or IPAddr formats, and returns an IPAddr (or nil).
     def normalize_ip(ip)
       case ip
@@ -472,7 +477,7 @@ module MetaEvents
       #
       # +depth+ should be an integer, indicating how many layers of recursive calls we've invoked; this is simply to
       # prevent infinite recursion -- if this exceeds +MAX_DEPTH+, above, then an exception will be raised.
-      def merge_properties(target, source, prefix = nil, depth = 0)
+      def merge_properties(target, source, separator, prefix = nil, depth = 0)
         if depth > MAX_DEPTH
           raise "Nesting in EventTracker is too great; do you have a circular reference? " +
             "We reached depth: #{depth.inspect}; expanding: #{source.inspect} with prefix #{prefix.inspect} into #{target.inspect}"
@@ -497,10 +502,11 @@ module MetaEvents
 
           net_value = normalize_scalar_property_value(value)
           if net_value == :invalid_property_value
+            with_separator = "#{prefixed_key}#{separator}"
             if value.kind_of?(Hash)
-              merge_properties(target, value, "#{prefixed_key}_", depth + 1)
+              merge_properties(target, value, separator, with_separator, depth + 1)
             elsif value.respond_to?(:to_event_properties)
-              merge_properties(target, value.to_event_properties, "#{prefixed_key}_", depth + 1)
+              merge_properties(target, value.to_event_properties, separator, with_separator, depth + 1)
             else
               raise ArgumentError, "Event property #{prefixed_key.inspect} is not a valid scalar, Hash, or object that " +
                 "responds to #to_event_properties, but rather #{value.inspect} (#{value.class.name})."
@@ -527,7 +533,7 @@ module MetaEvents
         when Numeric then value
         when String then value.strip
         when Symbol then value.to_s.strip
-        when Time then value.utc.strftime("%Y-%m-%dT%H:%M:%S")
+        when Time then value.getutc.strftime("%Y-%m-%dT%H:%M:%S")
         when Array then
           out = value.map { |e| normalize_scalar_property_value(e) }
           out = :invalid_property_value if out.detect { |e| e == :invalid_property_value }

data/lib/meta_events/version.rb

@@ -1,3 +1,3 @@
 module MetaEvents
-  VERSION = "1.1.2"
+  VERSION = "1.2.0"
 end

data/spec/meta_events/definition/version_spec.rb

@@ -1,3 +1,5 @@
+require 'meta_events/definition/version'
+
 describe ::MetaEvents::Definition::Version do
   let(:definition_set) do
     out = double("definition_set")
@@ -38,6 +40,15 @@ describe ::MetaEvents::Definition::Version do
     instance.prefix.should == "gep3_"
   end
 
+  it "should set the property_separator to underscore by default" do
+    instance.property_separator.should == "_"
+  end
+
+  it "should allow setting the property separator to something else in the constructor" do
+    i2 = klass.new(definition_set, 3, "2014-02-03", :property_separator => 'Z')
+    i2.property_separator.should == "Z"
+  end
+
   context "with one category" do
     let(:category) do
       out = double("category")

data/spec/meta_events/tracker_spec.rb

@@ -1,3 +1,4 @@
+require "meta_events"
 require "active_support"
 require 'active_support/core_ext/numeric/time'
 require 'ipaddr'
@@ -19,6 +20,12 @@ describe MetaEvents::Tracker do
           event :quux, '2014-01-31', 'this is quux'
         end
       end
+
+      version 3, '2014-07-01', :property_separator => '~' do
+        category :bar do
+          event :baz, '2014-07-01', 'this is baz'
+        end
+      end
     end
   end
 
@@ -462,6 +469,18 @@ EOS
       expect_event('xy1_foo_bar', { 'user_name' => 'wilfred', 'user_hometown' => 'Fridley', 'location_city' => 'Edina', 'location_zip' => 55343 })
     end
 
+    it "should expand out nested properties using the #property_separator set on the version" do
+      i2 = new_instance(@distinct_id, nil, :definitions => definition_set, :version => 3, :implicit_properties => { :user => @user } )
+      i2.event!(:bar, :baz, { :location => { :city => 'Edina', :zip => 55343 } })
+      expect_event('xy3_bar_baz', { 'user~name' => 'wilfred', 'user~hometown' => 'Fridley', 'location~city' => 'Edina', 'location~zip' => 55343 })
+    end
+
+    it "should expand out nested properties from #to_event_properties using the #property_separator set on the version" do
+      i2 = new_instance(@distinct_id, nil, :definitions => definition_set, :version => 3, :implicit_properties => { :user => @user } )
+      i2.event!(:bar, :baz, { :location => tep_object(:city => 'Edina', :zip => 55343 ) })
+      expect_event('xy3_bar_baz', { 'user~name' => 'wilfred', 'user~hometown' => 'Fridley', 'location~city' => 'Edina', 'location~zip' => 55343 })
+    end
+
     it "should not allow firing a retired event" do
       expect { @instance.event!(:foo, :nolonger, { }) }.to raise_error(::MetaEvents::Definition::DefinitionSet::RetiredEventError)
     end
@@ -494,6 +513,13 @@ EOS
       expect(props).to eq('user_name' => 'bongo', 'user_hometown' => 'Fridley', 'baz_a' => 1, 'baz_b' => 'hoo')
     end
 
+    it "should respect the property_separator" do
+      i2 = new_instance(@distinct_id, nil, :definitions => definition_set, :version => 3, :implicit_properties => { :user => @user } )
+      expect(i2.effective_properties(:bar, :baz)[:properties]).to eq('user~name' => 'wilfred', 'user~hometown' => 'Fridley')
+      props = i2.effective_properties(:bar, :baz, :baz => { :a => 1, :b => 'hoo' }, :'user~name' => 'bongo')[:properties]
+      expect(props).to eq('user~name' => 'bongo', 'user~hometown' => 'Fridley', 'baz~a' => 1, 'baz~b' => 'hoo')
+    end
+
     it "should include no additional keys" do
       expect(@instance.effective_properties(:foo, :bar).keys.sort_by(&:to_s)).to eq(%w{distinct_id event_name external_name properties}.map(&:to_sym).sort_by(&:to_s))
     end
@@ -502,7 +528,7 @@ EOS
   describe "#merge_properties" do
     def expand(hash)
       out = { }
-      klass.merge_properties(out, hash, "", 0)
+      klass.merge_properties(out, hash, "Z", "", 0)
       out
     end
 
@@ -540,20 +566,20 @@ EOS
     end
 
     it "should recursively expand hashes" do
-      expect(expand({ :foo => { :bar => ' whatEVs '} })).to eq({ 'foo_bar' => 'whatEVs' })
+      expect(expand({ :foo => { :bar => ' whatEVs '} })).to eq({ 'fooZbar' => 'whatEVs' })
       expect { expand({ :foo => { :bar => [ 1, 2, /foo/ ] } }) }.to raise_error(ArgumentError)
     end
 
     it "should call #to_event_properties for any object, and recursively expand that" do
-      expect(expand(:baz => tep_object({ :foo => ' BaR '}))).to eq({ 'baz_foo' => 'BaR' })
-      expect(expand(:baz => tep_object({ :foo => { :bar => ' yo yo yo '} }))).to eq({ 'baz_foo_bar' => 'yo yo yo' })
+      expect(expand(:baz => tep_object({ :foo => ' BaR '}))).to eq({ 'bazZfoo' => 'BaR' })
+      expect(expand(:baz => tep_object({ :foo => { :bar => ' yo yo yo '} }))).to eq({ 'bazZfooZbar' => 'yo yo yo' })
 
       subsidiary = tep_object({ :bar => :baz })
-      expect(expand(:baz => tep_object({ :foo => subsidiary }))).to eq({ 'baz_foo_bar' => 'baz' })
+      expect(expand(:baz => tep_object({ :foo => subsidiary }))).to eq({ 'bazZfooZbar' => 'baz' })
     end
 
     it "should raise if it detects a property-name conflict" do
-      expect { expand(:foo_bar => :quux1, :foo => { :bar => :quux }) }.to raise_error(MetaEvents::Tracker::PropertyCollisionError)
+      expect { expand(:fooZbar => :quux1, :foo => { :bar => :quux }) }.to raise_error(MetaEvents::Tracker::PropertyCollisionError)
     end
   end
 
@@ -584,5 +610,37 @@ EOS
         expect(klass.normalize_scalar_property_value(input)).to eq(output)
       end
     end
+
+    it "should not modify passed values" do
+      t = Time.parse("2008-09-04 3:46:12 PM -08:00")
+      [
+        nil,
+        true,
+        false,
+        3,
+        42.5e+17,
+        3.months,
+        :foobar,
+        :' FooBar  ',
+        ' FooBar  ',
+        t,
+        [ "foo", :bar, 123, -9.45e+17, t, false, nil, true, "  BoNk " ],
+        /foobar/,
+        Object.new
+      ].each do |input|
+        expect { klass.normalize_scalar_property_value(input) }.to_not change { input }
+      end
+
+      nan = (0.0 / 0.0)
+      expect { klass.normalize_scalar_property_value(nan) }.to_not change { nan.nan? }
+
+      infinity = (1.0 / 0.0)
+      expect { klass.normalize_scalar_property_value(infinity) }.to_not change { infinity.infinite? }
+
+      neg_infinity = -(1.0 / 0.0)
+      expect { klass.normalize_scalar_property_value(neg_infinity) }.to_not change { neg_infinity.infinite? }
+
+      expect { klass.normalize_scalar_property_value(t) }.to_not change { t.zone }
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: meta_events
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrew Geweke
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-29 00:00:00.000000000 Z
+date: 2014-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -96,6 +96,7 @@ files:
 - .gitignore
 - .travis.yml
 - CHANGES.md
+- CONTRIBUTORS.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -140,7 +141,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Structured, documented, powerful event emitting library for Mixpanel and