roadforest 0.0.3 → 0.1

data/lib/roadforest/content-handling/type-handlers/rdfa-writer/render-environment.rb

@@ -0,0 +1,144 @@
+require 'roadforest/content-handling/type-handlers/rdfa-writer'
+module RoadForest::MediaType
+  class RDFaWriter
+    class RenderEnvironment
+      attr_accessor :heading_predicates, :lang
+
+      def initialize(engine)
+        @_engine = engine
+      end
+
+      def add_debug(msg = nil, &block)
+        @_engine.add_debug(msg, &block)
+      end
+
+      def inspect
+        "<#{self.class.name}:#{"%x" % self.object_id} #{instance_variables.map do |name|
+          next if name == :@_engine
+          "#{name}=#{instance_variable_get(name).inspect}"
+        end.compact.join(" ")}>"
+      end
+      # Display a subject.
+      #
+      # If the Haml template contains an entry matching the subject's rdf:type URI, that entry will be used as the template for this subject and it's properties.
+      #
+      # @example Displays a subject as a Resource Definition:
+      #     <div typeof="rdfs:Resource" about="http://example.com/resource">
+      #       <h1 property="dc:title">label</h1>
+      #       <ul>
+      #         <li content="2009-04-30T06:15:51Z" property="dc:created">2009-04-30T06:15:51+00:00</li>
+      #       </ul>
+      #     </div>
+      #
+      # @param [RDF::Resource] subject
+      # @param [Hash{Symbol => Object}] options
+      # @option options [:li, nil] :element(:div)
+      #   Serialize using &lt;li&gt; rather than template default element
+      # @option options [RDF::Resource] :rel (nil)
+      #   Optional @rel property
+      # @return [String]
+      def subject(subject, &block)
+        @_engine.render_subject(subject, &block)
+      end
+
+      def is_subject?
+        false
+      end
+
+      def literal?
+        false
+      end
+
+      def render_checked
+        false
+      end
+
+      # Haml rendering helper. Return CURIE for the literal datatype, if the
+      # literal is a typed literal.
+      #
+      # @param [RDF::Resource] literal
+      # @return [String, nil]
+      # @raise [RDF::WriterError]
+      def get_dt_curie(literal)
+        raise RDF::WriterError, "Getting datatype CURIE for #{literal.inspect}, which must be a literal" unless literal.is_a?(RDF::Literal)
+        get_curie(literal.datatype) if literal.literal? && literal.datatype?
+      end
+
+      # Haml rendering helper. Return language for plain literal, if there is no language, or it is the same as the document, return nil
+      #
+      # @param [RDF::Literal] literal
+      # @return [Symbol, nil]
+      # @raise [RDF::WriterError]
+      def get_lang(literal)
+        raise RDF::WriterError, "Getting datatype CURIE for #{literal.inspect}, which must be a literal" unless literal.is_a?(RDF::Literal)
+        literal.language if literal.literal? && literal.language && literal.language.to_s != @_engine.lang.to_s
+      end
+
+      # Haml rendering helper. Data to be added to a @content value
+      #
+      # @param [RDF::Literal] literal
+      # @return [String, nil]
+      # @raise [RDF::WriterError]
+      def get_content(literal)
+        raise RDF::WriterError, "Getting content for #{literal.inspect}, which must be a literal" unless literal.is_a?(RDF::Literal)
+        case literal
+        when RDF::Literal::Date, RDF::Literal::Time, RDF::Literal::DateTime
+          literal.to_s
+        end
+      end
+
+      # Haml rendering helper. Display value for object, may be non-canonical if get_content returns a non-nil value
+      #
+      # @param [RDF::Literal] literal
+      # @return [String]
+      # @raise [RDF::WriterError]
+      def get_value(literal)
+        raise RDF::WriterError, "Getting value for #{literal.inspect}, which must be a literal" unless literal.is_a?(RDF::Literal)
+        case literal
+        when RDF::Literal::Date
+          literal.object.strftime("%A, %d %B %Y")
+        when RDF::Literal::Time
+          literal.object.strftime("%H:%M:%S %Z").sub(/\+00:00/, "UTC")
+        when RDF::Literal::DateTime
+          literal.object.strftime("%H:%M:%S %Z on %A, %d %B %Y").sub(/\+00:00/, "UTC")
+        else
+          literal.to_s
+        end
+      rescue
+        literal.to_s  # When all else fails ...
+      end
+
+      # Haml rendering helper. Return an appropriate label for a resource.
+      #
+      # @param [RDF::Resource] resource
+      # @return [String]
+      # @raise [RDF::WriterError]
+      def get_predicate_name(resource)
+        raise RDF::WriterError, "Getting predicate name for #{resource.inspect}, which must be a resource" unless resource.is_a?(RDF::Resource)
+        get_curie(resource)
+      end
+
+      # rendering helper. Return appropriate, term, CURIE or URI for the given
+      # resource.
+      #
+      # @param [RDF::Value] resource
+      # @return [String] value to use to identify URI
+      # @raise [RDF::WriterError]
+      def get_curie(resource)
+        @_engine.get_curie(resource)
+      end
+
+      ##
+      # Haml rendering helper. Escape entities to avoid whitespace issues.
+      #
+      # # In addtion to "&<>, encode \n and \r to ensure that whitespace is properly preserved
+      #
+      # @param [String] str
+      # @return [String]
+      #   Entity-encoded string
+      def escape_entities(str)
+        CGI.escapeHTML(str).gsub(/[\n\r]/) {|c| '&#x' + c.unpack('h').first + ';'}
+      end
+    end
+  end
+end

data/lib/roadforest/content-handling/type-handlers/rdfa-writer/subject-environment.rb

@@ -0,0 +1,80 @@
+require 'roadforest/content-handling/type-handlers/rdfa-writer/render-environment'
+module RoadForest::MediaType
+  class RDFaWriter
+    class SubjectEnvironment < RenderEnvironment
+      attr_accessor :base, :element, :predicate_terms, :property_objects, :rel, :inlist, :subject, :typeof
+
+      # Write a predicate with one or more values.
+      #
+      # Values may be a combination of Literal and Resource (Node or URI).
+      # @param [RDF::Resource] predicate
+      #   Predicate to serialize
+      # @param [Array<RDF::Resource>] objects
+      #   Objects to serialize
+      # @return [String]
+      def predicate(predicate)
+        @_engine.render_predicate(subject, predicate)
+      end
+
+      def attrs
+        {:rel => rel, :resource => (about || resource), :typeof => typeof, :inlist => inlist}
+      end
+
+      def is_subject?
+        true
+      end
+
+      def predicates
+        enum_for(:each_predicate)
+      end
+
+      def each_predicate
+        predicate_terms.each do |predicate|
+          predicate = RDF::URI(predicate) if predicate.is_a?(String)
+          objects = property_objects[predicate.to_s]
+          next if objects.nil? or objects.empty?
+
+          nonlists, lists = objects.partition do |object|
+            !@_engine.is_list?(object)
+          end
+
+          add_debug {"properties with lists: #{lists} non-lists: #{nonlists}"}
+
+          ([@_engine.simple_property_env(predicate, nonlists)] + @_engine.list_property_envs(predicate, lists)).compact.each do |env|
+            yield(env)
+          end
+        end
+      end
+
+      def template_kinds
+        %w{subject}
+      end
+
+      def render_checked
+        return true if @_engine.is_done?(subject)
+        @_engine.subject_done(subject)
+        return false
+      end
+
+      def about
+        if rel.nil?
+          get_curie(subject)
+        else
+          nil
+        end
+      end
+
+      def resource
+        if rel.nil?
+          nil
+        else
+          get_curie(subject)
+        end
+      end
+
+      def yielded(pred)
+        @_engine.render(pred)
+      end
+    end
+  end
+end

data/lib/roadforest/content-handling/type-handlers/rdfa-writer.rb

