roadforest 0.0.1

data/examples/file-management.rb

@@ -0,0 +1,98 @@
+require 'rdf/vocab/skos'
+
+module FileManagementExample
+  module Vocabulary
+    class LC < ::RDF::Vocabulary("http://lrdesign.com/vocabularies/logical-construct#"); end
+  end
+
+  class ServicesHost < ::RoadForest::Application::ServicesHost
+    attr_accessor :file_records, :destination_dir
+
+    def initialize
+      @file_records = []
+    end
+  end
+
+  FileRecord = Struct.new(:name, :resolved)
+
+  class Application < RoadForest::Application
+    def setup
+      router.add         :root,              [],                    :read_only,  Models::Navigation
+      router.add         :unresolved_needs,  ["unresolved_needs"],  :parent,     Models::UnresolvedNeedsList
+      router.add_traced  :need,              ["needs",'*'],         :leaf,       Models::Need
+      router.add         :file_content,      ["files","*"],         :leaf,       Models::NeedContent
+    end
+
+    module Models
+      class Navigation < RoadForest::RDFModel
+        def exists?
+          true
+        end
+
+        def update(graph)
+          return false
+        end
+
+        def nav_entry(graph, name, path)
+          graph.add_node([:skos, :hasTopConcept], "#" + name) do |entry|
+            entry[:rdf, :type] = [:skos, "Concept"]
+            entry[:skos, :label] = name
+            entry[:foaf, "page"] = path
+          end
+        end
+
+        def fill_graph(graph)
+          graph[:rdf, "type"] = [:skos, "ConceptScheme"]
+          nav_entry(graph, "Unresolved", path_for(:unresolved_needs))
+        end
+      end
+
+      class UnresolvedNeedsList < RoadForest::RDFModel
+        def exists?
+          true
+        end
+
+        def update(graph)
+        end
+
+        def add_child(graph)
+          new_file = FileRecord.new(graph.first(:lc, "name"), false)
+          services.file_records << new_file
+        end
+
+        def fill_graph(graph)
+          graph.add_list(:lc, "needs") do |list|
+            services.file_records.each do |record|
+              if !record.resolved
+                list << path_for(:need, '*' => record.name)
+              end
+            end
+          end
+        end
+      end
+
+      class NeedContent < RoadForest::BlobModel
+        add_type "text/plain", TypeHandlers::Handler.new
+      end
+
+      class Need < RoadForest::RDFModel
+        def data
+          @data = services.file_records.find do |record|
+            record.name == params.remainder
+          end
+        end
+
+        def graph_update(graph)
+          data.resolved = graph[[:lc, "resolved"]]
+          new_graph
+        end
+
+        def fill_graph(graph)
+          graph[[:lc, "resolved"]] = data.resolved
+          graph[[:lc, "name"]] = data.name
+          graph[[:lc, "contents"]] = path_for(:file_content)
+        end
+      end
+    end
+  end
+end

data/lib/roadforest/application/dispatcher.rb

@@ -0,0 +1,54 @@
+require 'webmachine'
+
+module RoadForest
+  class Dispatcher < Webmachine::Dispatcher
+    include Resource::Handlers
+    def initialize(services)
+      super(method(:create_resource))
+      @services = services
+      @route_names = {}
+    end
+    attr_accessor :services
+
+    def resource_route(resource, name, path_spec, bindings)
+      route = Route.new(path_spec, resource, bindings || {})
+      yield route if block_given?
+      @route_names[name] = route
+      @routes << route
+      route
+    end
+
+    def add_route(name, path_spec, resource_type, model_class, bindings = nil, &block)
+      resource = bundle_typed_resource(resource_type, model_class, name)
+      resource_route(resource, name, path_spec, bindings, &block)
+    end
+    alias add add_route
+
+    def add_traced_route(name, path_spec, resource_type, model_class, bindings = nil, &block)
+      resource = bundle_traced_resource(resource_type, model_class, name)
+      resource_route(resource, name, path_spec, bindings, &block)
+    end
+    alias add_traced add_traced_route
+
+    def route_for_name(name)
+      @route_names.fetch(name)
+    end
+
+    class Route < Webmachine::Dispatcher::Route
+      # Create a complete URL for this route, doing any necessary variable
+      # substitution.
+      # @param [Hash] vars values for the path variables
+      # @return [String] the valid URL for the route
+      def build_path(vars = {})
+        "/" + path_spec.map do |segment|
+          case segment
+          when '*',Symbol
+            vars.fetch(segment)
+          when String
+            segment
+          end
+        end.join("/")
+      end
+    end
+  end
+end

