pebbles-uid 0.0.2

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pebbles-uid.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Katrina Owen
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,211 @@
+# Pebbles::Uid
+
+Handle unique identifiers in the Pebblestack universe conveniently.
+
+## Unique Identifiers
+
+A valid Uid is in the format `genus[.species]:path[$oid]`.
+
+### Genus
+
+The genus is one or more dot-delimited labels.
+
+The first label uniquely identifies which pebble the resource originated from.
+
+Any secondary labels are grouped into a `species`, which identify sub-types within a given pebble.
+
+```
+  post.doc
+```
+
+Here the genus is `post`, and the species is `doc`.
+
+### Path
+
+The path is a dot-delimited set of labels. The first label represents the realm, and is required.
+
+A single resource may have multiple paths (and therefore multiple uids). For example:
+
+    ```
+       post.card:tourism.norway.fjords$42
+       post.card:tourism.norway.west-coast$42
+    ```
+
+### Oid
+
+The object identifier can be nearly any string, including another uid.
+
+The oid _MUST_ be unique for any genus and realm.
+
+There are currently two characters which cannot be included in an oid:
+
+`|` (pipe) and `,` (comma).
+
+Oid is optional when creating a new resource.
+
+## Queries
+
+### For one specific resource
+
+Across the pebblestack universe, you can query for a specific resource by passing a full Uid.
+
+In addition, the wildcard query `genus:realm.*$oid` will identify a single resource, e.g.:
+
+    ```
+      post.card:tourism.*$42
+    ```
+
+If a specific resource is targeted (i.e. genus and oid are both unambiguous), then realm is required.
+
+### For a collection of resources
+
+#### Asterisks
+
+The most permissive query consists of any genus in any path, with any oid (implied):
+
+    ```
+      *:*
+    ```
+
+This is the equivalent to:
+
+    ```
+      *:*$*
+    ```
+
+Queries may not be made across multiple realms at one time. If realm is not specified in the path, then it is assumed that the application verifies realm if necessary.
+
+In the context of a genus or a path, you may specify any number of labels and terminate with an asterisk, which means: zero or more labels follow. E.g.:
+
+    ```
+      post.*:tourism.europe.*
+    ```
+
+NOTE: wildcard queries on species is not yet supported.
+
+This will return things like:
+
+    ```
+      post:tourism.europe$123
+      post:tourism.europe.france.sightseeing$234
+      post.card:tourism.europe.mountains$345
+    ```
+
+Asterisks may not occur in mid-sequence. In other words, `post:tourism.*.food` will not be accepted.
+
+In the context of an oid, you either know the oid you want, or you don't. A query where oid is not specified at all is equivalent to an oid represented by an asterisk.
+
+#### Pipes
+
+A pipe signifies _or_.
+
+This can be used in genus at any position:
+
+    ```
+      unit|group:*
+    ```
+
+    ```
+      post.doc|card:*
+    ```
+
+In a path, this can be used in any position except the first, as the realm must be unambiguous.
+
+Thus:
+
+    ```
+      post:realm.label1|label2.something
+    ```
+
+The following is not allowed:
+
+    ```
+      post:realm1|realm2.*
+    ```
+
+If you wish to fetch a specific list of objects, you may use the pipe to delimit oids:
+
+    ```
+      post:realm.*$a|b|c|d|e|f|g
+    ```
+
+This is equivalent to the NOW deprecated comma-delimited uid query:
+
+    ```
+      post:realm.*$a,post:realm.*$b,post:realm.*$c,post:realm.*$d,post:realm.*$e,post:realm.*$f,post:realm.*$g,
+    ```
+
+NOTE: realm is required in this case, because each term in the list must refer to a single resource.
+
+#### Caret
+
+In both genus and paths, a caret indicates ancestry up to the specified point:
+
+    ```
+      post:realm.europe.^norway.fjords.food
+    ```
+
+This represents everything at the following locations:
+
+    ```
+      post:realm.europe
+      post:realm.europe.norway
+      post:realm.europe.norway.fjords
+      post:realm.europe.norway.fjords.food
+    ```
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pebbles-uid'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pebbles-uid
+
+## Usage
+
+### Identifying an existing resource
+
+    uid = Pebbles::Uid.new('post.card:tourism.norway.fjords$1234')
+
+    uid.realm
+    => "tourism"
+
+    uid.genus
+    => "post.card"
+
+    uid.species
+    => "card"
+
+    uid.path
+    => "tourism.norway.fjords"
+
+    uid.oid
+    => 1234
+
+    uid.to_s
+    => 'post.card:tourism.norway.fjords$1234'
+
+    uid.to_hash
+    => {'genus' => 'post.card', 'path_0' => 'tourism', 'path_1' => 'norway', 'path_2' => 'fjords', 'oid' => '1234'}
+
+    uid.to_hash(:verbose => true, :suffix => '')
+    => {'genus_0_' => 'post', 'genus_1_' => 'card', 'path_0_' => 'tourism', 'path_1_' => 'norway', 'path_2_' => 'fjords', 'oid_' => '1234'}
+
+    uid.to_hash(:verbose => true, :suffix => 'xyz', :genus => 'klass', :path => 'label' => :oid => 'id')
+    => {'klass_0_xyz' => 'post', 'klass_1_xyz' => 'card', 'label_0_xyz' => 'tourism', 'label_1_xyz' => 'norway', 'label_2_xyz' => 'fjords', 'id_xyz' => '1234'}
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"

