rgfa 1.2.1

data/lib/rgfa/error.rb

@@ -0,0 +1,3 @@
+# Parent class for library-specific errors
+class RGFA::Error < StandardError; end
+

data/lib/rgfa/field_array.rb

@@ -0,0 +1,87 @@
+# Array representing multiple values of the same tag in different header lines
+class RGFA::FieldArray < Array
+  attr_reader :datatype
+
+  # @param datatype [RGFA::Line::OPTFIELD_DATATYPE] the datatype to use
+  def initialize(datatype, data = [])
+    @datatype = datatype
+    super(data)
+  end
+
+  # Run a datatype-specific validation on each element of the array
+  # @param datatype [RGFA::Line::OPTFIELD_DATATYPE]
+  def validate_gfa_field!(datatype, fieldname=nil)
+    each.validate_gfa_field!(@datatype, fieldname)
+  end
+
+  # Default datatype, in this case :J
+  # @api private
+  def default_gfa_datatype
+    :J
+  end
+
+  # Representation of the field array as JSON array, with
+  # two additional values: the datatype and a zero byte as "signature".
+  # @param datatype [RGFA::Line::OPTFIELD_DATATYPE] (ignored, J is always used)
+  # @api private
+  def to_gfa_field(datatype: nil)
+    self << @datatype
+    self << "\0"
+    to_json
+  end
+
+  # Add a value to the array and validate
+  # @raise [RGFA::FieldArray::TypeMismatchError] if the type
+  #   of the new value does not correspond to the type of
+  #   existing values
+  # @param value [Object] the value to add
+  # @param type [RGFA::Line::OPTFIELD_DATATYPE, nil] the datatype to use;
+  #   if not +nil+, it will be checked that the specified datatype is the
+  #   same as for previous elements of the field array;
+  #   if +nil+, the value will be validated, according to the datatype
+  #   specified on field array creation
+  # @param fieldname [Symbol] the field name to use for error messages
+  #
+  def push_with_validation(value, type, fieldname=nil)
+    if type.nil?
+      value.validate_gfa_field!(@datatype, fieldname)
+    elsif type != @datatype
+      raise RGFA::FieldArray::TypeMismatchError,
+        "Datatype mismatch error for field #{fieldname}:\n"+
+        "value: #{value}\n"+
+        "existing datatype: #{@datatype};\n"+
+        "new datatype: #{type}"
+    end
+    self << value
+  end
+end
+
+# Generic error associated with field arrays
+class RGFA::FieldArray::Error < RGFA::Error; end
+
+# Error raised when trying to add elements with a wrong datatype
+class RGFA::FieldArray::TypeMismatchError < RGFA::Error; end
+
+class Array
+  # Is this possibly a {RGFA::FieldArray} instance?
+  #
+  # (i.e. are the two last elements a datatype symbol
+  # and a zero byte?)
+  # @return [Boolean]
+  def rgfa_field_array?
+    self[-1] == "\0" and
+      RGFA::Line::OPTFIELD_DATATYPE.include?(self[-2].to_sym)
+  end
+
+  # Create a {RGFA::FieldArray} from an array
+  # @param datatype [RGFA::Line::OPTFIELD_DATATYPE, nil] the datatype to use
+  def to_rgfa_field_array(datatype=nil)
+    if self.rgfa_field_array?
+      RGFA::FieldArray.new(self[-2].to_sym, self[0..-3])
+    elsif datatype.nil?
+      raise RGFA::FieldArray::Error, "no datatype specified"
+    else
+      RGFA::FieldArray.new(datatype, self)
+    end
+  end
+end

data/lib/rgfa/field_parser.rb