data/lib/roadforest/application/parameters.rb

@@ -0,0 +1,39 @@
+module RoadForest
+  class Application
+    #Parameters extracted from a URL, which a model object can use to identify
+    #the resource being discussed
+    class Parameters
+      def initialize
+        @path_info = {}
+        @query_params = {}
+        @path_tokens = []
+        yield self if block_given?
+      end
+      attr_accessor :path_info, :query_params, :path_tokens
+
+      def [](field_name)
+        return path_tokens if field_Name == '*'
+        @path_info[field_name] || @query_params[field_name]
+      end
+
+      def fetch(field_name)
+        return path_tokens if field_Name == '*'
+        @path_info[field_name] || @query_params.fetch(field_name)
+      end
+
+      def slice(*fields)
+        fields.each_with_object({}) do |name, hash|
+          hash[name] = self[name]
+        end
+      end
+
+      def remainder
+        @remainder = @path_tokens.join("/")
+      end
+
+      def to_hash
+        (query_params||{}).merge(path_info||{}).merge('*' => path_tokens)
+      end
+    end
+  end
+end

data/lib/roadforest/application/path-provider.rb

@@ -0,0 +1,18 @@
+module RoadForest
+  class PathProvider
+    def initialize(dispatcher)
+      @dispatcher = dispatcher
+    end
+
+    # Get the URL to the given resource, with optional variables to be used
+    # for bindings in the path spec.
+    # @param [Webmachine::Resource] resource the resource to link to
+    # @param [Hash] vars the values for the required path variables
+    # @raise [RuntimeError] Raised if the resource is not routable.
+    # @return [String] the URL
+    def path_for(name, vars = {})
+      route = @dispatcher.route_for_name(name)
+      ::RDF::URI.parse(route.build_path(vars))
+    end
+  end
+end

data/lib/roadforest/application/route-adapter.rb

@@ -0,0 +1,24 @@
+module RoadForest
+  class Application
+    class RouteAdapter
+      def initialize(resource_class, &setup_block)
+        @resource_class = resource_class
+        @setup_block = setup_block
+      end
+
+      def new(request, response)
+        resource = @resource_class.new(request, response)
+        @setup_block[resource, request, response]
+        resource
+      end
+
+      def <(klass)
+        if klass <= Webmachine::Resource
+          return true
+        else
+          return false
+        end
+      end
+    end
+  end
+end

data/lib/roadforest/application/services-host.rb

@@ -0,0 +1,10 @@
+class RoadForest::Application
+  #XXX Worth doing some meta to get sanity checking of configs here? Better
+  #fail early if there's no DB configured, right?
+  class ServicesHost
+    def initialize
+    end
+
+    attr_accessor :router, :canonical_host, :type_handling
+  end
+end

data/lib/roadforest/application.rb

@@ -0,0 +1,42 @@
+require 'webmachine/application'
+module RoadForest
+  class Application < Webmachine::Application; end
+end
+
+require 'roadforest/resource/handlers'
+require 'roadforest/application/dispatcher'
+require 'roadforest/application/path-provider'
+require 'roadforest/application/services-host'
+require 'roadforest/resource/rdf'
+require 'roadforest/content-handling/engine'
+
+module RoadForest
+  class Application
+    include Resource::Handlers
+
+    def initialize(canonical_host, services, configuration = nil, dispatcher = nil)
+      @canonical_host = ::RDF::URI.parse(canonical_host)
+      configuration ||= Webmachine::Configuration.default
+      dispatcher ||= Dispatcher.new(services)
+      super(configuration, dispatcher)
+      self.services = services
+
+      setup
+    end
+
+    def setup
+    end
+
+    attr_reader :services, :canonical_host
+
+    alias router dispatcher
+
+    def services=(service_host)
+      router.services = service_host
+      @services = service_host
+      @services.canonical_host = @canonical_host
+      @services.router = PathProvider.new(@dispatcher)
+      @services.type_handling ||= ContentHandling::Engine.default
+    end
+  end
+end

