talia_core 0.5.4 → 0.7.0

data/lib/talia_core/active_source_parts/xml/generic_reader_add_statements.rb

@@ -0,0 +1,97 @@
+module TaliaCore
+  module ActiveSourceParts
+    module Xml
+      
+      # These are statements that can be used in handlers 
+      # (see GenericReaderImportStatements to learn about handlers). They will
+      # add data to the source that is currently being imported.
+      module GenericReaderAddStatements
+        
+        # Adds a value for the given predicate (may also be a database field). Example:
+        #
+        #  add :uri, "http://foobar.org" # Set the uri of the current source to http://foobar.org
+        #  add 'dct:creator', ['John Doe', 'Jane Doe'] # Sets the dct:creator property
+        #
+        # To add relations between source, see #add_rel
+        def add(predicate, object, required = false)
+          # We need to check if the object elements are already strings -
+          # otherwise we would *.to_s the PropertyString objects, which would
+          # destroy the metadata in them.
+          if(object.kind_of?(Array))
+            object.each { |obj| set_element(predicate, obj.is_a?(String) ? obj : obj.to_s, required) }
+          else
+            set_element(predicate, object.is_a?(String) ? object : object.to_s, required)
+          end
+        end
+        
+        # Works as #add, but also encodes the language (and potentially the type of the literal)
+        # into the value.
+        def add_i18n(predicate, object, lang, type=nil)
+          object = object.blank? ? nil : TaliaCore::PropertyString.new(object, lang, type)
+          add(predicate, object)
+        end
+        
+        # Adds a date field. This will attempt to parse the original string
+        # and write the result as an ISO 8061 compliant date string. Note
+        # that this won't be able to parse everything you throw at it, though.
+        def add_date(predicate, date, required = false, fmt = nil)
+          add(predicate, to_iso8601(parse_date(date, fmt)), required)
+        end
+        
+        # Adds a date interval as an ISO 8061 compliant date string. See
+        # add_date for more info. If only one of the dates is given this
+        # will add a normal date string instead of an interval.
+        def add_date_interval(predicate, start_date, end_date, fmt = nil)
+          return if(start_date.blank? && end_date.blank?)
+          if(start_date.blank?)
+            add_date(predicate, start_date, true, fmt)
+          elsif(end_date.blank?)
+            add_date(predicate, end_date, true, fmt)
+          else
+            add(predicate, "#{to_iso8601(parse_date(start_date, fmt))}/#{to_iso8601(parse_date(end_date, fmt))}", required)
+          end
+        end
+
+        # Adds a relation for the given predicate. This works as #add,
+        # but with the difference that it takes an object uri instead of 
+        # a literal value. (See the #add method to add literal values):
+        #
+        #  add_rel 'dct:create', 'local:John', 'local:Jane'
+        def add_rel(predicate, object, required = false)
+          object = check_objects(object)
+          if(!object)
+            raise(ArgumentError, "Relation with empty object on #{predicate} (#{@current.attributes['uri']}).") if(required)
+            return
+          end
+          if(object.kind_of?(Array))
+            object.each do |obj| 
+              raise(ArgumentError, "Cannot add relation on database field <#{predicate}> - <#{object.inspect}>") if(ActiveSource.db_attr?(predicate))
+              set_element(predicate, "<#{irify(obj)}>", required) 
+            end
+          else
+            raise(ArgumentError, "Cannot add relation on database field") if(ActiveSource.db_attr?(predicate))
+            set_element(predicate, "<#{irify(object)}>", required)
+          end
+        end
+
+        # Add a file to the source being imported. See the DataLoader module for a description of
+        # the possible options.
+        # 
+        # Note that the import reader will not be able to resolve URLs or file names that are relative
+        # to the original XML file or URL. File names should be absolute (otherwise they'll be treated
+        # as relative to the current Talia working directory), as should be URLs. Furthermore,
+        # the file names/paths must be valid on the machine _where the import takes place_.
+        def add_file(urls, options = {})
+          return if(urls.blank?)
+          urls = [ urls ] unless(urls.is_a?(Array))
+          files = urls.collect { |url| { :url => get_absolute_file_url(url), :options => options } }
+          @current.attributes[:files] = files if(files.size > 0)
+        end
+        
+        
+        
+      end
+      
+    end
+  end
+end

data/lib/talia_core/active_source_parts/xml/generic_reader_helpers.rb

