lutaml-vformat 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1b4498040b2d01535f5469b36d771aa21ba3ed86ece6149af63fe5fd2a78a71d
+  data.tar.gz: b17bc582b5a99aa90aecb71b27547ffee35accc9d74f5ea85f7a46170e1176db
+SHA512:
+  metadata.gz: a258aa0b6bae31d8ad38c57f00468917a41b290f6ac25515416f419bd4c5eeec290fda5bc66487abc90098a0a0e0bb78c9f2119471ed55a89de1a16b64da7244
+  data.tar.gz: 955446d8c4ed7d24a71473f7ef34cb24fa2e8fd8690dbbdc4bb366d41693ab9ee8db56b2835483b16d70df641d4646ba3bf5602fff78fc35ab9f6955a47647db

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/Gemfile.lock
+
+# rspec failure tracking
+.rspec_status
+
+.DS_Store
+.rubocop-https---*

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,10 @@
+# See https://github.com/metanorma/cimas
+inherit_from:
+  - https://raw.githubusercontent.com/riboseinc/oss-guides/main/ci/rubocop.yml
+
+# local repo-specific modifications
+# ...
+
+AllCops:
+  NewCops: disable
+  TargetRubyVersion: 3.0

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "rake"
+gem "rspec"
+gem "rubocop"
+gem "rubocop-performance"

data/LICENSE.md

