pebbles-uid 0.0.8 → 0.0.9

data/README.md

@@ -4,21 +4,21 @@ Handle unique identifiers in the Pebblestack universe conveniently.
 
 ## Unique Identifiers
 
-A valid Uid is in the format `genus[.species]:path[$oid]`.
+A valid Uid is in the format `genus[.epiteth]:path[$oid]`.
 
-### Genus
+### Species
 
-The genus is one or more dot-delimited labels.
+The species is one or more dot-delimited labels.
 
-The first label uniquely identifies which pebble the resource originated from.
+The first label, the genus, uniquely identifies which pebble the resource originated from.
 
-Any secondary labels are grouped into a `species`, which identify sub-types within a given pebble.
+Any secondary labels are grouped into an `epiteth`, which identify sub-types within a given pebble.
 
 ```
 post.doc
 ```
 
-Here the genus is `post`, and the species is `doc`.
+Here the genus is `post`, and the epiteth is `doc`.
 
 ### Path
 
@@ -35,7 +35,7 @@ post.card:tourism.norway.west-coast$42
 
 The object identifier can be nearly any string, including another uid.
 
-The oid _MUST_ be unique for any genus and realm.
+The oid _MUST_ be unique for any species and realm.
 
 There are currently two characters which cannot be included in an oid:
 
@@ -49,19 +49,19 @@ Oid is optional when creating a new 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.:
+In addition, the wildcard query `species: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.
+If a specific resource is targeted (i.e. species 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):
+The most permissive query consists of any species in any path, with any oid (implied):
 
 ```
 *:*
@@ -75,7 +75,7 @@ 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.:
+In the context of a species 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.*
@@ -99,7 +99,7 @@ In the context of an oid, you either know the oid you want, or you don't. A quer
 
 A pipe signifies _or_.
 
-This can be used in genus at any position:
+This can be used in species at any position:
 
 ```
 unit|group:*
@@ -139,7 +139,7 @@ NOTE: realm is required in this case, because each term in the list must refer t
 
 #### Caret
 
-In both genus and paths, a caret indicates ancestry up to the specified point:
+In both species and paths, a caret indicates ancestry up to the specified point:
 
 ```
 post:realm.europe.^norway.fjords.food
@@ -178,10 +178,13 @@ uid = Pebbles::Uid.new('post.card:tourism.norway.fjords$1234')
 uid.realm
 => "tourism"
 
-uid.genus
+uid.species
 => "post.card"
 
-uid.species
+uid.genus
+=> "post"
+
+uid.epiteth
 => "card"
 
 uid.path
@@ -194,7 +197,7 @@ uid.to_s
 => 'post.card:tourism.norway.fjords$1234'
 
 uid.to_hash
-=> {'genus_0' => 'post', 'genus_1' => 'card', 'path_0' => 'tourism', 'path_1' => 'norway', 'path_2' => 'fjords', 'oid' => '1234'}
+=> {'species_0' => 'post', 'species_1' => 'card', 'path_0' => 'tourism', 'path_1' => 'norway', 'path_2' => 'fjords', 'oid' => '1234'}
 ```
 
 ### Uid Queries
@@ -209,7 +212,7 @@ query.collection?
 => true
 
 query.to_hash
-=> {'genus_0' => 'post', 'genus_1' => 'card', 'path_0' => 'tourism', 'path_1' => ['norway', nil], ['fjords', 'mountains', nil]}
+=> {'species_0' => 'post', 'species_1' => 'card', 'path_0' => 'tourism', 'path_1' => ['norway', nil], ['fjords', 'mountains', nil]}
 ```
 
 ## TODO

data/lib/pebbles-uid.rb

@@ -1,8 +1,7 @@
 require "pebbles-uid/version"
 
 require 'pebbles-uid/wildcard'
-require 'pebbles-uid/parse'
-require 'pebbles-uid/cache_key'
+require 'pebbles-uid/class_methods'
 require 'pebbles-uid/query'
 require "pebbles-uid/conditions"
 require "pebbles-uid/labels"
@@ -11,56 +10,11 @@ require "pebbles-uid/oid"
 module Pebbles
   class Uid
 
-    class << self
-
-      def parse(s)
-        /^(?<genus>.*):(?<path>[^\$]*)\$?(?<oid>.*)$/ =~ s
-        [genus, path, oid.empty? ? nil : oid]
-      end
-
-      def build(genus, path, oid)
-        s = "#{genus}:#{path}"
-        s << "$#{oid}" if oid
-        s
-      end
-
-      def query(s, options = {})
-        Pebbles::Uid::Query.new(s, options)
-      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?
-        Labels.new(path).valid_with?(/^[a-z0-9_-]+$/)
-      end
-
-      def valid_genus?(genus)
-        return false if genus.empty?
-        Labels.new(genus).valid_with?(/^[a-z0-9_-]+$/)
-      end
-
-      def valid_oid?(oid)
-        return true if !oid || oid.empty?
-        !!(oid =~ /^[^,|]+$/)
-      end
-    end
-
-    attr_reader :genus, :path, :oid
+    attr_reader :species, :path, :oid
     def initialize(s)
-      @genus, @path, @oid = self.class.parse(s)
-      unless valid_genus?
-        raise ArgumentError.new("Invalid Uid: #{s}. Genus is invalid.")
+      @species, @path, @oid = self.class.parse(s)
+      unless valid_species?
+        raise ArgumentError.new("Invalid Uid: #{s}. Species is invalid.")
       end
       unless valid_path?
         raise ArgumentError.new("Invalid Uid: #{s}. Path is invalid.")
@@ -70,12 +24,21 @@ module Pebbles
         raise ArgumentError.new("Invalid Uid: #{s}. Cannot have wildcard oid.")
       end
 
-      if genus.empty?
-        raise ArgumentError.new("Invalid Uid: #{s}. Genus is required.")
+      if species.empty?
+        raise ArgumentError.new("Invalid Uid: #{s}. Species is required.")
       end
       if path.empty?
         raise ArgumentError.new("Invalid Uid: #{s}. Realm is required.")
       end
+
+    end
+
+    def epiteth
+      @epiteth ||= species.split('.')[1..-1].join('.')
+    end
+
+    def genus
+      @genus ||= species.split('.').first
     end
 
     def realm
@@ -83,23 +46,23 @@ module Pebbles
     end
 
     def species
-      @species ||= genus_labels.tail.join('.')
+      @species ||= species_labels.tail.join('.')
     end
 
     def path_labels
       @path_labels ||= Labels.new(path, :name => 'path')
     end
 
-    def genus_labels
-      @genus_labels ||= Labels.new(genus, :name => 'genus')
+    def species_labels
+      @species_labels ||= Labels.new(species, :name => 'species')
     end
 
     def valid?
-      valid_genus? && valid_path? && valid_oid?
+      valid_species? && valid_path? && valid_oid?
     end
 
-    def valid_genus?
-      self.class.valid_genus?(genus)
+    def valid_species?
+      self.class.valid_species?(species)
     end
 
     def valid_path?
@@ -115,21 +78,21 @@ module Pebbles
     end
 
     def to_s
-      Pebbles::Uid.build genus, path, oid
+      Pebbles::Uid.build species, path, oid
     end
 
     def parsed
-      [genus, path, oid].compact
+      [species, path, oid].compact
     end
 
     def to_hash
-      hash = genus_labels.to_hash.merge(path_labels.to_hash)
+      hash = species_labels.to_hash.merge(path_labels.to_hash)
       hash = hash.merge(:oid => oid) if oid?
       hash
     end
 
     def cache_key
-      "#{genus}:#{realm}.*$#{oid}"
+      "#{species}:#{realm}.*$#{oid}"
     end
 
   end

data/lib/pebbles-uid/class_methods.rb

@@ -0,0 +1,62 @@
+module Pebbles
+  class Uid
+    class << self
+
+      def parse(s)
+        /^(?<species>.*):(?<path>[^\$]*)\$?(?<oid>.*)$/ =~ s
+        [species, path, oid.empty? ? nil : oid]
+      end
+
+      def build(species, path, oid)
+        s = "#{species}:#{path}"
+        s << "$#{oid}" if oid
+        s
+      end
+
+      def query(s, options = {})
+        Pebbles::Uid::Query.new(s, options)
+      end
+
+      def cache_key(uid)
+        species, path, oid = parse(uid)
+        "#{species}:#{Labels.new(path).first}.*$#{oid}"
+      end
+
+      def species(s)
+        parse(s)[0]
+      end
+
+      def genus(s)
+        parse(s)[0].split('.').first
+      end
+
+      def epiteth(s)
+        parse(s)[0].split('.')[1..-1].join('.')
+      end
+
+      def path(s)
+        parse(s)[1]
+      end
+
+      def oid(s)
+        parse(s)[2]
+      end
+
+      def valid_path?(path)
+        return false if path.empty?
+        Labels.new(path).valid_with?(/^[a-z0-9_-]+$/)
+      end
+
+      def valid_species?(species)
+        return false if species.empty?
+        Labels.new(species).valid_with?(/^[a-z0-9_-]+$/)
+      end
+
+      def valid_oid?(oid)
+        return true if !oid || oid.empty?
+        !!(oid =~ /^[^,|]+$/)
+      end
+    end
+  end
+end
+