@@ -0,0 +1,88 @@
+module TaliaCore
+  module ActiveSourceParts
+    module Xml
+      
+      # Helper methods that can be used during the import operation
+      module GenericReaderHelpers
+        
+        # Returns true if the given source was already imported. This can return false
+        # if you call this for the currently importing source. 
+        def source_exists?(uri)
+          !@sources[uri].blank?
+        end
+
+        # Returns true if the currently imported element already contains type information
+        # AND is of the given type.
+        def current_is_a?(type)
+          assit_kind_of(Class, type)
+          @current.attributes['type'] && ("TaliaCore::#{@current.attributes['type']}".constantize <= type)
+        end
+        
+        # Get the iso8601 string for the date
+        def to_iso8601(date)
+          return nil unless(date)
+          date = DateTime.parse(date) unless(date.respond_to?(:strftime))
+          date.strftime('%Y-%m-%dT%H:%M:%SZ')
+        end
+        
+        # Parses the given string and returns it as a date object
+        def parse_date(date, fmt = nil)
+          return nil if(date.blank?)
+          return DateTime.strptime(date, fmt) if(fmt) # format given
+          return DateTime.new(date.to_i) if(date.size < 5) # this short should be a year
+          DateTime.parse(date)
+        end
+        
+        # Gets an absolute path to the given file url, using the base_file_url
+        def get_absolute_file_url(url)
+          orig_url = url.to_s.strip
+          
+          url = file_url(orig_url)
+          # If a file:// was stripped from the url, this means it will always point
+          # to a file
+          force_file = (orig_url != url)
+          # Indicates wether the base url is a network url or a file/directory
+          base_is_net = !base_file_url.is_a?(String)
+          # Try to find if we have a "net" URL if we aren't sure if this is a file. In
+          # case the base url is a network url, we'll always assume that the
+          # url is also a net thing. Otherwise we only have a net url if it contains a
+          # '://' string
+          is_net_url = !force_file && (base_is_net || url.include?('://'))
+          # The url is absolute if there is a : character to be found
+          
+          
+          if(is_net_url)
+            base_is_net ? join_url(base_file_url, url) : url
+          else
+            base_is_net ? url : join_files(base_file_url, url)
+          end
+        end
+        
+        # Joins the two files. If the path is an absolute path,
+        # the base_dir is ignored
+        def join_files(base_dir, path)
+          if(Pathname.new(path).relative?)
+            File.join(base_dir, path)
+          else
+            path
+          end
+        end
+        
+        # Joins the two url parts. If the path is an absolute URL,
+        # the base_url is ignored.
+        def join_url(base_url, path)
+          return path if(path.include?(':')) # Absolute URL contains ':'
+          if(path[0..0] == '/')
+            new_url = base_url.clone
+            new_url.path = path
+            new_url.to_s
+          else
+            (base_file_url + path).to_s
+          end
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/talia_core/active_source_parts/xml/generic_reader_import_statements.rb