@@ -0,0 +1,33 @@
+Licenses & Copyright
+====================
+
+This license file adheres to the formatting guidelines of
+[readable-licenses](https://github.com/nevir/readable-licenses).
+
+
+Ribose's BSD 2-Clause License
+-----------------------------
+
+Copyright (c) 2026, [Ribose Inc](https://www.ribose.com).
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1.  Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+2.  Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README.adoc

@@ -0,0 +1,172 @@
+= lutaml-vformat
+
+The vObject wire format (the line format shared by RFC 6350 vCard and RFC 5545
+iCalendar) for https://github.com/lutaml/lutaml-model[lutaml-model]. The gem
+registers a `:vobject` format into `Lutaml::Model::FormatRegistry` when it is
+required, so models gain `from_vobject` and `to_vobject`.
+
+This gem is the wire layer only. It has no vCard or iCalendar vocabulary; the
+vCard property set is a separate gem built on this one.
+
+== Installation
+
+[source,ruby]
+----
+gem "lutaml-vformat"
+----
+
+Requires `lutaml-model` `~> 0.8.164` (the version the registration API was
+measured against) and Ruby 3.0 or later.
+
+== What it covers
+
+* `BEGIN:` / `END:` component nesting to any depth
+* property parameters, including quoted values and comma-separated lists
+* property groups (`item1.TEL`)
+* structured values (`;` between fields, `,` between values in a field)
+* text escaping: backslash, comma, semicolon and newline
+* line folding at 75 octets (counted in octets, never inside a UTF-8
+  sequence) and unfolding
+* value types: text, uri, binary, boolean, integer, float, utc-offset,
+  language-tag, date-and-or-time
+
+Output uses CRLF line endings and ends with one.
+
+== Usage
+
+[source,ruby]
+----
+require "lutaml/vformat"
+
+class Phone < Lutaml::Model::Serializable
+  attribute :number, :string
+  attribute :types, :string, collection: true
+  attribute :pref, :integer
+
+  vobject do
+    type :property
+    map_value to: :number
+    map_param "TYPE", to: :types
+    map_param "PREF", to: :pref
+  end
+end
+
+class PersonName < Lutaml::Model::Serializable
+  attribute :family, :string
+  attribute :given, :string
+
+  vobject do
+    type :property
+    map_field 0, to: :family   # N:family;given
+    map_field 1, to: :given
+  end
+end
+
+class Card < Lutaml::Model::Serializable
+  attribute :fn, :string
+  attribute :n, PersonName
+  attribute :tel, Phone, collection: true
+  attribute :bday, Lutaml::Vformat::Value::DateAndOrTime
+
+  vobject do
+    type :component
+    component_root "VCARD"
+    map_property "FN", to: :fn
+    map_property "N", to: :n
+    map_property "TEL", to: :tel
+    map_property "BDAY", to: :bday
+  end
+end
+
+card = Card.from_vobject(<<~VCARD.gsub("\n", "\r\n"))
+  BEGIN:VCARD
+  FN:Jo Doe
+  N:Doe;Jo
+  TEL;TYPE=work,voice;PREF=1:+1 555 0100
+  BDAY:19850412
+  END:VCARD
+VCARD
+
+card.tel.first.types  # => ["work", "voice"]
+card.bday.kind        # => :date
+card.to_vobject       # => "BEGIN:VCARD\r\nFN:Jo Doe\r\n..."
+----
+
+=== Mapping DSL
+
+Inside `vobject do ... end`:
+
+[cols="2,5"]
+|===
+| `type :component` / `type :property` | What the model represents.
+| `component_root "NAME"` | The `BEGIN:` name of a top-level component model.
+| `map_property "NAME", to: :attr` | A content line of the component. The attribute is a scalar type or a `:property` model. Repeated lines need `collection: true`.
+| `map_component "NAME", to: :attr` | A nested `BEGIN:NAME` block; the attribute is a `:component` model.
+| `map_value to: :attr` | In a property model: the property value.
+| `map_param "NAME", to: :attr` | In a property model: a parameter. A `collection: true` attribute receives every value.
+| `map_group to: :attr` | In a property model: the group prefix.
+| `map_field index, to: :attr` | In a property model: one field of a structured value.
+|===
+
+`map_property`, `map_value`, `map_param` and `map_field` accept
+`value_type:` (`:text`, `:uri`, `:binary`, `:boolean`, `:integer`, `:float`,
+`:utc_offset`, `:language_tag`, `:date_and_or_time`). Without it the type
+comes from the attribute (`:string`, `:integer`, `:float`, `:boolean` and the
+`Lutaml::Vformat::Value` classes).
+
+=== Value types
+
+[cols="2,3,3"]
+|===
+| Type | Ruby object | Wire form
+
+| `Value::Text` | `String` | escaped
+| `Value::Uri` | `String` | as is
+| `Value::Binary` | `Value::Binary::Blob` (`#bytes`) | strict base64
+| `Value::Boolean` | `true` / `false` | `TRUE` / `FALSE`
+| `Value::Integer` | `Integer` | `-12`
+| `Value::Float` | `Float` | `1.5`, never exponent form
+| `Value::UtcOffset` | `Integer` (seconds east of UTC) | `+0530`, `-0800`
+| `Value::LanguageTag` | `String` | RFC 5646 tag
+| `Value::DateAndOrTime` | `Value::DateAndOrTime::Instant` (`#kind`, `#to_s`) | `19850412`, `--0412`, `19961022T140000Z`, `T1022`
+|===
+
+Each class has `.parse(wire)` and `.format(object)`; an invalid wire value
+raises `Lutaml::Vformat::ValueError`.
+
+=== Without models
+
+[source,ruby]
+----
+document = Lutaml::Vformat::Document.parse(text)
+event = document.component("VCALENDAR").components_named("VEVENT").first
+event.property("DTSTART").value
+event.property("DTSTART").param("TZID")
+document.to_vobject
+----
+
+Names and parameter names are case-insensitive and kept upper-case.
+Property values stay in wire (escaped) form; use `Property#text` or
+`Property#fields` for the unescaped view.
+
+== Errors
+
+Malformed input (unbalanced `BEGIN`/`END`, a line without `:`, invalid
+UTF-8, a value that does not match its type) raises
+`Lutaml::Vformat::ParseError`; through `Model.from_vobject` it surfaces as
+`Lutaml::Model::InvalidFormatError`. A parameter value that contains a double
+quote cannot be written and raises `Lutaml::Vformat::SerializeError`.
+
+== Not covered in 0.1.0
+
+* the vCard and iCalendar vocabularies
+* vCard 2.1 syntax (bare parameters such as `TEL;WORK:`, quoted-printable)
+* RFC 6868 caret encoding of parameter values
+* the `VALUE=` parameter: it is available as `Property#value_type` but models
+  neither read nor write it; name the type with `value_type:` or the
+  attribute type
+* converting `DateAndOrTime` to `Date` or `Time`
+
+== License
+
+BSD-2-Clause. See link:LICENSE.md[LICENSE.md].

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/lutaml/vformat/adapter.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # The adapter registered for :vobject. Parsing returns an Adapter (a
+    # Document); serializing wraps the Document built by the transform.
+    class Adapter < Document
+    end
+  end
+end

data/lib/lutaml/vformat/codec.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Wire text <-> attribute values. A vObject value type (or the
+    # +value_type:+ of a mapping rule) wins; plain lutaml-model String,
+    # Integer, Float and Boolean attributes use the matching vObject type;
+    # anything else is cast from the unescaped text.
+    module Codec
+      BUILTIN = {
+        Lutaml::Model::Type::String => Value::Text,
+        Lutaml::Model::Type::Integer => Value::Integer,
+        Lutaml::Model::Type::Float => Value::Float,
+        Lutaml::Model::Type::Boolean => Value::Boolean,
+      }.freeze
+
+      module_function
+
+      def value_class(type, value_type = nil)
+        return Value.for(value_type) if value_type
+        return type if type <= Value::Base
+
+        BUILTIN[type]
+      end
+
+      def read(type, wire, value_type: nil)
+        klass = value_class(type, value_type)
+        return klass.parse(wire) if klass
+
+        type.cast(Escaping.unescape(wire))
+      end
+
+      # Parameter values are never text-escaped.
+      def read_param(type, text, value_type: nil)
+        klass = value_class(type, value_type)
+        return type.cast(text) if klass.nil?
+
+        klass.escaped? ? text : klass.parse(text)
+      end
+
+      def write(type, value, value_type: nil)
+        klass = value_class(type, value_type)
+        return klass.format(value) if klass
+
+        return Value::Boolean.format(value) if [true, false].include?(value)
+
+        Escaping.escape(type.serialize(value).to_s)
+      end
+
+      def write_param(type, value, value_type: nil)
+        klass = value_class(type, value_type)
+        return value.to_s unless klass
+
+        klass.escaped? ? value.to_s : klass.format(value)
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/component.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # A BEGIN:NAME ... END:NAME block holding properties and nested components,
+    # each in document order.
+    class Component
+      attr_reader :name, :properties, :components
+
+      def initialize(name, properties: [], components: [])
+        @name = name.to_s.upcase
+        @properties = properties
+        @components = components
+      end
+
+      def properties_named(name)
+        properties.select { |p| p.name == name.to_s.upcase }
+      end
+
+      def components_named(name)
+        components.select { |c| c.name == name.to_s.upcase }
+      end
+
+      def property(name)
+        properties_named(name).first
+      end
+
+      def ==(other)
+        other.is_a?(Component) && [name, properties, components] ==
+          [other.name, other.properties, other.components]
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/document.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # A parsed vObject stream: zero or more top-level components.
+    class Document
+      attr_reader :components
+
+      def self.parse(data, _options = {})
+        new(Parser.parse(data))
+      end
+
+      def initialize(components = [], _options = {})
+        components = components.components if components.is_a?(Document)
+        @components = Array(components)
+      end
+
+      def component(name)
+        @components.find { |c| c.name == name.to_s.upcase }
+      end
+
+      def to_vobject(_options = {})
+        Writer.write(@components)
+      end
+
+      def ==(other)
+        other.is_a?(Document) && components == other.components
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    class Error < StandardError; end
+
+    # Malformed vObject input. Registered as the format's error type, so
+    # Model.from_vobject surfaces it as Lutaml::Model::InvalidFormatError.
+    class ParseError < Error; end
+
+    # A value that does not match its declared vObject value type.
+    class ValueError < ParseError; end
+
+    # A model or document that cannot be written as vObject.
+    class SerializeError < Error; end
+  end
+end

data/lib/lutaml/vformat/escaping.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Text value escaping (RFC 6350 section 3.4): backslash, semicolon and
+    # comma get a backslash prefix; a line break becomes the two characters
+    # backslash-n.
+    module Escaping
+      BACKSLASH = "\\"
+      ESCAPES = {
+        BACKSLASH => BACKSLASH * 2,
+        ";" => "#{BACKSLASH};",
+        "," => "#{BACKSLASH},",
+        "\n" => "#{BACKSLASH}n",
+      }.freeze
+      ESCAPABLE = Regexp.union(ESCAPES.keys)
+      ESCAPE_SEQUENCE = /#{Regexp.escape(BACKSLASH)}(.)/m
+      UNESCAPES = { "n" => "\n", "N" => "\n" }.freeze
+
+      module_function
+
+      def escape(text)
+        text.to_s.gsub(/\r\n|\r|\n/, "\n").gsub(ESCAPABLE, ESCAPES)
+      end
+
+      # Unknown escapes drop the backslash; a trailing lone backslash is
+      # kept literally.
+      def unescape(text)
+        text.gsub(ESCAPE_SEQUENCE) do
+          char = Regexp.last_match(1)
+          UNESCAPES.fetch(char, char)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/folding.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Line folding (RFC 6350 section 3.2, RFC 5545 section 3.1).
+    #
+    # The limit counts octets of the encoded line, not characters, and a fold
+    # never falls inside a multi-byte UTF-8 sequence. A continuation line
+    # starts with one space that counts toward its limit.
+    module Folding
+      LIMIT = 75
+      CRLF = "\r\n"
+
+      module_function
+
+      def fold(line, limit: LIMIT, eol: CRLF)
+        bytes = line.b
+        return line.dup if bytes.bytesize <= limit
+
+        chunks(bytes, limit).join("#{eol} ".b).force_encoding(line.encoding)
+      end
+
+      # The first chunk gets +limit+ octets; later ones one fewer, because
+      # each is written after a leading space.
+      def chunks(bytes, limit)
+        chunks = []
+        pos = 0
+        while pos < bytes.bytesize
+          cut = cut_point(bytes, pos, pos.zero? ? limit : limit - 1)
+          chunks << bytes.byteslice(pos, cut - pos)
+          pos = cut
+        end
+        chunks
+      end
+
+      def unfold(text)
+        text.gsub(/\r?\n[ \t]/, "")
+      end
+
+      # Largest end offset, at most +budget+ bytes after +pos+, that is not
+      # in the middle of a UTF-8 sequence.
+      def cut_point(bytes, pos, budget)
+        cut = pos + budget
+        return bytes.bytesize if cut >= bytes.bytesize
+
+        cut -= 1 while cut > pos && continuation?(bytes.getbyte(cut))
+        cut
+      end
+
+      def continuation?(byte)
+        (byte & 0xC0) == 0x80
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/mapping.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # The +vobject do ... end+ block.
+    #
+    #   vobject do
+    #     type :component            # or :property
+    #     component_root "VEVENT"    # type :component, top-level name
+    #     property_root "TEL"        # type :property, informational
+    #
+    #     map_property "SUMMARY", to: :summary
+    #     map_component "VALARM", to: :alarms
+    #
+    #     # in a property model:
+    #     map_value to: :value
+    #     map_param "TYPE", to: :types
+    #     map_group to: :group
+    #     map_field 0, to: :family   # structured value, ";"-separated
+    #   end
+    class Mapping < Lutaml::Model::Mapping
+      TYPES = %i[component property].freeze
+
+      attr_reader :mappings, :element_type, :component_name, :property_name
+
+      def initialize
+        super
+        @element_type = nil
+        @component_name = nil
+        @property_name = nil
+      end
+
+      def deep_dup
+        duped = super
+        duped.copy_roots(@element_type, @component_name, @property_name)
+        duped
+      end
+
+      def copy_roots(element_type, component_name, property_name)
+        @element_type = element_type
+        @component_name = component_name
+        @property_name = property_name
+      end
+
+      def finalize(_mapper_class)
+        @finalized = true
+      end
+
+      def finalized?
+        @finalized == true
+      end
+
+      def type(element_type)
+        unless TYPES.include?(element_type)
+          raise ArgumentError,
+                "Invalid element type: #{element_type.inspect} " \
+                "(expected one of #{TYPES.inspect})"
+        end
+
+        @element_type = element_type
+      end
+
+      def component_root(name)
+        @component_name = name.to_s.upcase
+      end
+
+      def property_root(name)
+        @property_name = name.to_s.upcase
+      end
+
+      def map_property(name, to:, value_type: nil)
+        add(name.to_s.upcase, to, :property, value_type)
+      end
+
+      def map_component(name, to:)
+        add(name.to_s.upcase, to, :component, nil)
+      end
+
+      def map_value(to:, value_type: nil)
+        add("VALUE", to, :value, value_type)
+      end
+
+      def map_param(name, to:, value_type: nil)
+        add(name.to_s.upcase, to, :param, value_type)
+      end
+
+      def map_field(index, to:, value_type: nil)
+        add(index, to, :field, value_type)
+      end
+
+      def map_group(to:)
+        add("GROUP", to, :group, nil)
+      end
+
+      def rules(kind)
+        @mappings.select { |r| r.kind == kind }
+      end
+
+      private
+
+      def add(name, to, kind, value_type)
+        @mappings << MappingRule.new(name, to: to, kind: kind,
+                                           value_type: value_type)
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/mapping_rule.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # One mapping line. +kind+ is :property, :component, :value, :param,
+    # :field or :group; +name+ is the vObject name (or field index).
+    class MappingRule < Lutaml::Model::MappingRule
+      KINDS = %i[property component value param field group].freeze
+
+      attr_reader :kind, :value_type
+
+      def initialize(name, to:, kind:, value_type: nil)
+        super(name, to: to)
+        @kind = kind
+        @value_type = value_type
+      end
+
+      def deep_dup
+        self.class.new(name.dup, to: to, kind: kind, value_type: value_type)
+      end
+    end
+  end
+end