data/lib/pebbles-uid/query.rb

@@ -4,11 +4,11 @@ module Pebbles
 
       NO_MARKER = Class.new
 
-      attr_reader :term, :terms, :genus, :path, :oid,
-        :genus_name, :path_name, :suffix, :stop
+      attr_reader :term, :terms, :species, :path, :oid,
+        :species_name, :path_name, :suffix, :stop
       def initialize(term, options = {})
         @term = term
-        @genus_name = options.fetch(:genus) { 'genus' }
+        @species_name = options.fetch(:species) { 'species' }
         @path_name = options.fetch(:path) { 'path' }
         @suffix = options[:suffix]
         @stop = options.fetch(:stop) { NO_MARKER }
@@ -20,7 +20,7 @@ module Pebbles
         end
 
         if !list?
-          @genus, @path, @oid = Pebbles::Uid.parse(term)
+          @species, @path, @oid = Pebbles::Uid.parse(term)
         end
       end
 
@@ -47,16 +47,16 @@ module Pebbles
         @path && @path.split('.').reject {|s| s == '*'}.length > 0
       end
 
-      def genus?
-        @genus && @genus != '*'
+      def species?
+        @species && @species != '*'
       end
 
-      def species?
-        !genus_wrapper.tail.empty?
+      def epiteth?
+        !species_wrapper.tail.empty?
       end
 
-      def species
-        genus_wrapper.tail.join('.')
+      def epiteth
+        species_wrapper.tail.join('.')
       end
 
       def oid?
@@ -72,7 +72,7 @@ module Pebbles
           raise RuntimeError.new('Cannot compute a conditions hash for a list of uids')
         end
 
-        hash = genus_wrapper.to_hash.merge(path_wrapper.to_hash)
+        hash = species_wrapper.to_hash.merge(path_wrapper.to_hash)
         if oid?
           oid_key = ['oid', suffix].compact.join('_').to_sym
           hash = hash.merge(oid_key => oid)
@@ -86,13 +86,13 @@ module Pebbles
 
       private
 
-      def genus_wrapper
-        unless @genus_wrapper
-          options = {:name => genus_name, :suffix => suffix}
+      def species_wrapper
+        unless @species_wrapper
+          options = {:name => species_name, :suffix => suffix}
           options.merge!(:stop => stop) if use_stop_marker?
-          @genus_wrapper = Labels.new(genus, options)
+          @species_wrapper = Labels.new(species, options)
         end
-        @genus_wrapper
+        @species_wrapper
       end
 
       def path_wrapper
@@ -106,21 +106,21 @@ module Pebbles
 
       def wildcard_query?
         return false if term.include?(',')
-        genus, _, oid = Pebbles::Uid.parse(term)
-        return true if Labels.new(genus).wildcard?
+        species, _, oid = Pebbles::Uid.parse(term)
+        return true if Labels.new(species).wildcard?
         return true if oid.nil? || oid.empty? || oid == '*'
         false
       end
 
       def extract_terms
         term.split(',').map do |uid|
-          _genus, _path, _oid = Pebbles::Uid.parse(uid)
-          genus_labels = Labels.new(_genus)
+          _species, _path, _oid = Pebbles::Uid.parse(uid)
+          species_labels = Labels.new(_species)
           path_labels = Labels.new(_path)
           oid_box = Oid.new(_oid)
 
           raise ArgumentError.new('Realm must be specified') if path_labels.empty? || path_labels.first == '*'
-          raise ArgumentError.new('Genus must unambiguous') if genus_labels.ambiguous?
+          raise ArgumentError.new('Species must unambiguous') if species_labels.ambiguous?
           raise ArgumentError.new('Oid must be unambiguous') if oid_box.ambiguous?
 
           @realm ||= path_labels.first
@@ -128,7 +128,7 @@ module Pebbles
 
           if oid_box.multiple?
             _oid.split('|').map do |s|
-              "#{_genus}:#{_path}$#{s}"
+              "#{_species}:#{_path}$#{s}"
             end
           else
             uid

data/lib/pebbles-uid/version.rb

@@ -1,5 +1,5 @@
 module Pebbles
   class Uid
-    VERSION = "0.0.8"
+    VERSION = "0.0.9"
   end
 end

data/spec/query_spec.rb