data/lib/pebbles-uid.rb

@@ -0,0 +1,129 @@
+require "pebbles-uid/version"
+
+require 'pebbles-uid/query'
+require "pebbles-uid/conditions"
+require "pebbles-uid/labels"
+require "pebbles-uid/genus"
+require "pebbles-uid/path"
+require "pebbles-uid/oid"
+
+module Pebbles
+  class Uid
+
+    class << self
+
+      def query(s)
+        Pebbles::Uid::Query.new(s)
+      end
+
+      def parse(s)
+        /^(?<genus>.*):(?<path>[^\$]*)\$?(?<oid>.*)$/ =~ s
+        [genus, path, oid.empty? ? nil : oid]
+      end
+
+      def genus(s)
+        parse(s)[0]
+      end
+
+      def path(s)
+        parse(s)[1]
+      end
+
+      def oid(s)
+        parse(s)[2]
+      end
+
+      def valid_path?(path)
+        return false if path.empty?
+        Path.new(path).valid_with?(/^[a-z0-9_-]+$/)
+      end
+
+      def valid_genus?(genus)
+        return false if genus.empty?
+        Genus.new(genus).valid_with?(/^[a-z0-9_-]+$/)
+      end
+
+      def valid_oid?(oid)
+        return true if !oid || oid.empty?
+        !!(oid =~ /^[^,|]+$/)
+      end
+
+      def cache_key(uid)
+        genus, path, oid = parse(uid)
+        "#{genus}:#{Path.new(path).realm}.*$#{oid}"
+      end
+    end
+
+    attr_reader :genus, :path, :oid
+    def initialize(s)
+      @genus, @path, @oid = self.class.parse(s)
+      unless valid_genus?
+        raise ArgumentError.new("Invalid Uid: #{s}. Genus is invalid.")
+      end
+      unless valid_path?
+        raise ArgumentError.new("Invalid Uid: #{s}. Path is invalid.")
+      end
+
+      if oid == '*'
+        raise ArgumentError.new("Invalid Uid: #{s}. Cannot have wildcard oid.")
+      end
+
+      if genus.empty?
+        raise ArgumentError.new("Invalid Uid: #{s}. Genus is required.")
+      end
+      if path.empty?
+        raise ArgumentError.new("Invalid Uid: #{s}. Realm is required.")
+      end
+    end
+
+    def realm
+      @realm ||= path.split('.').first
+    end
+
+    def species
+      @species ||= genus_labels.species
+    end
+
+    def path_labels
+      @path_labels ||= Path.new(path)
+    end
+
+    def genus_labels
+      @genus_labels ||= Genus.new(genus)
+    end
+
+    def valid?
+      valid_genus? && valid_path? && valid_oid?
+    end
+
+    def valid_genus?
+      self.class.valid_genus?(genus)
+    end
+
+    def valid_path?
+      self.class.valid_path?(path)
+    end
+
+    def valid_oid?
+      self.class.valid_oid?(oid)
+    end
+
+    def oid?
+      !!oid
+    end
+
+    def to_s
+      s = "#{genus}:#{path}"
+      s << "$#{oid}" if oid
+      s
+    end
+
+    def parsed
+      [genus, path, oid].compact
+    end
+
+    def cache_key
+      "#{genus}:#{realm}.*$#{oid}"
+    end
+  end
+end

data/lib/pebbles-uid/conditions.rb