@@ -0,0 +1,239 @@
+module TaliaCore
+  module ActiveSourceParts
+    module Xml
+      
+      # These are the statements that are use to add handler for elements or which are
+      # used to otherwise read data for the element
+      #
+      # = What is an element handler?
+      #
+      # The methods in the Handlers submodule create element handlers. Handlers are the
+      # starting point for the import operation and are the only statements at the top
+      # level of the import description.
+      #
+      # Each handler will match a specific XML tag in the "current" XML content. At the 
+      # beginning of the import the "current" content will be either the root element
+      # or all of its child elements (depending on wether the can_use_root flag is set).
+      #
+      # The handlers will automatically attempt to match the element(s) at the starting
+      # level:
+      #
+      #  class SampleReader < GenericReader
+      #     
+      #     can_use_root CAN_BE_TRUE_OR_FALSE
+      #     
+      #     element :foo do
+      #       # Code for foo tags
+      #     end
+      #
+      #     element :bar
+      #       # Code for bar tags
+      #     end
+      #
+      #     element :foobar
+      #       # Code for foobar tags
+      #     end
+      #
+      #  end
+      # 
+      # With this importer, there would be three handlers, for "foo", "bar" and
+      # "foobar" tags. If you had the following XML
+      #
+      #  <foobar>
+      #    <foo>Hello</foo>
+      #    <bar>World</bar>
+      #  </foobar>
+      # 
+      # When reader above is run on the sample XML, the follwoing will happen:
+      #
+      # * In case can_use_root has been set to true, the importer will start
+      #   at the root element. In this case, the "Code for foobar tags" will
+      #   be executed
+      # * In case can_use_root has not been set, or set to false, the importer
+      #   will work on the elements _inside_ the root tag. This means that
+      #   it will first check the "foo" tag and call the "Code for foo tags"
+      #   and then check the the "bar" tag and call the "Code for bar tags".
+      #
+      # Obviously an XML can also contain the same element multiple times, in
+      # which case the handler will be called multiple time.
+      #
+      # = What happens inside a handler?
+      #
+      # When a handler is called, the "current" XML will be set to the inner
+      # part of the current document. That is, in case of the "foobar" handler
+      # the "current" XML would consist of the "foo" and "bar" tags (and their)
+      # content. For the "foo" and "bar" handler, the "current" XML would be
+      # just the text nodes inside it.
+      #
+      # The handler handler also has a "current" source that is being imported.
+      # In case of a handler that was declared with .element, a new, empty
+      # source is created whenever the handler is called. If the handler was
+      # declared with .plain_element, the handler "inherits" the current source
+      # that was active when it was called.
+      #
+      # Inside the handler, the GenericReaderAddStatements are used in order 
+      # to add data and properties to the current source.
+      #
+      # All handlers are executed as instance methods of the current reader.
+      #
+      # = How are handlers called?
+      #
+      # The handlers that are declared in the importer are
+      # matched against the "starting" tags in the XML and called 
+      # automatically. Inside the handler methods like #add_source can be 
+      # used to call a handler on sub-elements. Example for the
+      # reader given above (with can_use_root set):
+      #
+      #  element :foobar do
+      #    # At this point a new empty source has been created
+      #    # and is set as the "current" source. The "current" XML
+      #    # is the foo and bar tags
+      #    add_source :foo # Takes the "foo" tag and calls the handler
+      #    add_source :bar # Takes the "bar" tag and calls the handler
+      #    # Alternatively: add_source :from_all_sources -> do both automatically
+      #  end
+      #
+      # If the "foo" hanlder was defined as a .plain_element
+      #
+      #  plain_element :foo { }
+      #
+      # then the "foo" handler would inherit the source from the "foobar" handler
+      # through wich it was called.
+      #
+      # = Accessing data within in the handlers
+      #
+      # While the handlers allow you to navigate through the XML structure, you
+      # will also have to read the data in order to construct the sources.
+      #
+      # The from_* methods allow to read data from the current XML:
+      #
+      #  element :foobar do
+      #    the_thing = from_element :foo
+      #  end
+      # 
+      # In this case, inside the handler for the "foobar" tag, you attempt to
+      # read the text from the :foo element. With the XML given above, the
+      # result of this would be the string "Hello"
+      module GenericReaderImportStatements
+        
+        # Methods to create handlers. See GenericReaderImportStatements
+        module Handlers
+          
+          # Creates a handler for the element_name tag. Each time the handler
+          # is called, a new, empty source is created and set as current.
+          #
+          # The handler block will be executed as an instance method on the
+          # current reader object and the "current" XML inside the handler
+          # block will be the inner XML of the "element_name" tag that is
+          # currently being processed
+          def element(element_name, &handler_block)
+            element_handler(element_name, true, &handler_block)
+          end
+
+          # Works as #element, except that no new source is created. The 
+          # current source in the block will be the one that is active
+          # at the point where the handler was called.
+          def plain_element(element_name, &handler_block)
+            element_handler(element_name, false, &handler_block)
+          end
+          
+        end # End handlers
+        
+        # Gets the data for an attribute of the current XML element. E.g. if
+        # you have XML for
+        #
+        #  <foobar name="myself">
+        #    <foo>Hello World</foo>
+        #  </foobar>
+        #
+        # And this handler
+        #
+        #  element :foobar do
+        #    my_attr = from_attribute :name
+        #  end
+        #
+        # then the my_attr variable will be set to "myself"
+        def from_attribute(attrib) 
+          @current.element[attrib]
+        end
+
+        # Gets data from the XML tag "elem" inside the currently active XML
+        # 
+        # <foobar><foo>Hello World</foo></foobar>
+        #
+        # Inside the "foobar" handler `from_element :foo` would return
+        # "Hello World" with the XML given above.
+        def from_element(elem)
+          return @current.element.inner_text.strip if(elem == :self)
+          elements = all_elements(elem)
+          elements = elements.uniq if(elements.size > 1) # Try to ignore dupes
+          raise(ArgumentError, "More than one element of #{elem} in #{@current.element.inspect}") if(elements.size > 1)
+          elements.first
+        end
+        
+        # This works like #from_element, except that it will return an array with the
+        # values of *all* "elem" tags inside the current XML.
+        def all_elements(elem)
+          result = []
+          @current.element.search("/#{elem}").each { |el| result << el.inner_text.strip }
+          result
+        end
+        
+        # Adds a nested element. This will not change the currently importing source, but
+        # it will set the currently active XML to the nested element. 
+        # If a block is given, it will execute for each of the nested elements that
+        # are found. Otherwise, a method name must be given, and that method will
+        # be executed instead of the block
+        def nested(sub_element, handler_method = nil)
+          original_element = @current.element
+          begin
+            @current.element.search("#{sub_element}").each do |sub_elem|
+              @current.element = sub_elem
+              assit(block_given? ^ (handler_method.is_a?(Symbol)), 'Must have either a handler (x)or a block.')
+              block_given? ? yield : self.send(handler_method)
+            end
+          ensure
+            @current.element = original_element
+          end
+        end
+        
+        # Adds a source from the given sub-element. You may either pass a block with
+        # the code to import or the name of an already registered element. If the
+        # special value :from_all_sources is given, it will read from all sub-elements for which
+        # there are registered handlers.
+        #
+        # If the method is used with a block, it will call the block as a handler for the _current_
+        # element.l
+        def add_source(sub_element = nil, &block)
+          if(sub_element)
+            if(sub_element == :from_all_sources)
+              read_children_of(@current.element)
+            else
+              @current.element.search("/#{sub_element}").each { |sub_elem| read_source(sub_elem, &block) }
+            end
+          else
+            raise(ArgumentError, "When adding elements on the fly, you must use a block") unless(block)
+            attribs = call_handler(@current.element, &block)
+            add_source_with_check(attribs) if(attribs)
+          end
+        end
+        
+        # Imports another source like add_source and also assigns the new source as
+        # a part of the current one.
+        def add_part(sub_element = nil, &block)
+          raise(RuntimeError, "Cannot add child before having an uri to refer to.") unless(@current.attributes['uri'])
+          @current.element.search("/#{sub_element}").each do |sub_elem|
+            attribs = call_handler(sub_elem, &block)
+            if(attribs)
+              attribs[N::TALIA.part_of.to_s] ||= []
+              attribs[N::TALIA.part_of.to_s] << "<#{@current.attributes['uri']}>"
+              add_source_with_check(attribs)
+            end
+          end
+        end
+        
+      end
+      
+    end
+  end
+end