@@ -0,0 +1,109 @@
+require "json"
+require_relative "byte_array"
+require_relative "numeric_array"
+require_relative "cigar"
+require_relative "error"
+require_relative "field_array"
+
+#
+# Methods to parse the string representations of the GFA fields
+# @api private
+#
+module RGFA::FieldParser
+
+  # Parse a string representation of a GFA field value
+  # @raise [RGFA::Error] if the value is not valid
+  # @param datatype [RGFA::Line::FIELD_DATATYPE]
+  def parse_gfa_field(datatype: nil,
+                      validate_strings: true,
+                      fieldname: nil,
+                      frozen: false)
+    case datatype
+    when :A, :Z, :seq
+      validate_gfa_field!(datatype, fieldname: fieldname) if validate_strings
+      self.freeze if frozen
+      return self
+    when :lbl, :orn
+      validate_gfa_field!(datatype, fieldname: fieldname) if validate_strings
+      return to_sym.freeze
+    when :i
+      return Integer(self)
+    when :pos
+      value = Integer(self)
+      raise RGFA::FieldParser::FormatError if value < 0
+      return value
+    when :f
+      return Float(self)
+    when :H
+      value = to_byte_array
+      value.freeze if frozen
+      return value
+    when :B
+      value = to_numeric_array
+      value.freeze if frozen
+      return value
+    when :J
+      value = JSON.parse(self)
+      # RGFA convention for array of fields
+      if value.kind_of?(Array) and value.rgfa_field_array?
+        value = value.to_rgfa_field_array
+      end
+      # no need to freeze, as any Hash or Array will be valid
+      return value
+    when :cig
+      value = to_cigar
+      value.freeze if frozen
+      return value
+    when :cgs
+      value = split(",").map do |c|
+        c = c.to_cigar
+        c.freeze if frozen
+        c
+      end
+      value.freeze if frozen
+      return value
+    when :lbs
+      value = split(",").map do |l|
+        o = l[-1].to_sym
+        l = l[0..-2]
+        if validate_strings
+          l.validate_gfa_field!(:lbl, fieldname: "#{fieldname} "+
+                               "(entire field content: #{self})" )
+        end
+        os = [l.to_sym, o].to_oriented_segment
+        os.freeze if frozen
+        os
+      end
+      value.freeze if frozen
+      return value
+    else
+      raise RGFA::FieldParser::UnknownDatatypeError,
+        "Datatype unknown: #{datatype.inspect}"
+    end
+  end
+
+  # Parses an optional field in the form tagname:datatype:value
+  # and parses the value according to the datatype
+  # @raise [RGFA::FieldParser::FormatError] if the string does not represent
+  #   an optional field
+  # @return [Array(Symbol, RGFA::Line::FIELD_DATATYPE, String)]
+  #   the parsed content of the field
+  def parse_gfa_optfield
+    if self =~ /^([A-Za-z][A-Za-z0-9]):([AifZJHB]):(.+)$/
+      return $1.to_sym, $2.to_sym, $3
+    else
+      raise RGFA::FieldParser::FormatError,
+        "Expected optional field, found: #{self.inspect}"
+    end
+  end
+end
+
+# Error raised if the field content has an invalid format
+class RGFA::FieldParser::FormatError < RGFA::Error; end
+
+# Error raised if an unknown datatype symbol is used
+class RGFA::FieldParser::UnknownDatatypeError < RGFA::Error; end
+
+class String
+  include RGFA::FieldParser
+end

data/lib/rgfa/field_validator.rb