@@ -0,0 +1,73 @@
+# A key => value representation of sets of labels
+# used for elastic search or active record as indexing
+# or search conditions.
+module Pebbles
+  class Uid
+    class Conditions
+
+      NO_MARKER = Class.new
+
+      attr_reader :values, :name, :suffix, :stop, :verbose
+
+      def initialize(values, options = {})
+        @values = values
+        @name = options.fetch(:name) { 'label' }
+        @suffix = options.fetch(:suffix) { nil }
+        @verbose = options.fetch(:verbose) { true }
+        @stop = options.fetch(:stop) { NO_MARKER }
+        if values.last == '*'
+          @stop = NO_MARKER
+          @values.pop
+        end
+      end
+
+      alias :verbose? :verbose
+
+      def next
+        label(values.length)
+      end
+
+      def to_hash
+        return {label => values.join('.')} unless verbose?
+
+        collection = labelize
+        collection.merge!(stop_label) if use_stop_marker?
+        collection
+      end
+
+      def labelize
+
+        optional_part = false
+        labels = values.map do |label|
+          if label =~ /^\^/
+            label.gsub!(/^\^/, '')
+            optional_part = true
+          end
+
+          result = label.include?('|') ? label.split('|') : label
+          result = [result, nil].flatten if optional_part
+          result
+        end
+
+        collection = {}
+        labels.each_with_index do |value, i|
+          collection[label(i)] = value
+        end
+        collection
+      end
+
+      def label(i = nil)
+        [name, i, suffix].compact.join('_')
+      end
+
+      def stop_label
+        { label(values.length) => stop }
+      end
+
+      def use_stop_marker?
+        stop != NO_MARKER
+      end
+
+    end
+  end
+end

data/lib/pebbles-uid/genus.rb

@@ -0,0 +1,25 @@
+module Pebbles
+  class Uid
+    class Genus < Labels
+
+      def ambiguous?
+        value == '*' || values.empty? || wildcard?
+      end
+
+      def species
+        return if size <= 1
+
+        tail.join('.')
+      end
+
+      def species?
+        species != '*'
+      end
+
+      def to_hash(options = {})
+        super({:verbose => false, :name => 'genus'}.merge(options))
+      end
+
+    end
+  end
+end

data/lib/pebbles-uid/labels.rb

@@ -0,0 +1,45 @@
+module Pebbles
+  class Uid
+    class Labels
+
+      attr_reader :values, :prefix
+      def initialize(*values)
+        @values = values.flatten.compact.map {|v| v.split('.') }.flatten
+      end
+
+      def tail
+        values[1..-1]
+      end
+
+      def valid_with?(pattern)
+        !empty? && values.all? {|value| value[pattern] }
+      end
+
+      def size
+        values.size
+      end
+
+      def to_a
+        values
+      end
+
+      def to_s
+        values.join('.')
+      end
+      alias :value :to_s
+
+      def empty?
+        values.empty?
+      end
+
+      def wildcard?
+        !!(value =~ /[\*\|\^]/)
+      end
+
+      def to_hash(options = {})
+        Conditions.new(values, options).to_hash
+      end
+
+    end
+  end
+end

data/lib/pebbles-uid/oid.rb

@@ -0,0 +1,29 @@
+module Pebbles
+  class Uid
+
+    class Oid < Labels
+
+      def ambiguous?
+        value == '*' || value.empty?
+      end
+
+      def empty?
+        value.empty?
+      end
+
+      def multiple?
+        !!(value =~ /[\|]/)
+      end
+
+      def wildcard?
+        value == '*' || multiple?
+      end
+
+      def to_hash(options = {})
+        options.delete(:verbose)
+        super({:verbose => false, :name => 'oid'}.merge(options))
+      end
+
+    end
+  end
+end

data/lib/pebbles-uid/path.rb

@@ -0,0 +1,20 @@
+module Pebbles
+  class Uid
+    class Path < Labels
+
+      def realm
+        values.first
+      end
+
+      def realm?
+        return false if realm == '*'
+        !!realm
+      end
+
+      def to_hash(options = {})
+        super({:name => 'path'}.merge(options))
+      end
+
+    end
+  end
+end

data/lib/pebbles-uid/query.rb

@@ -0,0 +1,89 @@
+module Pebbles
+  class Uid
+    class Query
+
+      attr_reader :term, :terms, :genus, :path, :oid
+      def initialize(term)
+        @term = term
+
+        if wildcard_query?
+          @terms = [term]
+          @genus, @path, @oid = Pebbles::Uid.parse(term)
+        else
+          @terms = extract_terms
+        end
+      end
+
+      def for_one?
+        !wildcard_query? && terms.size == 1
+      end
+
+      def list?
+        terms.size != 1
+      end
+
+      def collection?
+        wildcard_query?
+      end
+
+      def path?
+        @path && @path.split('.').reject {|s| s == '*'}.length > 0
+      end
+
+      def genus?
+        @genus && @genus != '*'
+      end
+
+      def species?
+        !!Genus.new(genus).species
+      end
+
+      def species
+        Genus.new(genus).species
+      end
+
+      def oid?
+        !!@oid && @oid != '*'
+      end
+
+      def cache_keys
+        terms.map { |t| Pebbles::Uid.cache_key(t) }
+      end
+
+      private
+
+      def wildcard_query?
+        return false if term.include?(',')
+        species, _, oid = Pebbles::Uid.parse(term)
+        return true if Genus.new(species).wildcard?
+        return true if oid.nil? || oid.empty? || oid == '*'
+        false
+      end
+
+      def extract_terms
+        term.split(',').map do |uid|
+          species, path, oid = Pebbles::Uid.parse(uid)
+          species_labels = Genus.new(species)
+          path_labels = Path.new(path)
+          oid_box = Oid.new(oid)
+
+          raise ArgumentError.new('Realm must be specified') unless path_labels.realm?
+          raise ArgumentError.new('Genus must unambiguous') if species_labels.ambiguous?
+          raise ArgumentError.new('Oid must be unambiguous') if oid_box.ambiguous?
+
+          @realm ||= path_labels.realm
+          raise ArgumentError.new('One realm at a time, please') if @realm != path_labels.realm
+
+          if oid_box.multiple?
+            oid.split('|').map do |s|
+              "#{species}:#{path}$#{s}"
+            end
+          else
+            uid
+          end
+        end.flatten
+      end
+
+    end
+  end
+end