data/lib/roadforest/blob-model.rb

@@ -0,0 +1,56 @@
+require 'roadforest/model'
+require 'roadforest/content-handling/type-handlers/jsonld'
+
+module RoadForest
+  class BlobModel < Model
+    TypeHandlers = RoadForest::MediaType::Handlers
+    class << self
+      def type_handling
+        @engine ||= ContentHandling::Engine.new
+      end
+
+      def add_type(type, handler)
+        add_parser(type, handler)
+        add_renderer(type, handler)
+      end
+      alias add add_type
+
+      def add_parser(type, handler)
+        type_handling.add_parser(type, handler)
+      end
+
+      def add_renderer(type, handler)
+        type_handling.add_renderer(type, handler)
+      end
+    end
+
+    def type_handling
+      self.class.type_handling
+    end
+
+    def destination_dir
+      Pathname.new(services.destination_dir)
+    end
+
+    def sub_path
+      params.remainder
+    end
+
+    def path
+      destination_dir.join(sub_path)
+    end
+
+    def retrieve
+      File::open(path)
+    end
+
+    def update(incoming)
+      File::open(path, "w") do |file|
+        incoming.each do |chunk|
+          file.write(chunk)
+        end
+      end
+      return nil
+    end
+  end
+end

data/lib/roadforest/content-handling/engine.rb

@@ -0,0 +1,113 @@
+require 'roadforest/content-handling/media-type'
+
+module RoadForest
+  module ContentHandling
+    class Engine
+      class TypeHandlerList
+        def initialize(prefix)
+          @prefix = prefix
+          @types = MediaTypeList.new
+          @handlers = {}
+          @type_map = []
+          @symbol_lookup = {}
+        end
+        attr_reader :handlers, :types, :type_map
+
+        def add(handler)
+          type = handler.type
+          @types.add(type)
+          @handlers[type] = handler
+          symbol = handler_symbol(type)
+          raise "Type collision: #{type} already in #{self.inspect}" if @symbol_lookup.has_key?(symbol)
+          @type_map << [type.content_type_header, symbol]
+          @symbol_lookup[symbol] = handler
+        end
+
+        def handler_symbol(type)
+          "#{@prefix}_#{type.accept_header.gsub(/\W/, "_")}".to_sym
+        end
+
+        def fetch(symbol, &block)
+          @symbol_lookup.fetch(symbol, &block)
+        end
+
+        def reset
+          @handlers.clear
+        end
+
+        def handler_for(type)
+          type = MediaType.parse(type)
+          @handlers.fetch(type)
+        rescue KeyError
+          raise "No Content-Type handler for #{content_type}"
+        end
+      end
+
+      def self.default
+        require 'roadforest/content-handling/type-handlers/jsonld'
+        self.new.tap do |engine|
+          engine.add "application/ld+json", RoadForest::MediaType::Handlers::JSONLD.new
+        end
+      end
+
+      def initialize
+        @renderers = TypeHandlerList.new("provide")
+        @parsers = TypeHandlerList.new("accept")
+        @type_mapping = {}
+      end
+      attr_reader :renderers, :parsers
+
+      def add_type(type, handler)
+        type = MediaType.parse(type)
+        add_parser(type, handler)
+        add_renderer(type, handler)
+      end
+      alias add add_type
+
+      def add_parser(type, object)
+        type = MediaType.parse(type)
+        wrapper = RoadForest::MediaType::Handlers::Wrap::Parse.new(type, object)
+        parsers.add(wrapper)
+      end
+      alias accept add_parser
+
+      def add_renderer(type, object)
+        type = MediaType.parse(type)
+        wrapper = RoadForest::MediaType::Handlers::Wrap::Render.new(type, object)
+        renderers.add(wrapper)
+      end
+      alias provide add_renderer
+
+      def fetch(symbol)
+        @renderers.fetch(symbol){ @parsers.fetch(symbol) }
+      end
+
+      def choose_renderer(header)
+        content_type = choose_media_type(renderers.types, header)
+        return renderers.handler_for(content_type)
+      end
+
+      def each_renderer(&block)
+        renderers.handlers.enum_for(:each_pair) unless block_given?
+        renderers.handlers.each_pair(&block)
+      end
+
+      def choose_parser(header)
+        content_type = choose_media_type(parsers.types, header)
+        return parsers.handler_for(content_type)
+      end
+
+      def each_parser(&block)
+        parsers.handlers.enum_for(:each_pair) unless block_given?
+        parsers.handlers.each_pair(&block)
+      end
+
+      # Given the 'Accept' header and provided types, chooses an
+      # appropriate media type.
+      def choose_media_type(provided, header)
+        requested = MediaTypeList.build(header.split(/\s*,\s*/))
+        requested.best_match_from(provided)
+      end
+    end
+  end
+end