@@ -0,0 +1,241 @@
+require_relative "field_parser"
+require_relative "line"
+
+#
+# Methods to validate the string representations of the GFA fields data
+# @api private
+#
+module RGFA::FieldValidator
+
+  # Validation regular expressions, derived from the GFA specification
+  DATASTRING_VALIDATION_REGEXP = {
+    :A => /^[!-~]$/,         # Printable character
+    :i => /^[-+]?[0-9]+$/,   # Signed integer
+    :f => /^[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?$/,
+                           # Single-precision floating number
+    :Z => /^[ !-~]+$/,       # Printable string, including space
+    :J => /^[ !-~]+$/,       # JSON, excluding new-line and tab characters
+    :H => /^[0-9A-F]+$/,     # Byte array in the Hex format
+    :B => /^[cCsSiIf](,[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?)+$/,
+                           # Integer or numeric array
+    :lbl => /^[!-)+-<>-~][!-~]*$/,       # segment/path label
+    :orn => /^\+|-$/,                    # segment orientation
+    :lbs => /^[!-)+-<>-~][!-~]*[+-](,[!-)+-<>-~][!-~]*[+-])+$/,
+                           # multiple labels with orientations, comma-sep
+    :seq => /^\*$|^[A-Za-z=.]+$/,          # nucleotide sequence
+    :pos => /^[0-9]*$/,                  # positive integer
+    :cig => /^(\*|(([0-9]+[MIDNSHPX=])+))$/, # CIGAR string
+    :cgs => /^(\*|(([0-9]+[MIDNSHPX=])+))(,(\*|(([0-9]+[MIDNSHPX=])+)))*$/,
+                                       # multiple CIGARs, comma-sep
+  }
+
+  # Validates the string according to the provided datatype
+  # @param datatype [RGFA::Line::FIELD_DATATYPE]
+  # @param fieldname [#to_s] Fieldname to use in the error msg
+  # @raise [RGFA::FieldParser::FormatError] if the string does not match
+  #   the regexp for the provided datatype
+  # @return [void]
+  # @api private
+  def validate_gfa_field!(datatype, fieldname=nil)
+    regexp = DATASTRING_VALIDATION_REGEXP[datatype]
+    raise RGFA::FieldParser::UnknownDatatypeError if regexp.nil?
+    if (regexp !~ self)
+      fieldname ||= "Value"
+      raise RGFA::FieldParser::FormatError,
+        "Wrong format for field #{fieldname}: \n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}\n"+
+        "Expected regex: #{regexp}\n"
+    end
+  end
+
+end
+
+class String
+  include RGFA::FieldValidator
+end
+
+class Object
+  # @!macro [new] validate_gfa_field
+  #   Validates the object according to the provided datatype
+  #   @param datatype [RGFA::Line::FIELD_DATATYPE]
+  #   @param fieldname [#to_s] Fieldname to use in the error msg
+  #   @raise [RGFA::FieldParser::FormatError] if the object type or content
+  #     is not compatible to the provided datatype
+  #   @return [void]
+  #   @api private
+  def validate_gfa_field!(datatype, fieldname=nil)
+    raise RGFA::FieldParser::FormatError,
+      "Wrong type (#{self.class}) for field #{fieldname}\n"+
+      "Content: #{self.inspect}\n"+
+      "Datatype: #{datatype}"
+  end
+end
+
+class Symbol
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :lbl and datatype != :orn and datatype != :Z
+      raise RGFA::FieldParser::FormatError,
+        "Wrong type (#{self.class}) for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}"
+    end
+    self.to_s.validate_gfa_field!(datatype)
+  end
+end
+
+class Hash
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :J
+      raise RGFA::FieldParser::FormatError,
+        "Wrong type (#{self.class}) for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}"
+    end
+  end
+end
+
+class Array
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    begin
+      case datatype
+      when :J
+        return
+      when :Z
+        return
+      when :lbs
+        map!(&:to_oriented_segment).each(&:validate!)
+        return
+      when :cig
+        to_cigar.validate!
+        return
+      when :cgs
+        map(&:to_cigar).each(&:validate!)
+        return
+      when :B
+        to_numeric_array.validate!
+        return
+      when :H
+        to_byte_array.validate!
+        return
+      end
+    rescue => err
+      raise RGFA::FieldParser::FormatError,
+        "Invalid content for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}\n"+
+        "Error: #{err}"
+    end
+    raise RGFA::FieldParser::FormatError,
+        "Wrong type (#{self.class}) for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}"
+  end
+end
+
+class RGFA::ByteArray
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :H
+      raise RGFA::FieldParser::FormatError,
+          "Wrong type (#{self.class}) for field #{fieldname}\n"+
+          "Content: #{self.inspect}\n"+
+          "Datatype: #{datatype}"
+    end
+    begin
+      validate!
+    rescue => err
+      raise RGFA::FieldParser::FormatError,
+        "Invalid content for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}\n"+
+        "Error: #{err}"
+    end
+  end
+end
+
+class RGFA::CIGAR
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :cig
+      raise RGFA::FieldParser::FormatError,
+          "Wrong type (#{self.class}) for field #{fieldname}\n"+
+          "Content: #{self.inspect}\n"+
+          "Datatype: #{datatype}"
+    end
+    begin
+      validate!
+    rescue => err
+      raise RGFA::FieldParser::FormatError,
+        "Invalid content for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}\n"+
+        "Error: #{err}"
+    end
+  end
+end
+
+class RGFA::NumericArray
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :B
+      raise RGFA::FieldParser::FormatError,
+          "Wrong type (#{self.class}) for field #{fieldname}\n"+
+          "Content: #{self.inspect}\n"+
+          "Datatype: #{datatype}"
+    end
+    begin
+      validate!
+    rescue => err
+      raise RGFA::FieldParser::FormatError,
+        "Invalid content for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}\n"+
+        "Error: #{err}"
+    end
+  end
+end
+
+class Float
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :f and datatype != :Z
+      raise RGFA::FieldParser::FormatError,
+          "Wrong type (#{self.class}) for field #{fieldname}\n"+
+          "Content: #{self.inspect}\n"+
+          "Datatype: #{datatype}"
+    end
+  end
+end
+
+class Fixnum
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if (datatype == :pos and self < 0)
+      raise RGFA::FieldParser::FormatError,
+        "Invalid content for field #{fieldname}\n"+
+        "Content: #{self.inspect}\n"+
+        "Datatype: #{datatype}"
+    elsif ![:i, :f, :Z].include?(datatype)
+      raise RGFA::FieldParser::FormatError,
+          "Wrong type (#{self.class}) for field #{fieldname}\n"+
+          "Content: #{self.inspect}\n"+
+          "Datatype: #{datatype}"
+    end
+  end
+end
+
+class RGFA::Line::Segment
+  # @!macro validate_gfa_field
+  def validate_gfa_field!(datatype, fieldname=nil)
+    if datatype != :lbl
+      raise RGFA::FieldParser::FormatError,
+          "Wrong type (#{self.class}) for field #{fieldname}\n"+
+          "Content: <RGFA::Segment:#{self.to_s}>\n"+
+          "Datatype: #{datatype}"
+    end
+  end
+end