data/lib/pebbles-uid/version.rb

@@ -0,0 +1,5 @@
+module Pebbles
+  class Uid
+    VERSION = "0.0.2"
+  end
+end

data/lib/pebbles-uid/wildcard.rb

@@ -0,0 +1,45 @@
+module Pebbles
+  class Uid
+    module Wildcard
+
+      class << self
+
+        def valid?(path)
+          stars_are_solitary?(path) && single_caret?(path) && pipes_are_interleaved?(path) && carets_are_leading?(path) && stars_are_terminating?(path)
+        end
+
+        # a.*.c passes
+        # a.*b.c does not
+        # A later rule ensures that * always falls at the end of a path
+        def stars_are_solitary?(path)
+          !path.split('.').any? {|s| s.match(/.+\*|\*.+/)}
+        end
+
+        # a.b|c.d passes
+        # a.|b.c does not
+        def pipes_are_interleaved?(path)
+          !path.split('.').any? {|s| s.match(/^\||\|$/)}
+        end
+
+        # a.^b.c passes
+        # a.^c.^d does not
+        def single_caret?(path)
+          path.split('.').select {|s| s.match(/\^/) }.size <= 1
+        end
+
+        # a.^b.c passes
+        # a.b^c.d does not
+        def carets_are_leading?(path)
+          !path.split('.').any? {|s| s.match(/.+\^|\^$/) }
+        end
+
+        # a.b.* passes
+        # *.b.c does not
+        def stars_are_terminating?(path)
+          path !~ /.*\*\.\w/
+        end
+
+      end
+    end
+  end
+end

data/lib/pebbles/uid.rb

@@ -0,0 +1 @@
+require 'pebbles-uid'

data/pebbles-uid.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/pebbles-uid/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Katrina Owen"]
+  gem.email         = ["katrina.owen@gmail.com"]
+  gem.description   = %q{Handle pebble UIDs conveniently.}
+  gem.summary       = %q{Unique identifiers in the Pebblestack universe, in the format species[.genus]:path$oid, where the path is a dot-delimited set of labels, the first of which (realm) is required.}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "pebbles-uid"
+  gem.require_paths = ["lib"]
+  gem.version       = Pebbles::Uid::VERSION
+
+  gem.add_development_dependency "rspec"
+end

data/spec/conditions_spec.rb