@@ -1,9 +1,4 @@
-require 'pebbles-uid/parse'
-require 'pebbles-uid/cache_key'
-require 'pebbles-uid/labels'
-require 'pebbles-uid/conditions'
-require 'pebbles-uid/oid'
-require 'pebbles-uid/query'
+require 'pebbles-uid'
 
 describe Pebbles::Uid::Query do
 
@@ -17,7 +12,7 @@ describe Pebbles::Uid::Query do
     its(:list?) { should == false }
     its(:collection?) { should == false }
     its(:cache_keys) { should eq(['post:area51.*$abc']) }
-    its(:to_hash) { should eq(:genus_0_ => 'post', :path_0_ => 'area51', :oid_ => 'abc') }
+    its(:to_hash) { should eq(:species_0_ => 'post', :path_0_ => 'area51', :oid_ => 'abc') }
 
     it "handles a wildcard path if realm is given" do
       query = Pebbles::Uid::Query.new('post:area51.*$abc')
@@ -73,7 +68,7 @@ describe Pebbles::Uid::Query do
       ->{ Pebbles::Uid::Query.new('post:area51$abc,post:area52$xyz') }.should raise_error(ArgumentError)
     end
 
-    it "bails with unspecific genus" do
+    it "bails with unspecific species" do
       ->{ Pebbles::Uid::Query.new('post.*:area51$abc,post:area51$xyz') }.should raise_error(ArgumentError)
     end
 
@@ -101,7 +96,7 @@ describe Pebbles::Uid::Query do
     context "everything" do
       subject { Pebbles::Uid::Query.new('*:*') }
 
-      its(:genus?) { should == false }
+      its(:species?) { should == false }
       its(:path?) { should == false }
       its(:oid?) { should == false }
 
@@ -115,25 +110,25 @@ describe Pebbles::Uid::Query do
     context "everything, with any oid" do
       subject { Pebbles::Uid::Query.new('*:*$*') }
 
-      its(:genus?) { should == false }
+      its(:species?) { should == false }
       its(:path?) { should == false }
       its(:oid?) { should == false }
       its(:to_hash) { should == {} }
     end
 
-    context "a genus" do
+    context "a species" do
       subject { Pebbles::Uid::Query.new('beast:*$*') }
-      its(:genus?) { should == true }
-      its(:genus) { should eq('beast') }
-      its(:species?) { should == false }
-      its(:to_hash) { should == {:genus_0 => 'beast'} }
+      its(:species?) { should == true }
+      its(:species) { should eq('beast') }
+      its(:epiteth?) { should == false }
+      its(:to_hash) { should == {:species_0 => 'beast'} }
     end
 
-    context "a species" do
+    context "a epiteth" do
       subject { Pebbles::Uid::Query.new('beast.mythical.hairy:*$*') }
-      its(:species?) { should == true }
-      its(:species) { should eq('mythical.hairy') }
-      its(:to_hash) { should == {:genus_0 => 'beast', :genus_1 => 'mythical', :genus_2 => 'hairy'} }
+      its(:epiteth?) { should == true }
+      its(:epiteth) { should eq('mythical.hairy') }
+      its(:to_hash) { should == {:species_0 => 'beast', :species_1 => 'mythical', :species_2 => 'hairy'} }
     end
 
     context "a path" do
@@ -150,7 +145,7 @@ describe Pebbles::Uid::Query do
     end
 
     context "a typical search" do
-      subject { Pebbles::Uid::Query.new('beast:myths.*', :genus => 'klass', :path => 'label', :suffix => '') }
+      subject { Pebbles::Uid::Query.new('beast:myths.*', :species => 'klass', :path => 'label', :suffix => '') }
       its(:to_hash) { should == {:klass_0_ => 'beast', :label_0_ => 'myths'} }
       its(:next_path_label) { should == :label_1_ }
     end
@@ -162,7 +157,7 @@ describe Pebbles::Uid::Query do
     end
 
     context "a search with stops" do
-      subject { Pebbles::Uid::Query.new('beast:myths$*', :genus => 'klass', :path => 'label', :suffix => '', :stop => nil) }
+      subject { Pebbles::Uid::Query.new('beast:myths$*', :species => 'klass', :path => 'label', :suffix => '', :stop => nil) }
       its(:to_hash) { should == {:klass_0_ => 'beast', :klass_1_ => nil, :label_0_ => 'myths', :label_1_ => nil} }
       its(:next_path_label) { should == :label_1_ }
     end

data/spec/uid_spec.rb

@@ -14,7 +14,15 @@ describe Pebbles::Uid do
 
   describe "extracts elements" do
     specify "genus" do