@@ -0,0 +1,163 @@
+require 'cgi'
+require 'roadforest/debug'
+require 'rdf/rdfa'
+
+module RoadForest::MediaType
+  ##
+  # An RDFa 1.1 serialiser in Ruby. The RDFa serializer makes use of Haml templates, allowing runtime-replacement with alternate templates. Note, however, that templates should be checked against the W3C test suite to ensure that valid RDFa is emitted.
+  #
+  # Note that the natural interface is to write a whole graph at a time. Writing statements or Triples will create a graph to add them to and then serialize the graph.
+  #
+  # The writer will add prefix definitions, and use them for creating @prefix definitions, and minting CURIEs
+  #
+  # @example Obtaining a RDFa writer class
+  #     RDF::Writer.for(:html)          => RDF::RDFa::Writer
+  #     RDF::Writer.for("etc/test.html")
+  #     RDF::Writer.for(:file_name      => "etc/test.html")
+  #     RDF::Writer.for(:file_extension => "html")
+  #     RDF::Writer.for(:content_type   => "application/xhtml+xml")
+  #     RDF::Writer.for(:content_type   => "text/html")
+  #
+  # @example Serializing RDF graph into an XHTML+RDFa file
+  #     RDF::RDFa::Write.open("etc/test.html") do |writer|
+  #       writer << graph
+  #     end
+  #
+  # @example Serializing RDF statements into an XHTML+RDFa file
+  #     RDF::RDFa::Writer.open("etc/test.html") do |writer|
+  #       graph.each_statement do |statement|
+  #         writer << statement
+  #       end
+  #     end
+  #
+  # @example Serializing RDF statements into an XHTML+RDFa string
+  #     RDF::RDFa::Writer.buffer do |writer|
+  #       graph.each_statement do |statement|
+  #         writer << statement
+  #       end
+  #     end
+  #
+  # @example Creating @base and @prefix definitions in output
+  #     RDF::RDFa::Writer.buffer(:base_uri => "http://example.com/", :prefixes => {
+  #         :foaf => "http://xmlns.com/foaf/0.1/"}
+  #     ) do |writer|
+  #       graph.each_statement do |statement|
+  #         writer << statement
+  #       end
+  #     end
+  #
+  # @author [Gregg Kellogg](http://kellogg-assoc.com/)
+  class RDFaWriter < RDF::Writer
+    HAML_OPTIONS = {
+      :ugly => true, # to preserve whitespace without using entities
+    }
+
+    # @return [Graph] Graph of statements serialized
+    attr_accessor :graph
+
+    # @return [RDF::URI] Base URI used for relativizing URIs
+    attr_accessor :base_uri
+
+    ##
+    # Initializes the RDFa writer instance.
+    #
+    # @param  [IO, File] output
+    #   the output stream
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Boolean]  :canonicalize (false)
+    #   whether to canonicalize literals when serializing
+    # @option options [Hash]     :prefixes     (Hash.new)
+    #   the prefix mappings to use
+    # @option options [#to_s]    :base_uri     (nil)
+    #   the base URI to use when constructing relative URIs, set as html>head>base.href
+    # @option options [Boolean]  :validate (false)
+    #   whether to validate terms when serializing
+    # @option options [#to_s]   :lang   (nil)
+    #   Output as root @lang attribute, and avoid generation _@lang_ where possible
+    # @option options [Boolean]  :standard_prefixes   (false)
+    #   Add standard prefixes to _prefixes_, if necessary.
+    # @option options [Array<RDF::URI>] :top_classes ([RDF::RDFS.Class])
+    #   Defines rdf:type of subjects to be emitted at the beginning of the document.
+    # @option options [Array<RDF::URI>] :predicate_order ([RDF.type, RDF::RDFS.label, RDF::DC.title])
+    #   Defines order of predicates to to emit at begninning of a resource description..
+    # @option options [Array<RDF::URI>] :heading_predicates ([RDF::RDFS.label, RDF::DC.title])
+    #   Defines order of predicates to use in heading.
+    # @option options [String, Symbol, Hash{Symbol => String}] :haml (DEFAULT_HAML) HAML templates used for generating code
+    # @option options [Hash] :haml_options (HAML_OPTIONS)
+    #   Options to pass to Haml::Engine.new. Default options set `:ugly => false` to ensure that whitespace in literals with newlines is properly preserved.
+    # @yield  [writer]
+    # @yieldparam [RDF::Writer] writer
+    def initialize(output = $stdout, options = {}, &block)
+      super do
+        @graph = RDF::Graph.new
+        @valise = nil
+
+        block.call(self) if block_given?
+      end
+    end
+
+    ##
+    # Write whole graph
+    #
+    # @param  [Graph] graph
+    # @return [void]
+    def write_graph(graph)
+      @graph = graph
+    end
+
+    ##
+    # Addes a statement to be serialized
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @raise [RDF::WriterError] if validating and attempting to write an invalid {RDF::Term}.
+    def write_statement(statement)
+      raise RDF::WriterError, "Statement #{statement.inspect} is invalid" if validate? && statement.invalid?
+      @graph.insert(statement)
+    end
+
+    ##
+    # Addes a triple to be serialized
+    # @param  [RDF::Resource] subject
+    # @param  [RDF::URI]      predicate
+    # @param  [RDF::Value]    object
+    # @return [void]
+    # @raise  [NotImplementedError] unless implemented in subclass
+    # @abstract
+    # @raise [RDF::WriterError] if validating and attempting to write an invalid {RDF::Term}.
+    def write_triple(subject, predicate, object)
+      write_statement Statement.new(subject, predicate, object)
+    end
+
+    ##
+    # Outputs the XHTML+RDFa representation of all stored triples.
+    #
+    # @return [void]
+    def write_epilogue
+      require 'roadforest/content-handling/type-handlers/rdfa-writer/render-engine'
+      @base_uri = RDF::URI(@options[:base_uri]) if @options[:base_uri]
+      @lang = @options[:lang]
+      @debug = @options[:debug]
+      engine = RenderEngine.new(@graph, @debug) do |engine|
+        engine.valise = Valise.define do
+          ro up_to("lib") + "roadforest"
+        end
+        engine.style_name = @options[:haml]
+        engine.base_uri = base_uri
+        engine.lang = @lang
+        engine.standard_prefixes = @options[:standard_prefixes]
+        engine.top_classes = @options[:top_classes] || [RDF::RDFS.Class]
+        engine.predicate_order = @options[:predicate_order] || [RDF.type, RDF::RDFS.label, RDF::DC.title]
+        engine.heading_predicates = @options[:heading_predicates] || [RDF::RDFS.label, RDF::DC.title]
+        engine.haml_options = @options[:haml_options]
+      end
+
+      engine.prefixes.merge! @options[:prefixes] unless @options[:prefixes].nil?
+
+      # Generate document
+      rendered = engine.render_document
+
+      @output.write(rendered)
+    end
+  end
+end