@@ -0,0 +1,55 @@
+require 'pebbles-uid/conditions'
+
+describe Pebbles::Uid::Conditions do
+
+  subject { Pebbles::Uid::Conditions.new(%w(a b c)) }
+
+  its(:to_hash) { should eq('label_0' => "a", 'label_1' => "b", 'label_2' => "c") }
+
+  describe "customized labels" do
+    subject { Pebbles::Uid::Conditions.new(%w(p r q), :name => 'dot', :suffix => '') }
+    its(:to_hash) { should eq('dot_0_' => 'p', 'dot_1_' => 'r', 'dot_2_' => 'q') }
+  end
+
+  it "has a non-verbose mode" do
+    uid = Pebbles::Uid::Conditions.new(%w(k l m), :name => 'stuff', :verbose => false)
+    uid.to_hash.should eq({'stuff' => 'k.l.m'})
+  end
+
+  specify "non-verbose still takes a suffix" do
+    uid = Pebbles::Uid::Conditions.new(%w(k l m), :name => 'stuff', :verbose => false, :suffix => 'xyz')
+    uid.to_hash.should eq({'stuff_xyz' => 'k.l.m'})
+  end
+
+  describe "with a stop label" do
+    subject { Pebbles::Uid::Conditions.new(%w(x y z), :stop => nil) }
+    its(:to_hash) {  should eq('label_0' => "x", 'label_1' => "y", 'label_2' => "z", 'label_3' => nil) }
+  end
+
+  describe "next label" do
+    subject { Pebbles::Uid::Conditions.new(%w(h j k l), :name => 'vim') }
+    its(:next) { should eq('vim_4') }
+  end
+
+  describe "with pipes" do
+    subject { Pebbles::Uid::Conditions.new(%w(a b|c d), :stop => nil) }
+    its(:to_hash) {  should eq('label_0' => "a", 'label_1' => ['b', 'c'], 'label_2' => "d", 'label_3' => nil) }
+  end
+
+  describe "with an asterisk" do
+    # ignores stop marker if it is terminated by an asterisk
+    subject { Pebbles::Uid::Conditions.new(%w(a b *), :stop => nil) }
+    its(:to_hash) {  should eq('label_0' => "a", 'label_1' => 'b') }
+  end
+
+  describe "with an asterisk" do
+    subject { Pebbles::Uid::Conditions.new(%w(a ^b c), :stop => nil) }
+    its(:to_hash) {  should eq('label_0' => "a", 'label_1' => ['b', nil], 'label_2' => ['c', nil], 'label_3' => nil) }
+  end
+
+  describe "complicated stuff" do
+    subject { Pebbles::Uid::Conditions.new(%w(a ^b|c d *), :stop => nil) }
+    its(:to_hash) {  should eq('label_0' => "a", 'label_1' => ['b', 'c', nil], 'label_2' => ['d', nil]) }
+  end
+
+end

data/spec/genus_spec.rb

@@ -0,0 +1,33 @@
+require 'pebbles-uid/labels'
+require 'pebbles-uid/conditions'
+require 'pebbles-uid/genus'
+
+describe Pebbles::Uid::Genus do
+
+  subject { Pebbles::Uid::Genus.new('unicorn') }
+
+  its(:to_s) { should eq('unicorn') }
+
+  its(:species) { should be_nil }
+  its(:to_hash) { should eq('genus' => 'unicorn') }
+
+  context "subtypes" do
+
+    subject { Pebbles::Uid::Genus.new('unicorn', 'dust', 'sparkles') }
+    its(:to_s) { should eq('unicorn.dust.sparkles') }
+    its(:species) { should eq('dust.sparkles') }
+    its(:to_hash) { should eq('genus' => 'unicorn.dust.sparkles') }
+
+    it "doesn't have a species if there's a wildcard" do
+      genus = Pebbles::Uid::Genus.new('unicorn.*')
+      genus.species?.should == false
+    end
+
+    it "can customize the hash" do
+      subject.to_hash(:verbose => true).should eq('genus_0' => 'unicorn', 'genus_1' => 'dust', 'genus_2' => 'sparkles')
+    end
+  end
+
+  it { Pebbles::Uid::Genus.new('unicorn.horn').species.should eq('horn') }
+
+end

data/spec/labels_spec.rb

@@ -0,0 +1,37 @@
+require 'pebbles-uid/conditions'
+require 'pebbles-uid/labels'
+
+describe Pebbles::Uid::Labels do
+
+  subject { Pebbles::Uid::Labels.new('a.b.c') }
+  its(:to_s) { should eq('a.b.c') }
+  its(:to_a) { should eq(%w(a b c)) }
+  its(:to_hash) {  should eq('label_0' => "a", 'label_1' => "b", 'label_2' => "c") }
+  its(:tail) { should eq(%w(b c)) }
+
+  it "delegates to conditions" do
+    subject.to_hash(:name => 'thing', :verbose => false).should eq({'thing' => 'a.b.c'})
+  end
+
+  it "has a size" do
+    subject.size.should eq(3)
+  end
+
+  describe "alternate constructors" do
+    it { Pebbles::Uid::Labels.new('a', 'b', 'c').to_s.should eq('a.b.c') }
+    it { Pebbles::Uid::Labels.new(['a', 'b', 'c']).to_s.should eq('a.b.c') }
+  end
+
+  # Not certain where I want to deal with invalid wildcard paths yet.
+  context "wildcards" do
+    specify { Pebbles::Uid::Labels.new('a.*').wildcard?.should == true }
+    specify { Pebbles::Uid::Labels.new('a.b|c').wildcard?.should == true }
+    specify { Pebbles::Uid::Labels.new('a.^b.c').wildcard?.should == true }
+  end
+
+  context "validation" do
+    it { subject.valid_with?(/[0-9]/).should == false }
+    it { subject.valid_with?(/[a-z]/).should == true }
+  end
+
+end

data/spec/oid_spec.rb