data/lib/rgfa/field_writer.rb

@@ -0,0 +1,108 @@
+require "json"
+require_relative "byte_array"
+require_relative "numeric_array"
+require_relative "line"
+
+#
+# Methods to convert ruby objects to the GFA string representations
+# @api private
+#
+# The default conversion is implemented in this module, which is included in
+# Object; single classes may overwrite the following methods, if necessary:
+# - {#default_gfa_datatype}, which returns the symbol of the optional
+#   field GFA datatype to use, if none is specified
+#   (See RGFA::Line::FIELD_DATATYPE); the default is :Z
+# - {#to_gfa_field} should return a GFA string representation,
+#   eventually depending on the specified datatype; no validation is done;
+#   the default is #to_s
+#
+module RGFA::FieldWriter
+
+  # @!macro [new] to_gfa_field
+  #   Representation of the data for GFA fields; this method
+  #   does not (in general) validate the string. The method
+  #   can be overwritten for a given class, and may take
+  #   the {#default_gfa_datatype} into consideration.
+  #   @return [String]
+  #   @api private
+  def to_gfa_field(datatype: nil); to_s; end
+
+  # Representation of the data as an optional field
+  # @param fieldname [Symbol] the tag name
+  # @param datatype [RGFA::Line::OPTFIELD_DATATYPE] (<i>defaults to: the value
+  #  returned by {#default_gfa_datatype}</i>)
+  # @api private
+  def to_gfa_optfield(fieldname, datatype: default_gfa_datatype)
+    return "#{fieldname}:#{datatype}:#{to_gfa_field(datatype: datatype)}"
+  end
+
+  # @!macro [new] gfa_datatype
+  #   Optional field GFA datatype to use, if none is provided
+  #   @return [RGFA::Line::FIELD_DATATYPE]
+  #   @api private
+  def default_gfa_datatype; :Z; end
+end
+
+class Object
+  include RGFA::FieldWriter
+end
+
+class Fixnum
+  # @!macro gfa_datatype
+  def default_gfa_datatype; :i; end
+end
+
+class Float
+  # @!macro gfa_datatype
+  def default_gfa_datatype; :f; end
+end
+
+class Hash
+  # @!macro to_gfa_field
+  def to_gfa_field(datatype: nil); to_json; end
+
+  # @!macro gfa_datatype
+  def default_gfa_datatype; :J; end
+end
+
+class Array
+  # @!macro to_gfa_field
+  def to_gfa_field(datatype: default_gfa_datatype)
+    case datatype
+    when :B
+      to_numeric_array.to_s
+    when :J
+      to_json
+    when :cig
+      to_cigar.to_s
+    when :cgs
+      map{|cig|cig.to_cigar.to_s}.join(",")
+    when :lbs
+      map{|os|os.to_oriented_segment.to_s}.join(",")
+    when :H
+      to_byte_array.to_s
+    else
+      map(&:to_s).join(",")
+    end
+  end
+
+  # @!macro gfa_datatype
+  def default_gfa_datatype
+    (all?{|i|i.kind_of?(Integer)} or all?{|i|i.kind_of?(Float)}) ? :B : :J
+  end
+end
+
+class RGFA::ByteArray
+  # @!macro gfa_datatype
+  def default_gfa_datatype; :H; end
+end
+
+class RGFA::NumericArray
+  # @!macro gfa_datatype
+  def default_gfa_datatype; :B; end
+end
+
+class RGFA::Line::Segment
+  # @!macro to_gfa_field
+  def to_gfa_field(datatype: nil); to_sym.to_s; end
+end