bel 0.5.0 → 0.6.0

data/lib/bel/gen/statement.rb

@@ -0,0 +1,33 @@
+require 'bel'
+require_relative '../gen'
+BEL::Gen.soft_require('rantly')
+
+module BEL
+  module Gen
+
+    # The {Statement} module defines methods that generate random BEL
+    # {BEL::Model::Statement statements}.
+    module Statement
+      include BEL::Gen::Term
+
+      # Array of all BEL 1.0 relationships including both short and long form.
+      RELATIONSHIPS = BEL::Language::RELATIONSHIPS.each.to_a.flatten.sort.uniq
+
+      # Returns a randomly chosen relationship.
+      # @return [Symbol] the relationship label (short or long form)
+      def relationship
+        Rantly {
+          choose(*RELATIONSHIPS)
+        }
+      end
+
+      # Returns a randomly constructed BEL statement.
+      # @return [String] the statement label
+      def bel_statement
+        sub = bel_term
+        obj = bel_term
+        "#{sub} #{relationship} #{obj}"
+      end
+    end
+  end
+end

data/lib/bel/gen/term.rb

@@ -0,0 +1,33 @@
+require 'bel'
+require_relative '../gen'
+BEL::Gen.soft_require('rantly')
+
+module BEL
+  module Gen
+
+    # The {Term} module defines methods that generate random BEL
+    # {BEL::Model::Term terms}.
+    module Term
+      include BEL::Gen::Parameter
+
+      # Array of all BEL 1.0 functions including both short and long form.
+      FUNCTIONS     = BEL::Language::FUNCTIONS.map { |_, fx|
+        [ fx[:short_form], fx[:long_form] ]
+      }.flatten.sort.uniq
+
+      # Returns a randomly chosen function.
+      # @return [Symbol] the function label (short or long form)
+      def function
+        Rantly {
+          choose(*FUNCTIONS)
+        }
+      end
+
+      # Returns a randomly constructed BEL term.
+      # @return [String] the term label
+      def bel_term
+        "#{function}(#{bel_parameter})"
+      end
+    end
+  end
+end

data/lib/bel/language.rb

@@ -32,7 +32,7 @@ module BEL
           else
             self.value.to_s
           end