@@ -0,0 +1,12 @@
+require 'pebbles-uid/labels'
+require 'pebbles-uid/oid'
+
+describe Pebbles::Uid::Oid do
+
+  describe "wildcard" do
+    specify { Pebbles::Uid::Oid.new('*').wildcard?.should == true }
+    specify { Pebbles::Uid::Oid.new('star*star').wildcard?.should == false }
+    specify { Pebbles::Uid::Oid.new('abc|xyz').wildcard?.should == true }
+  end
+
+end

data/spec/path_spec.rb

@@ -0,0 +1,24 @@
+require 'pebbles-uid/conditions'
+require 'pebbles-uid/labels'
+require 'pebbles-uid/path'
+
+describe Pebbles::Uid::Path do
+
+  subject { Pebbles::Uid::Path.new('magical', 'forrest', 'clearing') }
+
+  its(:realm) { should eq('magical') }
+  its(:realm?) { should == true }
+  its(:to_s) { should eq('magical.forrest.clearing') }
+  its(:to_a) { should eq(%w(magical forrest clearing)) }
+  its(:to_hash) { should eq({'path_0' => 'magical', 'path_1' => 'forrest', 'path_2' => 'clearing'}) }
+  its(:wildcard?) { should == false }
+
+  it "can customize the hash" do
+    subject.to_hash(:name => 'label').should eq({'label_0' => 'magical', 'label_1' => 'forrest', 'label_2' => 'clearing'})
+  end
+
+  specify "wildcard realm" do
+    Pebbles::Uid::Path.new('*').realm?.should == false
+  end
+
+end

data/spec/query_spec.rb

@@ -0,0 +1,128 @@
+require 'pebbles-uid'
+
+describe Pebbles::Uid::Query do
+
+  context "for a single resource" do
+    let(:term) { "post:area51$abc" }
+    subject { Pebbles::Uid::Query.new(term) }
+
+    its(:term) { should == term }
+
+    its(:for_one?) { should == true }
+    its(:list?) { should == false }
+    its(:collection?) { should == false }
+    its(:cache_keys) { should eq(['post:area51.*$abc']) }
+
+    it "handles a wildcard path if realm is given" do
+      query = Pebbles::Uid::Query.new('post:area51.*$abc')
+      query.for_one?.should == true
+    end
+
+    it "ignores crazy wildcard stuff in the path" do
+      query = Pebbles::Uid::Query.new("post:area51.^a.b.c.*|d$abc")
+      query.for_one?.should == true
+    end
+
+    it "bails without realm" do
+      ->{ Pebbles::Uid::Query.new('post:*$abc') }.should raise_error(ArgumentError)
+      ->{ Pebbles::Uid::Query.new('post:$abc') }.should raise_error(ArgumentError)
+    end
+  end
+
+  context "for a list of resources" do
+    let(:term) { "post:area51$abc,post:area51$xyz" }
+    subject { Pebbles::Uid::Query.new(term) }
+
+    its(:for_one?) { should == false }
+    its(:list?) { should == true }
+    its(:collection?) { should == false }
+
+    its(:cache_keys) { should eq(['post:area51.*$abc', 'post:area51.*$xyz']) }
+
+    it "handles a pipe-delimited list of oids" do
+      query = Pebbles::Uid::Query.new("post:area51$abc|xyz")
+      query.terms.should eq(['post:area51$abc', 'post:area51$xyz'])
+    end
+
+    it "ignores crazy wildcard stuff in the path" do
+      query = Pebbles::Uid::Query.new("post:area51.^a.b.c.*|d$abc|xyz")
+      query.list?.should == true
+      query.cache_keys.should eq(['post:area51.*$abc', 'post:area51.*$xyz'])
+    end
+
+    it "bails without realm" do
+      ->{ Pebbles::Uid::Query.new('post:*$abc,post:*$xyz') }.should raise_error(ArgumentError)
+    end
+
+    it "must have only one realm" do
+      ->{ Pebbles::Uid::Query.new('post:area51$abc,post:area52$xyz') }.should raise_error(ArgumentError)
+    end
+
+    it "bails with unspecific genus" do
+      ->{ Pebbles::Uid::Query.new('post.*:area51$abc,post:area51$xyz') }.should raise_error(ArgumentError)
+    end
+
+    it "bails with unspecified oid" do
+      ->{ Pebbles::Uid::Query.new('post:area51$*,post:area51$xyz') }.should raise_error(ArgumentError)
+    end
+  end
+
+  context "for a collection of resources" do
+    let(:term) { "post.*:area51.^a.b.c" }
+    subject { Pebbles::Uid::Query.new(term) }
+
+    its(:for_one?) { should == false }
+    its(:list?) { should == false }
+    its(:collection?) { should == true }
+
+    it "handles unspecific oids" do
+      Pebbles::Uid::Query.new('post:area51$*').collection?.should == true
+      Pebbles::Uid::Query.new('post:area51').collection?.should == true
+    end
+  end
+
+  describe "wildcard queries" do
+
+    context "everything" do
+      subject { Pebbles::Uid::Query.new('*:*') }
+
+      its(:genus?) { should == false }
+      its(:path?) { should == false }
+      its(:oid?) { should == false }
+    end
+
+    context "everything, with any oid" do
+      subject { Pebbles::Uid::Query.new('*:*$*') }
+
+      its(:genus?) { should == false }
+      its(:path?) { should == false }
+      its(:oid?) { should == false }
+    end
+
+    context "a genus" do
+      subject { Pebbles::Uid::Query.new('beast:*$*') }
+      its(:genus?) { should == true }
+      its(:genus) { should eq('beast') }
+      its(:species?) { should == false }
+    end
+
+    context "a species" do
+      subject { Pebbles::Uid::Query.new('beast.mythical.hairy:*$*') }
+      its(:species?) { should == true }
+      its(:species) { should eq('mythical.hairy') }
+    end
+
+    context "a path" do
+      subject { Pebbles::Uid::Query.new('*:area51.*') }
+      its(:path?) { should == true }
+    end
+
+    context "one oid" do
+      subject { Pebbles::Uid::Query.new('*:*$yak') }
+      its(:oid?) { should == true }
+      its(:oid) { should == 'yak' }
+    end
+
+  end
+
+end