data/lib/roadforest/content-handling/type-handlers/rdfa.rb

@@ -0,0 +1,175 @@
+require 'rdf/rdfa' #XXX Otherwise json-ld grabs RDFa documents. Awaiting fix upstream
+require 'roadforest/content-handling/type-handlers/rdf-handler'
+module RoadForest
+  module MediaType
+    module Handlers
+      class RESTfulRDFaWriter < ::RDF::RDFa::Writer
+        HAML = ::RDF::RDFa::Writer::BASE_HAML.merge(:property_values => %q{
+          - objects.each do |object|
+            /
+              = object.inspect
+          %div.property
+            %span.label
+              = get_predicate_name(predicate)
+            %ul
+              - objects.each do |object|
+                - if res = yield(object, :inlist => inlist, :element => :li)
+                  != res
+                - elsif object.node?
+                  %li{:property => get_curie(predicate), :resource => get_curie(object), :inlist => inlist}= get_curie(object)
+                - elsif object.uri?
+                  %li
+                    %a{:property => get_curie(predicate), :href => object.to_s, :inlist => inlist}= object.to_s
+                - elsif object.datatype == RDF.XMLLiteral
+                  %li{:property => get_curie(predicate), :lang => get_lang(object), :datatype => get_curie(object.datatype), :inlist => inlist}<!= get_value(object)
+                - else
+                  %li{:property => get_curie(predicate), :content => get_content(object), :lang => get_lang(object), :datatype => get_dt_curie(object), :inlist => inlist}= escape_entities(get_value(object))
+        })
+
+        def initialize(output = $stdout, options = nil, &block)
+          options ||= {}
+          options = {:haml => HAML}
+          super(output, options, &block)
+        end
+
+
+        # Write a predicate with one or more values.
+        #
+        # Values may be a combination of Literal and Resource (Node or URI).
+        # @param [RDF::Resource] predicate
+        #   Predicate to serialize
+        # @param [Array<RDF::Resource>] objects
+        #   Objects to serialize
+        # @return [String]
+        def predicate(predicate, objects, options = nil)
+          add_debug {"predicate: #{predicate.inspect}, objects: #{objects}"}
+
+          return if objects.to_a.empty?
+
+          add_debug {"predicate: #{get_curie(predicate)}"}
+          render_property(predicate, objects, options || {}) do |o, opts|
+            # Yields each object, for potential recursive definition.
+            # If nil is returned, a leaf is produced
+            opts = {:rel => get_curie(predicate), :element => (:li if objects.length > 1)}.merge(opts||{})
+
+            if !is_done?(o) && @subjects.include?(o)
+              depth {subject(o, opts)}
+            end
+          end
+        end
+
+
+        # Render a single- or multi-valued predicate using
+        # `haml_template[:property_value]` or
+        # `haml_template[:property_values]`. Yields each object for optional
+        # rendering. The block should only render for recursive subject
+        # definitions (i.e., where the object is also a subject and is rendered
+        # underneath the first referencing subject).
+        #
+        # If a multi-valued property definition is not found within the template, the writer will use the single-valued property definition multiple times.
+        #
+        # @param [Array<RDF::Resource>] predicate
+        #   Predicate to render.
+        # @param [Array<RDF::Resource>] objects
+        #   List of objects to render. If the list contains only a single element, the :property_value template will be used. Otherwise, the :property_values template is used.
+        # @param [Hash{Symbol => Object}] options Rendering options passed to Haml render.
+        # @option options [String] haml (haml_template[:property_value], haml_template[:property_values])
+        #   Haml template to render. Otherwise, uses `haml_template[:property_value] or haml_template[:property_values]`
+        #   depending on the cardinality of objects.
+        # @yield [object]
+        #   Yields object.
+        # @yieldparam [RDF::Resource] object
+        # @yieldreturn [String, nil]
+        #   The block should only return a string for recursive object definitions.
+        # @return String
+        #   The rendered document is returned as a string
+        def render_property(predicate, objects, options = {}, &block)
+          add_debug {"render_property(#{predicate}): #{objects.inspect}"}
+          # If there are multiple objects, and no :property_values is defined, call recursively with
+          # each object
+
+          template = options[:haml]
+          template ||= objects.length > 1 ? haml_template[:property_values] : haml_template[:property_value]
+
+          # Separate out the objects which are lists and render separately
+          list_objects = objects.select {|o| o != ::RDF.nil && ::RDF::List.new(o, @graph).valid?}
+          unless list_objects.empty?
+            # Render non-list objects
+            add_debug {"properties with lists: non-lists: #{objects - list_objects} lists: #{list_objects}"}
+            nl = render_property(predicate, objects - list_objects, options, &block) unless objects == list_objects
+            return nl.to_s + list_objects.map do |object|
+              # Render each list as multiple properties and set :inlist to true
+              list = ::RDF::List.new(object, @graph)
+              list.each_statement {|st| subject_done(st.subject)}
+
+              add_debug {"list: #{list.inspect} #{list.to_a}"}
+              render_property(predicate, list.to_a, options.merge(:inlist => "true"), &block)
+            end.join(" ")
+          end
+
+          if objects.length > 1 && template.nil?
+            # Uf there is no property_values template, render each property using property_value template
+            objects.map do |object|
+              render_property(predicate, [object], options, &block)
+            end.join(" ")
+          else
+            raise ::RDF::WriterError, "Missing property template" if template.nil?
+
+            template = options[:haml] || (
+              objects.to_a.length > 1 &&
+              haml_template.has_key?(:property_values) ?
+              :property_values :
+              :property_value)
+              options = {
+                :objects    => objects,
+                :object     => objects.first,
+                :predicate  => predicate,
+                :property   => get_curie(predicate),
+                :rel        => get_curie(predicate),
+                :inlist     => nil,
+              }.merge(options)
+              hamlify(template, options) do |object, options|
+                yield(object, options) if block_given?
+              end
+          end
+        end
+
+      end
+
+      #text/html;q=1;rdfa
+      #image/svg+xml;q=1;rdfa
+      #application/xhtml+xml;q=1;rdfa
+      #text/html
+      #image/svg+xml
+      #application/xhtml+xml
+      class RDFa < RDFHandler
+        include RDF::Normalization
+
+        def local_to_network(base_uri, rdf)
+          raise "Invalid base uri: #{base_uri}" if base_uri.nil?
+          prefixes = relevant_prefixes_for_graph(rdf)
+          prefixes.keys.each do |prefix|
+            prefixes[prefix.to_sym] = prefixes[prefix]
+          end
+          #::RDF::RDFa.debug = true
+          RESTfulRDFaWriter.buffer(:base_uri => base_uri.to_s,
+                                   :prefixes => prefixes) do |writer|
+            rdf.each_statement do |statement|
+              writer << statement
+            end
+                                   end
+        end
+
+        def network_to_local(base_uri, source)
+          raise "Invalid base uri: #{base_uri.inspect}" if base_uri.nil?
+          graph = ::RDF::Graph.new
+          reader = ::RDF::RDFa::Reader.new(source.to_s, :base_uri => base_uri.to_s)
+          reader.each_statement do |statement|
+            graph.insert(statement)
+          end
+          graph
+        end
+      end
+    end
+  end
+end