pragmatic_context 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4bc6e4f0095dfc065bdc39301e9199ccf86dc34a
+  data.tar.gz: 1befe8820a2a6540868a07773b255c88e28fd9d2
+SHA512:
+  metadata.gz: 0369df6d7cd4d81bcbd7d7581dab2f282245f51266c2ceb1f71199e97975baa7c3042e03a08c9328a2e3688360cbd113c8c526aedb439679afee2e1213abd8c5
+  data.tar.gz: 049c0729133a59bb9ff14398ae0826614b1a46c68ffb9b9a79bd7edc818b2106715a239daaea79fe4cdc639801b7ec3261638e82e52a638446c7cacc2d5003b1

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/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Mat Trudel
+
+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,182 @@
+# PragmaticContext
+
+PragmaticContext lets declaratively contextualize your
+ActiveModel objects in terms of Linked Data concepts, giving you an easy way to
+get your models talking JSON-LD.
+
+## What's JSON-LD?
+
+I'm glad you asked. [JSON-LD](http://json-ld.org/) is a lightweight JSON format
+for expressing data within a context (also known as 'Linked Data'). Essentially
+what this means is that it lets you say that the thing your data model calls
+a 'last_name' is an embodiment of the abstract idea of a [Family
+Name](http://xmlns.com/foaf/spec/#term_familyName). JSON-LD is similar in spirit
+(though [vastly different in
+execution](http://manu.sporny.org/2014/json-ld-origins-2/)) to
+[RDF](http://en.wikipedia.org/wiki/Resource_Description_Framework). It allows
+users of your application to unambiguously establish the place of your application's data
+within a larger universe by placing it in context.
+
+If you're just getting started with JSON-LD, I highly recommend the [JSON-LD 1.0 W3C
+Recommendation](http://www.w3.org/TR/json-ld/) (really. Start at section 5).
+It's a straightforward description of JSON-LD's purpose and structure, and
+should be an easy read for anyone who already uses JSON. I wish more standards
+documents were written this way. Seriously, it's great.
+
+## An example
+
+As an example, let's consider the following Mongoid document:
+
+    class Person
+      include Mongoid::Document
+
+      field :first_name
+      field :last_name
+      field :email
+    end
+
+As implemented above, a Person object has a first name, a last name, an email
+address, and would serialize to JSON as something like:
+
+    { 
+      "first_name": "Mat",
+      "last_name": "Trudel",
+      "email": "mat@geeky.net"
+    }
+
+While that's usually clear enough to a human interacting with your API, the
+field names chosen are basically arbitrary, and are difficult to process in any
+automated way. Ideally, your field names should be able to unambiguously
+identify a field as representing the concept of a person's first
+name, whether the field was named 'first_name', 'FirstName', 'given_name', or
+even 'field1234'. By allowing you to contextualize your data, JSON-LD lets you
+essentially say "when I say 'last_name', I really mean
+`http://xmlns.com/foaf/0.1/familyName`". In so doing, it becomes possible to
+associate the last name fields of any JSON-LD API, regardless of what they name
+their fields.
+
+## Isn't this just a re-invention of RDF?
+
+Yes and no. While it's true that JSON-LD is a valid RDF serialization format,
+this [wasn't one of its original design
+goals](http://manu.sporny.org/2014/json-ld-origins-2/). My intent with
+PragmaticContext is to allow developers who already work with JSON data to be
+able to easily turn it into Linked Data without having to know or care about RDF
+at all. At a basic level, the concepts of Linked Data should be grokkable by
+anyone who already understands the basic concepts of APIs in general. JSON-LD's
+creator Manu Sporny says it best:
+
+> I’ve heard many people say that JSON-LD is primarily about the Semantic Web,
+> but I disagree, it’s not about that at all. JSON-LD was created for Web
+> Developers that are working with data that is important to other people and
+> must interoperate across the Web. The Semantic Web was near the bottom of my
+> list of “things to care about” when working on JSON-LD, and anyone that tells
+> you otherwise is wrong
+
+In terms of my personal approach to developing PragmanticContext, I'm
+consciously not considering RDF as entering into the equation at all. With
+PragmaticContext, I'm playing the role of an API developer already steeped in
+JSON who wants to make their data more expressive without having to slow down
+or learn a new stack. While I personally understand RDF's role and potential,
+I'm willfully ignoring it with the goal of producing a library relevant to JSON
+API developers. My thesis is that if JSON-LD is to be relevant to existing JSON
+API developers, it needs to do so as a natural outgrowth of their existing
+environment.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'pragmatic_context'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pragmatic_context
+
+## Usage
+
+PragmaticContext is implemented as a module that you mix into your existing
+ActiveModel objects. Taking the `Person` model above, you would add context to
+it like so:
+
+    class Person
+      include Mongoid::Document
+      include PragmaticContext::Contextualizable
+
+      field :first_name
+      field :last_name
+      field :email
+
+      contextualize :first_name, :as => 'http://xmlns.com/foaf/0.1/givenName'
+      contextualize :last_name, :as => 'http://xmlns.com/foaf/0.1/familyName'
+      contextualize :email, :as => 'http://xmlns.com/foaf/0.1/mbox'
+    end
+
+The `Contextualizable` mixin adds a `context` method to the Person object which
+returns a Hash object ready to be serialized into the output object. By wiring
+this up in whatever serializer your application uses, you would end up with
+the following JSON(-LD!) serialization:
+
+
+    { 
+      "@context": {
+        "first_name": { "@id", "http://xmlns.com/foaf/0.1/givenName" },
+        "last_name": { "@id", "http://xmlns.com/foaf/0.1/familyName" },
+        "email": { "@id", "http://xmlns.com/foaf/0.1/mbox" },
+      },
+      "first_name": "Mat",
+      "last_name": "Trudel",
+      "email": "mat@geeky.net"
+    }
+
+### Dynamic documents & more complicated cases
+
+There are cases (especially using Monogid's dynamic fields feature) where the
+list of an object's fields is not known at class load time. In these cases, it's
+possible to defer contextualization to a custom `Contextualizer` class
+configured like so:
+
+    class Person
+      include Mongoid::Document
+      include PragmaticContext::Contextualizable
+
+      #
+      # Machinery for defining fields, either static or dynamic
+      #
+
+      contextualize_with CustomContextualizer
+    end
+
+    class CustomContextualizer
+      def definitions_for_terms(terms)
+        # Returns a hash of terms => term definitions
+      end
+    end
+
+Examples of this are forthcoming.
+
+## Known Issues
+
+* `@type` values aren't yet handled in any real way. This is next up on my queue
+  and should be done very soon.
+* The above example is purposely short on serialization specifics. I'm trying to
+  be accommodating of various serializers and I'm still figuring out the best
+  way to do this. Hopefully we'll be able to make the process of adding
+  a `@context` automatic (or close to it) for common cases. Suggestions for this
+  point are very welcome.
+* Further to the above, there are many (most, even) use cases where the included
+  `@context` field should simply be a URI pointing to a stand-alone
+  represntation of the object's context. I'm not sure how to flexibly realize
+  this yet. Again, suggestions are very welcome.
+
+## Contributing
+
+1. Fork it ( http://github.com/mtrudel/pragmatic_context/fork )
+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 @@
+require "bundler/gem_tasks"

data/lib/pragmatic_context/contextualizable.rb

@@ -0,0 +1,47 @@
+require 'pragmatic_context/default_contextualizer'
+
+module PragmaticContext
+  module Contextualizable
+    def Contextualizable.included(base)
+      base.class_eval do
+      end
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      attr_accessor :contextualizer
+
+      def contextualize_with(klass)
+        self.contextualizer = klass.new
+      end
+
+      def contextualize(field, params)
+        setup_default_contextualizer
+        self.contextualizer.add_term(field, params)
+      end
+
+      private
+
+      def setup_default_contextualizer
+        already_setup = !self.contextualizer.nil? && !self.contextualizer.is_a?(PragmaticContext::DefaultContextualizer)
+        raise "Cannot call contextualize if contextualize_with has already been called" if already_setup
+        self.contextualizer ||= PragmaticContext::DefaultContextualizer.new
+      end
+    end
+
+    def context
+      self.class.contextualizer.definitions_for_terms(terms)
+    end
+
+    def uncontextualized_terms
+      terms_with_context = self.class.contextualizer.definitions_for_terms(terms).keys
+      terms - terms_with_context
+    end
+
+    private
+
+    def terms
+      attributes.keys - ['_id', '_type']
+    end
+  end
+end

data/lib/pragmatic_context/default_contextualizer.rb

@@ -0,0 +1,24 @@
+require 'active_support'
+require 'active_support/hash_with_indifferent_access'
+
+module PragmaticContext
+  class DefaultContextualizer
+    def add_term(term, params)
+      @properties ||= ActiveSupport::HashWithIndifferentAccess.new
+      @properties[term] = ActiveSupport::HashWithIndifferentAccess.new params
+    end
+
+    def definitions_for_terms(terms)
+      Hash[@properties.slice(*terms).map { |term, params| [term, definition_from_params(params)] }]
+    end
+
+    private
+
+    def definition_from_params(params)
+      result = {}
+      result['@id'] = params[:as] if params[:as]
+      result['@type'] = params[:type] if params[:type]
+      result
+    end
+  end
+end

data/lib/pragmatic_context/version.rb

@@ -0,0 +1,3 @@
+module PragmaticContext
+  VERSION = "0.0.1"
+end

data/lib/pragmatic_context.rb

@@ -0,0 +1,6 @@
+require "pragmatic_context/version"
+require "pragmatic_context/contextualizable"
+
+module PragmaticContext
+
+end

data/pragmatic_context.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'pragmatic_context/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "pragmatic_context"
+  spec.version       = PragmaticContext::VERSION
+  spec.authors       = ["Mat Trudel"]
+  spec.email         = ["mat@geeky.net"]
+  spec.summary       = %q{JSON-LD from a JSON perspective}
+  spec.description   = %q{A library to declaratively add JSON-LD support to your ActiveModel models}
+  spec.homepage      = "http://github.com/mtrudel/pragmatic_context"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec", "~> 2.6"
+
+  spec.add_dependency "activesupport"
+end

data/spec/lib/pragmatic_context/contextualizable_spec.rb

@@ -0,0 +1,75 @@
+require 'pragmatic_context'
+
+class Stub
+  include PragmaticContext::Contextualizable
+
+  attr_accessor :bacon
+
+  def attributes
+    { "bacon" => bacon }
+  end
+end
+
+describe PragmaticContext::Contextualizable do
+  describe 'included class methods (configuration DSL)' do
+    subject { Stub }
+
+    before :each do
+      subject.contextualizer = nil
+    end
+
+    describe 'contextualize_with' do
+      it 'should set the contextualizer on the class' do
+        contextualizer = double('contextualizer')
+        contextualizer_class = double('contextualizer class')
+        contextualizer_class.stub(:new) { contextualizer }
+        subject.contextualize_with contextualizer_class
+        subject.contextualizer.should eq contextualizer
+      end
+    end
+
+    describe 'contextualize' do
+      it 'should raise error if contextualize_with has already been called' do
+        subject.contextualize_with Object
+        expect { subject.contextualize }.to raise_error
+      end
+
+      it 'should create properties for each named field' do
+        contextualizer = double('contextualizer')
+        contextualizer.should_receive(:add_term).with(:bacon, { :as => 'http://bacon.yum' })
+        PragmaticContext::DefaultContextualizer.stub(:new) { contextualizer }
+
+        subject.contextualize :bacon, :as => 'http://bacon.yum'
+      end
+    end
+  end
+
+  describe 'included instance methods' do
+    subject { Stub.new }
+
+    before :each do
+      @contextualizer = double('contextualizer')
+      contextualizer_class = double('contextualizer class')
+      contextualizer_class.stub(:new) { @contextualizer }
+      subject.class.contextualize_with contextualizer_class
+    end
+
+    describe 'context' do
+      it 'should properly marshall together term definitions with the appropriate terms' do
+        @contextualizer.stub(:definitions_for_terms) do |terms|
+          { 'bacon' => { "@id" => "http://bacon.yum" } }.slice(*terms)
+        end
+        subject.bacon = 'crispy'
+        subject.context['bacon']['@id'].should == 'http://bacon.yum'
+      end
+    end
+
+    describe 'uncontextualized_terms' do
+      it 'should include terms which are not contextualized by the configured Contextualizer' do
+        @contextualizer.stub(:definitions_for_terms) { {} }
+        subject.uncontextualized_terms.should == ['bacon']
+      end
+    end
+  end
+end
+

data/spec/lib/pragmatic_context/default_contextualizer_spec.rb

@@ -0,0 +1,14 @@
+require 'pragmatic_context/default_contextualizer'
+
+describe PragmaticContext::DefaultContextualizer do
+  describe 'adding terms' do
+    it 'should add terms and be able to retrive them' do
+      subject.add_term('bacon', :as => 'http://bacon.com')
+      subject.add_term('ham', :as => 'http://ham.com')
+      subject.definitions_for_terms(%w(bacon ham)).should eq({
+        "bacon" => { "@id" => "http://bacon.com" },
+        "ham" => { "@id" => "http://ham.com" } 
+      })
+    end
+  end
+end

metadata

@@ -0,0 +1,116 @@
+--- !ruby/object:Gem::Specification
+name: pragmatic_context
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Mat Trudel
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-27 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A library to declaratively add JSON-LD support to your ActiveModel models
+email:
+- mat@geeky.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pragmatic_context.rb
+- lib/pragmatic_context/contextualizable.rb
+- lib/pragmatic_context/default_contextualizer.rb
+- lib/pragmatic_context/version.rb
+- pragmatic_context.gemspec
+- spec/lib/pragmatic_context/contextualizable_spec.rb
+- spec/lib/pragmatic_context/default_contextualizer_spec.rb
+homepage: http://github.com/mtrudel/pragmatic_context
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: JSON-LD from a JSON perspective
+test_files:
+- spec/lib/pragmatic_context/contextualizable_spec.rb
+- spec/lib/pragmatic_context/default_contextualizer_spec.rb
+has_rdoc: