lutaml-vformat 0.1.0

data/lib/lutaml/vformat/model_reader.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Components to models.
+    class ModelReader
+      include ModelSupport
+
+      def initialize(register)
+        @register = register
+      end
+
+      def component(klass, component)
+        mapping = klass.mappings_for(:vobject)
+        attrs = attrs_of(klass)
+        values = {}
+        values.update(property_values(mapping, attrs, component))
+        values.update(child_values(mapping, attrs, component))
+        build(klass, values)
+      end
+
+      private
+
+      def build(klass, values)
+        klass.new(values.reject { |_, v| v.nil? || v == [] })
+      end
+
+      def pick(attribute, list)
+        attribute.collection? ? list : list.first
+      end
+
+      def property_values(mapping, attrs, component)
+        mapping.rules(:property).to_h do |rule|
+          attribute = attrs.fetch(rule.to)
+          [rule.to, read_properties(attribute, rule, component)]
+        end
+      end
+
+      def child_values(mapping, attrs, component)
+        mapping.rules(:component).to_h do |rule|
+          attribute = attrs.fetch(rule.to)
+          children = component.components_named(rule.name).map do |child|
+            component(type_of(attribute), child)
+          end
+          [rule.to, pick(attribute, children)]
+        end
+      end
+
+      def read_properties(attribute, rule, component)
+        type = type_of(attribute)
+        list = component.properties_named(rule.name).map do |prop|
+          if property_model?(type)
+            property_model(type, prop)
+          else
+            leaf(type, prop, rule.value_type)
+          end
+        end
+        pick(attribute, list)
+      end
+
+      def leaf(type, prop, value_type)
+        Codec.read(type, prop.value, value_type: value_type)
+      end
+
+      def property_model(klass, prop)
+        mapping = klass.mappings_for(:vobject)
+        attrs = attrs_of(klass)
+        values = value_and_group(mapping, attrs, prop)
+        values.update(params(mapping, attrs, prop))
+        values.update(fields(mapping, attrs, prop))
+        build(klass, values)
+      end
+
+      def value_and_group(mapping, attrs, prop)
+        values = mapping.rules(:value).to_h do |rule|
+          type = type_of(attrs.fetch(rule.to))
+          [rule.to, leaf(type, prop, rule.value_type)]
+        end
+        mapping.rules(:group).each { |rule| values[rule.to] = prop.group }
+        values
+      end
+
+      def params(mapping, attrs, prop)
+        mapping.rules(:param).to_h do |rule|
+          attribute = attrs.fetch(rule.to)
+          type = type_of(attribute)
+          list = prop.param_values(rule.name).map do |text|
+            Codec.read_param(type, text, value_type: rule.value_type)
+          end
+          [rule.to, pick(attribute, list)]
+        end
+      end
+
+      def fields(mapping, attrs, prop)
+        rules = mapping.rules(:field)
+        return {} if rules.empty?
+
+        slots = Structured.split_raw(prop.value)
+        rules.to_h do |rule|
+          attribute = attrs.fetch(rule.to)
+          [rule.to, pick(attribute, field_values(attribute, rule, slots))]
+        end
+      end
+
+      def field_values(attribute, rule, slots)
+        type = type_of(attribute)
+        # An empty field is no value; an empty item inside a list is kept.
+        values = Array(slots[rule.name])
+        values = [] if values == [""]
+        values.map do |text|
+          Codec.read(type, text, value_type: rule.value_type)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/model_support.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Attribute and mapping lookups shared by ModelReader and ModelWriter.
+    module ModelSupport
+      private
+
+      def attrs_of(klass)
+        klass.attributes(@register)
+      end
+
+      def type_of(attribute)
+        attribute.type(@register)
+      end
+
+      def property_model?(type)
+        type.is_a?(Class) && type <= Lutaml::Model::Serialize &&
+          type.mappings_for(:vobject)&.element_type == :property
+      end
+
+      # Array() would splat Struct-based values such as
+      # DateAndOrTime::Instant.
+      def list_of(value)
+        return [] if value.nil?
+
+        value.is_a?(::Array) ? value : [value]
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/model_writer.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Models to components.
+    class ModelWriter
+      include ModelSupport
+
+      def initialize(register)
+        @register = register
+      end
+
+      def component(name, klass, model)
+        mapping = klass.mappings_for(:vobject)
+        attrs = attrs_of(klass)
+        Component.new(
+          name,
+          properties: properties(mapping, attrs, model),
+          components: children(mapping, attrs, model),
+        )
+      end
+
+      private
+
+      def properties(mapping, attrs, model)
+        mapping.rules(:property).flat_map do |rule|
+          attribute = attrs.fetch(rule.to)
+          list_of(model.public_send(rule.to)).map do |value|
+            property(rule, type_of(attribute), value)
+          end
+        end
+      end
+
+      def children(mapping, attrs, model)
+        mapping.rules(:component).flat_map do |rule|
+          type = type_of(attrs.fetch(rule.to))
+          list_of(model.public_send(rule.to)).map do |child|
+            component(rule.name, type, child)
+          end
+        end
+      end
+
+      def property(rule, type, value)
+        return property_model(rule.name, type, value) if property_model?(type)
+
+        Property.new(rule.name,
+                     Codec.write(type, value, value_type: rule.value_type))
+      end
+
+      def property_model(name, klass, model)
+        mapping = klass.mappings_for(:vobject)
+        attrs = attrs_of(klass)
+        group_rule = mapping.rules(:group).first
+        Property.new(
+          name, model_value(mapping, attrs, model),
+          params: params(mapping, attrs, model),
+          group: group_rule && model.public_send(group_rule.to)
+        )
+      end
+
+      def params(mapping, attrs, model)
+        mapping.rules(:param).each_with_object({}) do |rule, result|
+          list = param_list(rule, attrs, model)
+          result[rule.name] = list unless list.empty?
+        end
+      end
+
+      def param_list(rule, attrs, model)
+        type = type_of(attrs.fetch(rule.to))
+        list_of(model.public_send(rule.to)).map do |v|
+          Codec.write_param(type, v, value_type: rule.value_type)
+        end
+      end
+
+      def model_value(mapping, attrs, model)
+        fields = mapping.rules(:field)
+        return fields_value(fields, attrs, model) unless fields.empty?
+
+        rule = mapping.rules(:value).first
+        value = rule && model.public_send(rule.to)
+        return "" if value.nil?
+
+        Codec.write(type_of(attrs.fetch(rule.to)), value,
+                    value_type: rule.value_type)
+      end
+
+      def fields_value(rules, attrs, model)
+        slots = Array.new(rules.map(&:name).max + 1) { [] }
+        rules.each { |rule| slots[rule.name] = field_list(rule, attrs, model) }
+        Structured.join_raw(slots)
+      end
+
+      def field_list(rule, attrs, model)
+        type = type_of(attrs.fetch(rule.to))
+        list_of(model.public_send(rule.to)).map do |v|
+          Codec.write(type, v, value_type: rule.value_type)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/parser.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Lutaml
+  module Vformat
+    # Text to Components. Unfolds first, then reads content lines.
+    class Parser
+      NAME = /[A-Za-z0-9-]+/
+      BARE_ENCODINGS = %w[BASE64 QUOTED-PRINTABLE 8BIT 7BIT].freeze
+      GROUP_AND_NAME = /(?:(?<group>#{NAME})\.)?(?<name>#{NAME})/
+      PARAM_VALUE = /"[^"]*"|[^";:,]*/
+
+      def self.parse(data)
+        new(data).parse
+      end
+
+      def initialize(data)
+        @text = normalize(data)
+      end
+
+      # @return [Array<Component>] the top-level components
+      def parse
+        roots = []
+        stack = []
+        lines.each { |line, number| handle(line, number, roots, stack) }
+        unless stack.empty?
+          raise ParseError,
+                "missing END:#{stack.last.name} (unterminated component)"
+        end
+
+        roots
+      end
+
+      private
+
+      # Non-blank unfolded lines with their 1-based number. LF, CRLF and
+      # CR CR LF endings are all read.
+      def lines
+        Folding.unfold(lf_endings(@text)).split("\n").each_with_index
+          .reject { |line, _| line.strip.empty? }
+          .map { |line, index| [line, index + 1] }
+      end
+
+      # Linear, unlike a /\r+\n/ match, on long runs of CR.
+      def lf_endings(text)
+        text.split("\n", -1).map do |line|
+          line = line.chop while line.end_with?("\r")
+          line
+        end.join("\n")
+      end
+
+      def normalize(data)
+        text = data.to_s.dup.force_encoding(Encoding::UTF_8)
+        text = text.delete_prefix("")
+        raise ParseError, "input is not valid UTF-8" unless text.valid_encoding?
+
+        text
+      end
+
+      def handle(line, number, roots, stack)
+        property = parse_line(line, number)
+        case property.name
+        when "BEGIN" then open_component(property, stack)
+        when "END" then close_component(property, number, roots, stack)
+        else add_property(property, number, stack)
+        end
+      end
+
+      def open_component(property, stack)
+        stack.push(Component.new(property.value.strip))
+      end
+
+      def close_component(property, number, roots, stack)
+        name = property.value.strip.upcase
+        current = stack.pop
+        if current.nil? || current.name != name
+          raise ParseError,
+                "line #{number}: END:#{name} does not match " \
+                "#{current ? "BEGIN:#{current.name}" : 'any open component'}"
+        end
+
+        (stack.last ? stack.last.components : roots) << current
+      end
+
+      def add_property(property, number, stack)
+        if stack.empty?
+          raise ParseError,
+                "line #{number}: property outside a component"
+        end
+
+        stack.last.properties << property
+      end
+
+      def parse_line(line, number)
+        scanner = StringScanner.new(line)
+        unless scanner.scan(GROUP_AND_NAME)
+          raise ParseError, "line #{number}: invalid property name"
+        end
+
+        group = scanner[:group]
+        name = scanner[:name]
+        params = scan_params(scanner, number)
+        raise ParseError, "line #{number}: missing ':'" unless scanner.scan(":")
+
+        Property.new(name, scanner.rest, params: params, group: group)
+      end
+
+      def scan_params(scanner, number)
+        params = {}
+        while scanner.scan(";")
+          name, values = scan_param(scanner, number)
+          (params[name] ||= []).concat(values)
+        end
+        params
+      end
+
+      def scan_param(scanner, number)
+        unless scanner.scan(NAME)
+          raise ParseError, "line #{number}: invalid parameter name"
+        end
+
+        name = scanner.matched.upcase
+        return bare_param(name) unless scanner.scan("=")
+
+        [name, scan_param_values(scanner)]
+      end
+
+      # vCard 2.1 style "TEL;WORK:" or "PHOTO;BASE64:". Address books still
+      # write these in 3.0 cards, so read them as TYPE or ENCODING values.
+      def bare_param(name)
+        BARE_ENCODINGS.include?(name) ? ["ENCODING", [name]] : ["TYPE", [name]]
+      end
+
+      def scan_param_values(scanner)
+        values = []
+        loop do
+          scanner.scan(PARAM_VALUE)
+          values << scanner.matched.delete_prefix('"').delete_suffix('"')
+          break unless scanner.scan(",")
+        end
+        values
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/property.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # One content line: [group.]NAME[;PARAM=v1,v2]...:value
+    #
+    # +value+ is the raw wire text (still escaped); use #text or #fields for
+    # the unescaped views. Names and parameter names are case-insensitive and
+    # kept upper-case.
+    class Property
+      attr_reader :name, :group, :params, :value
+
+      def initialize(name, value = "", params: {}, group: nil)
+        @name = name.to_s.upcase
+        @group = group
+        @params = params.each_with_object({}) do |(k, v), h|
+          h[k.to_s.upcase] = Array(v).map(&:to_s)
+        end
+        @value = value.to_s
+      end
+
+      def param(name)
+        params[name.to_s.upcase]&.first
+      end
+
+      def param_values(name)
+        params[name.to_s.upcase] || []
+      end
+
+      # The VALUE parameter, lower-cased, or nil.
+      def value_type
+        param("VALUE")&.downcase
+      end
+
+      def text
+        Escaping.unescape(value)
+      end
+
+      def fields
+        Structured.split(value)
+      end
+
+      def ==(other)
+        other.is_a?(Property) && [name, group, params, value] ==
+          [other.name, other.group, other.params, other.value]
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/structured.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Structured values: fields separated by ";", each field holding one or
+    # more values separated by ",". Separators are only those not escaped
+    # with a backslash.
+    module Structured
+      module_function
+
+      # @return [Array<Array<String>>] fields, each an array of unescaped values
+      def split(raw)
+        split_raw(raw).map { |field| field.map { |v| Escaping.unescape(v) } }
+      end
+
+      # Like #split, but values stay in wire (escaped) form.
+      def split_raw(raw)
+        split_unescaped(raw, ";").map { |field| split_unescaped(field, ",") }
+      end
+
+      # Joins fields of already-escaped values.
+      def join_raw(fields)
+        fields.map { |field| Array(field).join(",") }.join(";")
+      end
+
+      # @param fields [Array<String, Array<String>, nil>]
+      def join(fields)
+        fields.map do |field|
+          Array(field).map { |v| Escaping.escape(v) }.join(",")
+        end.join(";")
+      end
+
+      # Splits on +separator+ except where a backslash escapes it; the
+      # backslashes stay in the parts.
+      def split_unescaped(raw, separator)
+        parts = [+""]
+        raw.scan(/\\.|./m) do |token|
+          token == separator ? parts << +"" : parts.last << token
+        end
+        parts
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/transform.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # The transformer registered for :vobject: models from a parsed Document
+    # and Documents from models.
+    class Transform < Lutaml::Model::Transform
+      def self.data_to_model(context, data, _format, options = {})
+        new(context, options[:register]).data_to_model(data)
+      end
+
+      def self.model_to_data(context, model, _format, options = {})
+        new(context, options[:register]).model_to_data(model)
+      end
+
+      def data_to_model(document)
+        mapping = context.mappings_for(:vobject)
+        name = mapping.component_name
+        root = document.components.find { |c| name.nil? || c.name == name }
+        unless root
+          raise ParseError,
+                "no #{name || 'component'} component in the input"
+        end
+
+        ModelReader.new(lutaml_register).component(context, root)
+      end
+
+      def model_to_data(model)
+        name = context.mappings_for(:vobject).component_name
+        unless name
+          raise SerializeError,
+                "#{context} declares no component_root, so it cannot be " \
+                "written as a top-level component"
+        end
+
+        writer = ModelWriter.new(lutaml_register)
+        Document.new([writer.component(name, context, model)])
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/value/base.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    module Value
+      # A vObject value type. Subclasses define .parse (wire text to a Ruby
+      # object, raising ValueError) and .format (Ruby object to wire text).
+      # They are also lutaml-model attribute types: assigning wire text or a
+      # native object casts to the native object.
+      class Base < Lutaml::Model::Type::Value
+        # Whether wire text of this type is subject to text escaping.
+        def self.escaped?
+          false
+        end
+
+        def self.cast(value, _options = EMPTY_OPTIONS)
+          return nil if value.nil?
+          return value if Lutaml::Model::Utils.uninitialized?(value)
+
+          native?(value) ? value : parse(value.to_s)
+        end
+
+        def self.valid?(wire)
+          parse(wire)
+          true
+        rescue ValueError
+          false
+        end
+
+        def self.from_vobject(wire)
+          parse(wire)
+        end
+
+        def self.native?(_value)
+          false
+        end
+
+        def self.invalid!(type_name, wire)
+          raise ValueError, "#{wire.inspect} is not a valid #{type_name} value"
+        end
+        private_class_method :invalid!
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/value/date_and_or_time.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    module Value
+      # RFC 6350 section 4.3.4 date-and-or-time (and the extended ISO 8601
+      # spellings vCard 3.0 / iCalendar producers emit). The native value
+      # keeps the exact text and classifies it.
+      class DateAndOrTime < Base
+        Instant = Struct.new(:kind, :text) do
+          include Comparable
+
+          def to_s
+            text
+          end
+
+          def <=>(other)
+            other.is_a?(Instant) ? text <=> other.text : nil
+          end
+        end
+
+        MONTH = "(?<mo>0[1-9]|1[0-2])"
+        DAY = "(?<dd>0[1-9]|[12]\\d|3[01])"
+        HOUR = "(?<hh>[01]\\d|2[0-3])"
+        MINUTE = "(?<mi>[0-5]\\d)"
+        SECOND = "(?<ss>[0-5]\\d|60)"
+        ZONE = "(?:Z|[+-](?:[01]\\d|2[0-3])(?::?[0-5]\\d)?)"
+        YEAR = "\\d{4}"
+
+        DATE_NOREDUC = [
+          "#{YEAR}-#{MONTH}-#{DAY}", "#{YEAR}#{MONTH}#{DAY}",
+          "--#{MONTH}-?#{DAY}", "---#{DAY}"
+        ].join("|").freeze
+        DATE = [
+          DATE_NOREDUC, "#{YEAR}-#{MONTH}", YEAR, "--#{MONTH}"
+        ].join("|").freeze
+        TIME_NOTRUNC = "#{HOUR}(?::?#{MINUTE}(?::?#{SECOND})?)?#{ZONE}?".freeze
+        TIME = [
+          TIME_NOTRUNC, "-#{MINUTE}(?::?#{SECOND})?#{ZONE}?",
+          "--#{SECOND}#{ZONE}?"
+        ].join("|").freeze
+
+        DATE_RE = /\A(?:#{DATE})\z/
+        DATE_TIME_RE = /\A(?:#{DATE_NOREDUC})T(?:#{TIME_NOTRUNC})\z/
+        TIME_RE = /\AT(?:#{TIME})\z/
+
+        def self.native?(value)
+          value.is_a?(Instant)
+        end
+
+        def self.parse(wire)
+          kind = if DATE_TIME_RE.match?(wire) then :date_time
+                 elsif DATE_RE.match?(wire) then :date
+                 elsif TIME_RE.match?(wire) then :time
+                 else invalid!("date-and-or-time", wire)
+                 end
+          Instant.new(kind, wire).freeze
+        end
+
+        def self.format(value)
+          value.is_a?(Instant) ? value.text : parse(value.to_s).text
+        end
+
+        def self.serialize(value)
+          value.nil? ? nil : format(value)
+        end
+      end
+    end
+  end
+end