-        %Q{SET DOCUMENT #{self.name} = #{ensure_quotes(property_value)}}
+        %Q{SET DOCUMENT #{self.name} = #{quote_if_needed(property_value)}}
       end
       alias_method :to_s, :to_bel
     end
@@ -94,10 +94,10 @@ module BEL
 
       def to_bel
         if self.value.respond_to? :each
-          value = self.value.map {|v| always_quote(v)}
+          value = self.value.map {|v| quote(v)}
           value = "{#{value.join(',')}}"
         else
-          value = ensure_quotes(self.value)
+          value = quote_if_needed(self.value)
         end
         "SET #{self.name} = #{value}"
       end
@@ -125,7 +125,7 @@ module BEL
       end
 
       def to_bel
-        %Q{SET STATEMENT_GROUP = #{ensure_quotes(self.name)}}
+        %Q{SET STATEMENT_GROUP = #{quote_if_needed(self.name)}}
       end
 
       alias_method :to_s, :to_bel

data/lib/bel/libbel/library_resolver.rb

@@ -40,7 +40,7 @@ module BEL
 
       def compiled_library(lib_name)
         exist = File.method(:exist?)
-        compiled_library_paths(lib_name).select(&exist).first
+        compiled_library_paths(lib_name).detect(&exist)
       end
 
       def compiled_library_paths(lib_name)

data/lib/bel/namespace.rb

@@ -239,9 +239,9 @@ module BEL
     class NamespaceDefinition
       include Enumerable
 
-      attr_reader :prefix
-      attr_reader :url
-      attr_reader :rdf_uri
+      attr_accessor :prefix
+      attr_accessor :url
+      attr_accessor :rdf_uri
 
       def initialize(prefix, url, rdf_uri = DEFAULT_URI)
         @prefix = prefix

data/lib/bel/quoting.rb

@@ -1,32 +1,236 @@
 module BEL
+
+  # The Quoting module implements quoting rules consistent with BEL
+  # and BEL Script. Double quotes are used to group a string together
+  # which may contain whitespace or special characters.
+  #
+  # A value can either be an identifier or a string value. An
+  # identifier can only include the characters +[0-9A-Za-z_]+. A string
+  # value is necessary when at least one of +[^0-9A-Za-z_]+ exists in
+  # the value.
+  #
+  # Uses:
+  #
+  # BEL: The BEL parameters must be an identifier or string value.
+  #
+  # BEL Script: BEL parameters, document property values, and annotation
+  # values must be an identifier or string value.
   module Quoting
 
-    NonWordMatcher = Regexp.compile(/[^0-9a-zA-Z_]/)
-    KeywordMatcher = Regexp.compile(/^(SET|DEFINE|a|g|p|r|m)$/)
+    # Declares BEL Script keywords that cause problems with the OpenBEL
+    # Framework parser.
+    Keywords               = %w(SET DEFINE a g p r m)
 
-    def ensure_quotes identifier
-      return "" unless identifier
-      identifier.to_s.gsub! '"', '\"'
-      if quotes_required? identifier
-        %Q{"#{identifier}"}
+    # Regular expression that matches one of {Quoting::Keywords}.
+    KeywordMatcher         = Regexp.compile(/^(#{Keywords.join('|')})$/)
+
+    # Regular expression that matches on any non-word character.
+    NonWordMatcher         = Regexp.compile(/[^0-9a-zA-Z_]/)
+
+    # Regular expression that matches a value surrounded by unescaped
+    # double quotes.
+    StrictQuotedMatcher    = Regexp.compile(/\A".*?(?<!\\)"\Z/m)
+
+    # Regular expression that matches a value surrounded by double quotes
+    # that may be escaped.
+    LenientQuotedMatcher   = Regexp.compile(/\A".*?"\Z/m)
+
+    # Regular expression that matches double quotes that are not escaped.
+    QuoteNotEscapedMatcher = Regexp.compile(/(?<!\\)"/m)
+
+    # Returns +value+ surrounded by double quotes. This method is idempotent
+    # so +value+ will only be quoted once regardless of how may times the
+    # method is called on it.
+    #
+    # @example Quoting a BEL parameter.
+    #    quote("apoptotic process")
+    #    # => "\"apoptotic process\""
+    # @example Escaping quotes within a value.
+    #    quote("vesicle fusion with \"Golgi apparatus\"")
+    #    # => "\"vesicle fusion with \\\"Golgi apparatus\\\"\""
+    #
+    # @parameter [#to_s] value a value to be quoted
+    # @return    [String] value surrounded by double quotes
+    def quote(value)
+      string   = value.to_s
+      unquoted = unquote(string)
+      escaped  = unquoted.gsub(QuoteNotEscapedMatcher, "\\\"")
+      %Q{"#{escaped}"}
+    end
+
+    # Returns +value+ with surrounded quotes removed.
+    #
+    # @example Unquoting a BEL parameter.
+    #    unquote("\"apoptotic process\"")
+    #    # => "apoptotic process"
+    # @example Escaped quotes are preserved.
+    #    unquote("\"vesicle fusion with \"Golgi apparatus\"\"")
+    #
+    # @parameter [#to_s]  value a value to be unquoted
+    # @return    [String] value with surrounding double quotes removed
+    def unquote(value)
+      string = value.to_s
+      if string =~ StrictQuotedMatcher
+        string[1...-1]
+      else
+        string
+      end
+    end
+
+    # Returns +value+ with quoting applied only if necessary. A +value+
+    # consisting of only word character (e.g. [0-9A-Za-z_]) does not need
+    # quoting. A +value+ consisting of at least one non-word character
+    # (e.g. [^0-9A-Za-z_]) will requiring quoting.
+    #
+    # @example Quotes added when value includes spaces.
+    #    quote_if_needed("apoptotic process")
+    #    # => "\"apoptotic process\""
+    # @example Quotes added when value includes double quote.
+    #    quote_if_needed("vesicle fusion with \"Golgi apparatus\"")
+    #    # => "\"vesicle fusion with \\\"Golgi apparatus\\\"\""
+    # @example No quotes necessary for identifier.
+    #    quote_if_needed("AKT1_HUMAN")
+    #    # => "AKT1_HUMAN"
+    #
+    # @parameter [#to_s]  value that may be quoted
+    # @return    [String] original value or quoted value
+    def quote_if_needed(value)
+      if string_value?(value)
+        quote(value)
       else
-        identifier
+        value.to_s
       end
     end
 
+    # Returns whether the +value+ is surrounded by double quotes.
+    #
+    # @example Returns +true+ when value is quoted.
+    #    quoted?("\"vesicle fusion with \"Golgi apparatus\"")
+    #    # => true
+    # @example Returns +false+ when value is not quoted.
+    #    quoted?("apoptotic process")
+    #    # => false
+    #
+    # @parameter [#to_s]   value to test
+    # @return    [Boolean] +true+ if +value+ is quoted, +false+ if
+    #            +value+ is not quoted
+    def quoted?(value)
+      string = value.to_s
+      (string =~ LenientQuotedMatcher) != nil
+    end
+
+    # Returns whether the +value+ is not surrounded by double quotes.
+    #
+    # @example Returns +true+ when value is not quoted.
+    #    unquoted?("apoptotic process")
+    #    # => true
+    # @example Returns +false+ when value is quoted.
+    #    unquoted?("\"vesicle fusion with \"Golgi apparatus\"")
+    #    # => false
+    #
+    # @parameter [#to_s]   value to test
+    # @return    [Boolean] +true+ if +value+ is not quoted, +false+ if
+    #            +value+ is quoted
+    def unquoted?(value)
+      !quoted?(value)
+    end
+
+    # Returns whether the +value+ represents an identifier. An
+    # identifier consists of only word characters (e.g. [0-9A-Za-z_]).
+    #
+    # @example Returns +true+ when representing an identifier.
+    #    identifier_value?("AKT1_HUMAN")
+    #    # => true
+    # @example Returns +false+ when not representing an identifier.
+    #    identifier_value?("apoptotic process")
+    #    # => false
+    #
+    # @parameter [#to_s]   value to test
+    # @return    [Boolean] +true+ if +value+ is an identifier,
+    #            +false+ if +value+ is not an identifier
+    def identifier_value?(value)
+      string = value.to_s
+      [NonWordMatcher, KeywordMatcher].none? { |matcher|
+        matcher.match string
+      }
+    end
+
+    # Returns whether the +value+ represents a string value. A string
+    # value consists of at least one non-word character
+    # (e.g. [^0-9A-Za-z_]).
+    #
+    # @example Returns +true+ when representing a string value.
+    #    string_value?("apoptotic process")
+    #    # => true
+    # @example Returns +false+ when not representing a string value.
+    #    string_value?("AKT1_HUMAN")
+    #    # => false
+    #
+    # @parameter [#to_s]   value to test
+    # @return    [Boolean] +true+ if +value+ is a string value,
+    #            +false+ if +value+ is not a string value
+    def string_value?(value)
+      string = value.to_s
+      [NonWordMatcher, KeywordMatcher].any? { |matcher|
+        matcher.match string
+      }
+    end
+
+    ## Deprecated, remove in [0.6.0].
+
+    # @deprecated Use {#quote_if_needed} instead. Will be removed in a
+    #             future release.
+    def ensure_quotes identifier
+      warn <<-DOC.gsub(/^\s+/, '')
+        Deprecation Warning
+        -------------------
+        The BEL::Quoting::ensure_quotes method is deprecated and
+        will be removed in a future relase.
+        Call module method BEL::Quoting.quote_if_needed instead.
+      DOC
+      quote_if_needed(identifier)
+    end
+
+    # @deprecated Use {#unquote} instead. Will be removed in a
+    #             future release.
     def remove_quotes identifier
-      identifier.to_s.gsub!(/\A"|"\Z/, '')
-      identifier
+      warn <<-DOC.gsub(/^\s+/, '')
+        Deprecation Warning
+        -------------------
+        The BEL::Quoting::remove_quotes method is deprecated and
+        will be removed in a future relase.
+        Call module method BEL::Quoting.unquote instead.
+      DOC
+      unquote(identifier)
     end
 
+    # @deprecated Use {#quote} instead. Will be removed in a
+    #             future release.
     def always_quote identifier
-      return "" unless identifier
-      identifier.to_s.gsub! '"', '\"'
-      %Q("#{identifier}")
+      warn <<-DOC.gsub(/^\s+/, '')
+        Deprecation Warning
+        -------------------
+        The BEL::Quoting::always_quote method is deprecated and
+        will be removed in a future relase.
+        Call module method BEL::Quoting.quote instead.
+      DOC
+      quote(identifier)
     end
 
+    # @deprecated Use {#quoted?} or {#unquoted?} instead. Will be removed
+    #             in a future release.
     def quotes_required? identifier
-      [NonWordMatcher, KeywordMatcher].any? { |m| m.match identifier.to_s }
+      warn <<-DOC.gsub(/^\s+/, '')
+        Deprecation Warning
+        -------------------
+        The BEL::Quoting::quotes_required? method is deprecated and 
+        will be removed in a future relase.
+        You can use BEL::Quoting.quoted? and BEL::Quoting.unquoted?
+        going forward.
+      DOC
+      [NonWordMatcher, KeywordMatcher].any? { |m|
+        m.match identifier.to_s
+      }
     end
   end
 end

data/lib/bel/translator.rb

@@ -39,8 +39,9 @@ module BEL
       #
       # @param [#to_s] value an id, media type, or file extension value that
       #        identifies a translator plugin
-      # @return [#create_translator] if a single a translator plugin was found
-      # @return [Array<#create_translator>] if multiple translator plugins
+      # @return [nil] when no translator plugin was found
+      # @return [#create_translator] when single translator plugin was found
+      # @return [Array<#create_translator>] when multiple translator plugins
       #         were found
       def self.for(value)
         return nil unless value
@@ -57,7 +58,14 @@ module BEL
           match |= (t.file_extensions.include?(value_symbol))
           match
         }
-        matches.size == 1 ? matches.first : matches
+
+        if matches.empty?
+          nil
+        elsif matches.size == 1
+          matches.first
+        else
+          matches
+        end
       end
     end
 

data/lib/bel/translator/plugins/bel_script/bel_citation_serialization.rb

@@ -44,12 +44,12 @@ module BEL::Translator::Plugins::BelScript::BelCitationSerialization
 
     # Reset cumulative annotations if new citation.
     if cumulative_citation == nil
-      bel << %Q{SET STATEMENT_GROUP = #{ensure_quotes(evidence.citation.id)}\n}
+      bel << %Q{SET STATEMENT_GROUP = #{quote_if_needed(evidence.citation.id)}\n}
       cumulative_annotations.clear
     elsif evidence.citation != cumulative_citation
       bel << %Q{UNSET STATEMENT_GROUP\n}
       bel << "\n\n"
-      bel << %Q{SET STATEMENT_GROUP = #{ensure_quotes(evidence.citation.id)}\n}
+      bel << %Q{SET STATEMENT_GROUP = #{quote_if_needed(evidence.citation.id)}\n}
       cumulative_annotations.clear
     end
 

data/lib/bel/translator/plugins/bel_script/bel_discrete_serialization.rb

@@ -1,4 +1,4 @@
-require_relative 'evidence_serialization.rb'
+require_relative 'evidence_serialization'
 
 # BEL Script evidence serialization that writes each evidence with their full
 # set of annotations (i.e. includes all `SET` and necessary `UNSET` records).

data/lib/bel/translator/plugins/bel_script/bel_yielder.rb

@@ -25,8 +25,11 @@ module BEL::Translator::Plugins
       #         +:citation+ => {BelCitationSerialization}; otherwise the default
       #         of {BelCitationSerialization} is used
       def initialize(data, options = {})
-        @data                   = data
-        @write_header           = options.fetch(:write_header, true)
+        @data                     = data
+        @streaming                = options.fetch(:streaming, false)
+        @write_header             = options.fetch(:write_header, true)
+        @annotation_reference_map = options.fetch(:annotation_reference_map, nil)
+        @namespace_reference_map  = options.fetch(:namespace_reference_map, nil)
 
         # augment self with BEL serialization stategy.
         serialization = options[:serialization]
@@ -56,20 +59,31 @@ module BEL::Translator::Plugins
 
       def each
         if block_given?
+          combiner =
+            if @streaming
+              BEL::Model::StreamingEvidenceCombiner.new(@data)
+            elsif @annotation_reference_map && @namespace_reference_map
+              BEL::Model::MapReferencesCombiner.new(
+                @data,
+                BEL::Model::HashMapReferences.new(
+                  @annotation_reference_map,
+                  @namespace_reference_map
+                )
+              )
+            else
+              BEL::Model::BufferingEvidenceCombiner.new(@data)
+            end
+
           header_flag = true
-          @data.each { |evidence|
+          combiner.each { |evidence|
 
             # serialize evidence
             bel = to_bel(evidence)
 
             if @write_header && header_flag
               yield document_header(evidence.metadata.document_header)
-              yield namespaces(
-                evidence.references.namespaces
-              )
-              yield annotations(
-                evidence.references.annotations
-              )
+              yield namespaces(combiner.namespace_references)
+              yield annotations(combiner.annotation_references)
 
               yield <<-COMMENT.gsub(/^\s+/, '')
                 ###############################################
@@ -118,18 +132,16 @@ module BEL::Translator::Plugins
         bel
       end
 
-      def annotations(annotations)
+      def annotations(annotation_references)
         bel = <<-COMMENT.gsub(/^\s+/, '')
           ###############################################
           # Annotation Definitions Section
         COMMENT
 
-        return bel unless annotations
+        return bel unless annotation_references
 
-        annotations.reduce(bel) { |bel, annotation|
-          keyword = annotation[:keyword]
-          type    = annotation[:type]
-          domain  = annotation[:domain]
+        annotation_references.reduce(bel) { |bel, ref|
+          keyword, type, domain = ref.values_at(:keyword, :type, :domain)
           bel << "DEFINE ANNOTATION #{keyword} AS "
 
           case type.to_sym
@@ -147,18 +159,17 @@ module BEL::Translator::Plugins
         bel
       end
 
-      def namespaces(namespaces)
+      def namespaces(namespace_references)
         bel = <<-COMMENT.gsub(/^\s+/, '')
           ###############################################
           # Namespace Definitions Section
         COMMENT
 
-        return bel unless namespaces
+        return bel unless namespace_references
 
-        namespaces.reduce(bel) { |bel, namespace|
-          keyword = namespace[:keyword]
-          uri     = namespace[:uri]
-          bel << %Q{DEFINE NAMESPACE #{keyword} AS URL "#{uri}"\n}
+        namespace_references.reduce(bel) { |bel, ref|
+          keyword, url = ref.values_at(:keyword, :uri)
+          bel << %Q{DEFINE NAMESPACE #{keyword} AS URL "#{url}"\n}
           bel
         }
         bel << "\n"