-      Pebbles::Uid.genus(uid).should eq('post.card')
+      Pebbles::Uid.genus(uid).should eq('post')
+    end
+
+    specify "species" do
+      Pebbles::Uid.species(uid).should eq('post.card')
+    end
+
+    specify "epiteth" do
+      Pebbles::Uid.epiteth('post.picture.card:a.b.c$1').should eq('picture.card')
     end
 
     specify "path" do
@@ -31,7 +39,7 @@ describe Pebbles::Uid do
   end
 
   describe "must" do
-    specify "have a genus" do
+    specify "have a species" do
       ->{ Pebbles::Uid.new(':tourism.norway$1') }.should raise_error(ArgumentError)
     end
 
@@ -47,7 +55,7 @@ describe Pebbles::Uid do
   end
 
   describe "rejects" do
-    it "wildcard genus" do
+    it "wildcard species" 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)
@@ -78,10 +86,10 @@ describe Pebbles::Uid do
     end
   end
 
-  context "genus" do
+  context "species" do
     %w(- . _ 8).each do |char|
-      it "accepts #{char} in a genus" do
-        Pebbles::Uid.valid_genus?("uni#{char}corn").should == true
+      it "accepts #{char} in a species" do
+        Pebbles::Uid.valid_species?("uni#{char}corn").should == true
       end
     end
 
@@ -120,8 +128,9 @@ describe Pebbles::Uid do
 
     its(:to_s) { should eq(uid) }
     its(:realm) { should eq('tourism') }
-    its(:genus) { should eq('post.card') }
-    its(:species) { should eq('card') }
+    its(:genus) { should eq('post') }
+    its(:species) { should eq('post.card') }
+    its(:epiteth) { should eq('card') }
     its(:path) { should eq('tourism.norway.fjords') }
     its(:oid) { should eq('1234') }
     its(:oid?) { should == true }
@@ -129,12 +138,12 @@ describe Pebbles::Uid do
     its(:cache_key) { should eq('post.card:tourism.*$1234') }
 
     its(:to_hash) do
-      should eq(:genus_0 => 'post', :genus_1 => 'card', :path_0 => 'tourism', :path_1 => 'norway', :path_2 => 'fjords', :oid => '1234')
+      should eq(:species_0 => 'post', :species_1 => 'card', :path_0 => 'tourism', :path_1 => 'norway', :path_2 => 'fjords', :oid => '1234')
     end
 
     context "without an oid" do
       it "excludes the oid key from the hash" do
-        Pebbles::Uid.new('post.doc:a.b.c').to_hash.should eq(:genus_0 => 'post', :genus_1 => 'doc', :path_0 => 'a', :path_1 => 'b', :path_2 => 'c')
+        Pebbles::Uid.new('post.doc:a.b.c').to_hash.should eq(:species_0 => 'post', :species_1 => 'doc', :path_0 => 'a', :path_1 => 'b', :path_2 => 'c')
       end
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pebbles-uid
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70147042121560 !ruby/object:Gem::Requirement
+  requirement: &70250797645480 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70147042121560
+  version_requirements: *70250797645480
 description: Handle pebble UIDs conveniently.
 email:
 - katrina.owen@gmail.com
@@ -35,11 +35,10 @@ files:
 - README.md
 - Rakefile
 - lib/pebbles-uid.rb
-- lib/pebbles-uid/cache_key.rb
+- lib/pebbles-uid/class_methods.rb
 - lib/pebbles-uid/conditions.rb
 - lib/pebbles-uid/labels.rb
 - lib/pebbles-uid/oid.rb
-- lib/pebbles-uid/parse.rb
 - lib/pebbles-uid/query.rb
 - lib/pebbles-uid/version.rb
 - lib/pebbles-uid/wildcard.rb

data/lib/pebbles-uid/cache_key.rb

@@ -1,13 +0,0 @@
-module Pebbles
-  class Uid
-
-    class << self
-      def cache_key(uid)
-        genus, path, oid = parse(uid)
-        "#{genus}:#{Labels.new(path).first}.*$#{oid}"
-      end
-    end
-
-  end
-end
-

data/lib/pebbles-uid/parse.rb

@@ -1,14 +0,0 @@
-module Pebbles
-  class Uid
-
-    class << self
-
-      def parse(s)
-        /^(?<genus>.*):(?<path>[^\$]*)\$?(?<oid>.*)$/ =~ s
-        [genus, path, oid.empty? ? nil : oid]
-      end
-
-    end
-  end
-end
-