data/spec/uid_spec.rb

@@ -0,0 +1,130 @@
+require 'pebbles-uid'
+
+describe Pebbles::Uid do
+
+  let(:uid) { 'post.card:tourism.norway.fjords$1234' }
+
+  describe "extracting single elements" do
+    specify { Pebbles::Uid.oid(uid).should eq('1234') }
+    specify { Pebbles::Uid.path(uid).should eq('tourism.norway.fjords') }
+    specify { Pebbles::Uid.genus(uid).should eq('post.card') }
+
+    describe "with missing oid" do
+      specify { Pebbles::Uid.oid('post:a.b.c').should eq(nil) }
+    end
+  end
+
+  describe "query" do
+    it "returns a query object" do
+      s = 'post:tourism.*$*'
+      Pebbles::Uid::Query.should_receive(:new).with s
+      query = Pebbles::Uid.query(s)
+    end
+  end
+
+  describe "requirements" do
+    it "must have a genus" do
+      ->{ Pebbles::Uid.new(':tourism.norway$1') }.should raise_error(ArgumentError)
+    end
+
+    it "must have a realm" do
+      ->{ Pebbles::Uid.new('post:$1') }.should raise_error(ArgumentError)
+    end
+
+    it "can skip the oid" do
+      ->{ Pebbles::Uid.new('post:tourism') }.should_not raise_error
+    end
+
+    it "doesn't accept wildcard genus" do
+      ->{ Pebbles::Uid.new('post.*:tourism$1') }.should raise_error(ArgumentError)
+      ->{ Pebbles::Uid.new('post|card:tourism$1') }.should raise_error(ArgumentError)
+      ->{ Pebbles::Uid.new('post.^b.c:tourism$1') }.should raise_error(ArgumentError)
+    end
+
+    it "doesn't accept wildcard paths" do
+      ->{ Pebbles::Uid.new('post:tourism.*$1') }.should raise_error(ArgumentError)
+      ->{ Pebbles::Uid.new('post:tourism|blogging$1') }.should raise_error(ArgumentError)
+      ->{ Pebbles::Uid.new('post:tourism.^b.c$1') }.should raise_error(ArgumentError)
+    end
+
+    it "doesn't accept wildcard oid" do
+      ->{ Pebbles::Uid.new('post:tourism$*') }.should raise_error(ArgumentError)
+    end
+  end
+
+  subject { Pebbles::Uid.new(uid) }
+
+  its(:to_s) { should eq(uid) }
+  its(:realm) { should eq('tourism') }
+  its(:genus) { should eq('post.card') }
+  its(:species) { should eq('card') }
+  its(:path) { should eq('tourism.norway.fjords') }
+  its(:oid) { should eq('1234') }
+  its(:oid?) { should == true }
+
+  its(:cache_key) { should eq('post.card:tourism.*$1234') }
+
+  context "when pending creation" do
+
+    let(:uid) { 'post.doc:universities.europe.norway' }
+    subject { Pebbles::Uid.new(uid) }
+
+    its(:to_s) { should eq(uid) }
+    its(:oid) { should be_nil }
+
+  end
+
+  context "paths" do
+    ["abc123", "abc.123", "abc.de-f.123"].each do |path|
+      specify "#{path} is a valid path" do
+        Pebbles::Uid.valid_path?(path).should == true
+      end
+    end
+
+    ["", ".", "..", "abc!"].each do |path|
+      specify "#{path} is not a valid path" do
+        Pebbles::Uid.valid_path?(path).should == false
+      end
+    end
+  end
+
+  context "genus" do
+    %w(- . _ 8).each do |char|
+      it "accepts #{char} in a genus" do
+        Pebbles::Uid.valid_genus?("uni#{char}corn").should == true
+      end
+    end
+
+    %w(! % { ? $).each do |char|
+      it "rejects #{char}" do
+        ->{ Pebbles::Uid.new("uni#{char}corn:mythical$1") }.should raise_error(ArgumentError)
+      end
+    end
+  end
+
+  context "oids" do
+    it "can be empty" do
+      Pebbles::Uid.new("beast:mythical").oid?.should == false
+    end
+
+    it "cannot contain pipes" do
+      Pebbles::Uid.valid_oid?("abc|xyz").should == false
+    end
+
+    it "cannot contain commas, either" do
+      Pebbles::Uid.valid_oid?("abc,xyz").should == false
+    end
+
+    it "can be empty" do
+      Pebbles::Uid.valid_oid?(nil).should == true
+    end
+
+    it "can be an empty string" do
+      Pebbles::Uid.valid_oid?("").should == true
+    end
+
+    it "is a black box" do
+      Pebbles::Uid.valid_oid?("holy+%^&*s!").should == true
+    end
+  end
+end

data/spec/wildcard_spec.rb

@@ -0,0 +1,53 @@
+require 'pebbles-uid/wildcard'
+
+describe Pebbles::Uid::Wildcard do
+
+  # This might not actually be necessary/relevant
+  specify "non-wildcard paths are valid" do
+    Pebbles::Uid::Wildcard.valid?('a.b.d').should == true
+  end
+
+  context "terminating asterisk representing entire label" do
+    [
+      '*', 'a.b.c.*', 'a.b|c.*', 'a.^b.c.*'
+    ].each do |path|
+      specify "#{path} is valid" do
+        Pebbles::Uid::Wildcard.valid?(path).should == true
+      end
+    end
+
+    ['*a', 'a*', '*.b', 'a.*.b'].each do |path|
+      specify "#{path} is invalid" do
+        Pebbles::Uid::Wildcard.valid?(path).should == false
+      end
+    end
+  end
+
+  context "pipes separate labels" do
+    ['a|b', 'a.b|c.d', 'a|b.c|d'].each do |path|
+      specify "#{path} is valid" do
+        Pebbles::Uid::Wildcard.valid?(path).should == true
+      end
+    end
+
+    ['|', 'a.|b', 'a.b|', 'a.|b.c', 'a.b|.c'].each do |path|
+      specify "#{path} is invalid" do
+        Pebbles::Uid::Wildcard.valid?(path).should == false
+      end
+    end
+  end
+
+  context "carets start an ancestry chain" do
+    ['^a', '^a.b', 'a.^b.c.*'].each do |path|
+      specify "#{path} is valid" do
+        Pebbles::Uid::Wildcard.valid?(path).should == true
+      end
+    end
+
+    ['^', '^.a', 'a^', 'a^b.c', '^a.^b'].each do |path|
+      specify "#{path} is invalid" do
+        Pebbles::Uid::Wildcard.valid?(path).should == false
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: pebbles-uid
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Katrina Owen
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-10-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: &70278976164860 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70278976164860
+description: Handle pebble UIDs conveniently.
+email:
+- katrina.owen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/pebbles-uid.rb
+- lib/pebbles-uid/conditions.rb
+- lib/pebbles-uid/genus.rb
+- lib/pebbles-uid/labels.rb
+- lib/pebbles-uid/oid.rb
+- lib/pebbles-uid/path.rb
+- lib/pebbles-uid/query.rb
+- lib/pebbles-uid/version.rb
+- lib/pebbles-uid/wildcard.rb
+- lib/pebbles/uid.rb
+- pebbles-uid.gemspec
+- spec/conditions_spec.rb
+- spec/genus_spec.rb
+- spec/labels_spec.rb
+- spec/oid_spec.rb
+- spec/path_spec.rb
+- spec/query_spec.rb
+- spec/uid_spec.rb
+- spec/wildcard_spec.rb
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.15
+signing_key: 
+specification_version: 3
+summary: Unique identifiers in the Pebblestack universe, in the format species[.genus]:path$oid,
+  where the path is a dot-delimited set of labels, the first of which (realm) is required.
+test_files:
+- spec/conditions_spec.rb
+- spec/genus_spec.rb
+- spec/labels_spec.rb
+- spec/oid_spec.rb
+- spec/path_spec.rb
+- spec/query_spec.rb
+- spec/uid_spec.rb
+- spec/wildcard_spec.rb