data/lib/roadforest/content-handling/media-type.rb

@@ -0,0 +1,222 @@
+module RoadForest
+  module ContentHandling
+    #@credit goes to Sean Cribbs & Ruby Webmachine for the basis of this code
+    #
+    # Encapsulates a MIME media type, with logic for matching types.
+    class MediaType
+      # Matches valid media types
+      MEDIA_TYPE_REGEX = /^\s*([^;\s]+)\s*((?:;\s*\S+\s*)*)\s*$/
+
+      # Matches sub-type parameters
+      PARAMS_REGEX = /;\s*([^=]+)=([^;=\s]+)/
+
+      # Creates a new MediaType by parsing an alternate representation.
+      # @param [MediaType, String, Array<String,Hash>] obj the raw type
+      #   to be parsed
+      # @return [MediaType] the parsed media type
+      # @raise [ArgumentError] when the type could not be parsed
+      def self.parse(obj)
+        case obj
+        when MediaType
+          obj
+        when MEDIA_TYPE_REGEX
+          type, raw_params = $1, $2
+          params = Hash[raw_params.scan(PARAMS_REGEX)]
+          new(type, params)
+        else
+          unless Array === obj && String === obj[0] && Hash === obj[1]
+            raise ArgumentError, "Invalid media type #{obj.inspect}"
+          end
+          type = parse(obj[0])
+          type.params.merge!(obj[1])
+          type
+        end
+      end
+
+      # @return [String] the MIME media type
+      attr_accessor :type
+
+      # @return [Hash] any type parameters, e.g. charset
+      attr_accessor :params
+
+      # @param [String] type the main media type, e.g. application/json
+      # @param [Hash] params the media type parameters
+      def initialize(type, params={})
+        @type, @params = type, params
+        @quality = (@params.delete('q') || "1.0").to_f
+      end
+
+      attr_reader :quality
+
+      # Detects whether the {MediaType} represents an open wildcard
+      # type, that is, "*/*" without any {#params}.
+      def matches_all?
+        @type == "*/*" && @params.empty?
+      end
+
+      # @return [true,false] Are these two types strictly equal?
+      # @param other the other media type.
+      # @see MediaType.parse
+      def ==(other)
+        other = self.class.parse(other)
+        other.type == type && other.params == params
+      end
+
+      # Detects whether this {MediaType} matches the other {MediaType},
+      # taking into account wildcards. Sub-type parameters are treated
+      # strictly.
+      # @param [MediaType, String, Array<String,Hash>] other the other type
+      # @return [true,false] whether it is an acceptable match
+      def exact_match?(other)
+        other = self.class.parse(other)
+        type_matches?(other) && other.params == params
+      end
+
+      # Detects whether the {MediaType} is an acceptable match for the
+      # other {MediaType}, taking into account wildcards and satisfying
+      # all requested parameters, but allowing this type to have extra
+      # specificity.
+      # @param [MediaType, String, Array<String,Hash>] other the other type
+      # @return [true,false] whether it is an acceptable match
+      def match?(other)
+        other = self.class.parse(other)
+        type_matches?(other) && params_match?(other.params)
+      end
+      alias =~ match?
+
+      # Detects whether the passed sub-type parameters are all satisfied
+      # by this {MediaType}. The receiver is allowed to have other
+      # params than the ones specified, but all specified must be equal.
+      # @param [Hash] params the requested params
+      # @return [true,false] whether it is an acceptable match
+      def params_match?(other)
+        other.all? do |k,v|
+          params[k] == v
+        end
+      end
+
+      def accept_header
+        [type, "q=#{quality}", *params.map {|k,v| "#{k}=#{v}" }].join(";")
+      end
+
+      def content_type_header
+        [type, *params.map {|k,v| "#{k}=#{v}" }].join(";")
+      end
+      alias to_s content_type_header
+
+      # @return [String] The major type, e.g. "application", "text", "image"
+      def major
+        @major ||= type.split("/").first
+      end
+
+      # @return [String] the minor or sub-type, e.g. "json", "html", "jpeg"
+      def minor
+        @minor ||= type.split("/").last
+      end
+
+      def precedence_index
+        [
+          @major == "*" ? 0 : 1,
+          @minor == "*" ? 0 : 1,
+          (@params.keys - %w{q}).length
+        ]
+      end
+
+      # @param [MediaType] other the other type
+      # @return [true,false] whether the main media type is acceptable,
+      #   ignoring params and taking into account wildcards
+      def type_matches?(other)
+        other = self.class.parse(other)
+        if ["*", "*/*", type].include?(other.type)
+          true
+        else
+          other.major == major && other.minor == "*"
+        end
+      end
+    end
+
+    class MediaTypeList
+      # Given an acceptance list, create a PriorityList from them.
+      def self.build(list)
+        return list if self === list
+
+        case list
+        when Array
+        when String
+          list = list.split(/\s*,\s*/)
+        else
+          raise "Cannot build a MediaTypeList from #{list.inspect}"
+        end
+
+        new.tap do |plist|
+          list.each {|item| plist.add_header_val(item) }
+        end
+      end
+
+      include Enumerable
+
+      # Creates a {PriorityList}.
+      # @see PriorityList::build
+      def initialize
+        @list = []
+      end
+
+      def accept_header
+        @list.map(&:accept_header).join(", ")
+      end
+      alias to_s accept_header
+
+      #Given another MediaTypeList, find the media type that is the best match
+      #between them - generally, the idea is to match an Accept header with a
+      #local list of provided types
+      def best_match_from(other)
+        other.max_by do |their_type|
+          best_type = self.by_precedence.find do |our_type|
+            their_type =~ our_type
+          end
+          if best_type.nil?
+            0
+          else
+            best_type.quality * their_type.quality
+          end
+        end
+      end
+
+      def by_precedence
+        self.sort do |left, right|
+          right.precedence_index <=> left.precedence_index
+        end.enum_for(:each)
+      end
+
+      # Adds an acceptable item with the given priority to the list.
+      # @param [Float] q the priority
+      # @param [String] choice the acceptable item
+      def add(type)
+        @list << type
+      end
+
+      # Given a raw acceptable value from an acceptance header,
+      # parse and add it to the list.
+      # @param [String] c the raw acceptable item
+      # @see #add
+      def add_header_val(type_string)
+        add(MediaType.parse(type_string))
+      rescue ArgumentError
+        raise "Invalid media type"
+      end
+
+      # Iterates over the list in priority order, that is, taking
+      # into account the order in which items were added as well as
+      # their priorities.
+      # @yield [q,v]
+      # @yieldparam [Float] q the acceptable item's priority
+      # @yieldparam [String] v the acceptable item
+      def each
+        return enum_for(:each) unless block_given?
+        @list.each do |item|
+          yield item
+        end
+      end
+    end
+  end
+end