data/lib/talia_core/active_source_parts/xml/rdf_builder.rb

@@ -2,15 +2,19 @@ module TaliaCore
   module ActiveSourceParts
     module Xml
 
-      # Class for creating xml-rdf data
+      # Class for creating xml-rdf Data from a source. See the parent class, TaliaUtil::Xml::RdfBuilder, for
+      # more information.
       class RdfBuilder < TaliaUtil::Xml::RdfBuilder
 
+        # Builds the RDF for a source and returns the result as a string
         def self.build_source(source)
           make_xml_string { |build| build.write_source(source) }
-          end
+        end
 
-        # Writes a complete source to the rdf
+        # Builds the RDF for a source. This will include both the "direct" predicates as well as the
+        # "inverse" (incoming predicates of a source)
         def write_source(source)
+          # The source is written as subject, with all the triples nested inside it.
           @builder.rdf :Description, 'rdf:about' => source.uri.to_s do # Element describing this resource
             # loop through the predicates
             source.direct_predicates.each do |predicate|
@@ -18,6 +22,9 @@ module TaliaCore
             end
           end
 
+          # Each of the inverse properties creates another subject entry, that just contains the one
+          # triple relating it to the current source. (In this case, the subject and predicate entries
+          # aren't merged any further)
           source.inverse_predicates.each do |predicate|
             source.inverse[predicate].each do |inverse_subject|
               @builder.rdf :Description, 'rdf:about' => inverse_subject do
@@ -28,7 +35,7 @@ module TaliaCore
         end
 
 
-          end
-        end
-          end
-        end
+      end
+    end
+  end
+end