lutaml-vformat 0.1.0

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

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    module Value
+      class Boolean < Base
+        def self.native?(value)
+          [true, false].include?(value)
+        end
+
+        def self.parse(wire)
+          case wire.upcase
+          when "TRUE" then true
+          when "FALSE" then false
+          else invalid!("boolean", wire)
+          end
+        end
+
+        def self.format(value)
+          value ? "TRUE" : "FALSE"
+        end
+      end
+
+      class Integer < Base
+        def self.native?(value)
+          value.is_a?(::Integer)
+        end
+
+        def self.parse(wire)
+          invalid!("integer", wire) unless wire.match?(/\A[+-]?\d+\z/)
+
+          wire.to_i
+        end
+
+        def self.format(value)
+          Integer(value).to_s
+        end
+      end
+
+      class Float < Base
+        def self.native?(value)
+          value.is_a?(::Float)
+        end
+
+        def self.parse(wire)
+          invalid!("float", wire) unless wire.match?(/\A[+-]?\d+(\.\d+)?\z/)
+
+          wire.to_f
+        end
+
+        # Plain decimal notation, never exponent form.
+        def self.format(value)
+          number = Kernel.Float(value)
+          unless number.finite?
+            raise SerializeError, "#{value} has no vObject float form"
+          end
+
+          text = number.to_s
+          text.include?("e") ? expand(number) : text
+        end
+
+        def self.expand(number)
+          ::Kernel.format("%.17f", number).sub(/0+\z/, "").sub(/\.\z/, ".0")
+        end
+        private_class_method :expand
+      end
+
+      # +hhmm or -hhmm, optionally with seconds. Native value: signed seconds
+      # east of UTC.
+      class UtcOffset < Base
+        PATTERN = /\A([+-])(\d{2})(\d{2})(\d{2})?\z/
+
+        def self.native?(value)
+          value.is_a?(::Integer)
+        end
+
+        def self.parse(wire)
+          match = PATTERN.match(wire) or invalid!("utc-offset", wire)
+          hours, minutes, seconds = match.values_at(2, 3, 4).map(&:to_i)
+          invalid!("utc-offset", wire) if out_of_range?(hours, minutes, seconds)
+
+          total = (hours * 3600) + (minutes * 60) + seconds
+          match[1] == "-" ? -total : total
+        end
+
+        def self.out_of_range?(hours, minutes, seconds)
+          hours > 23 || minutes > 59 || seconds > 59
+        end
+        private_class_method :out_of_range?
+
+        def self.format(value)
+          seconds = Kernel.Integer(value)
+          hours, rest = seconds.abs.divmod(3600)
+          minutes, secs = rest.divmod(60)
+          sign = seconds.negative? ? "-" : "+"
+          text = ::Kernel.format("%<s>s%<h>02d%<m>02d", s: sign, h: hours,
+                                                        m: minutes)
+          secs.zero? ? text : text + ::Kernel.format("%02d", secs)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    module Value
+      class Text < Base
+        def self.escaped?
+          true
+        end
+
+        def self.native?(value)
+          value.is_a?(::String)
+        end
+
+        def self.parse(wire)
+          Escaping.unescape(wire)
+        end
+
+        def self.format(value)
+          Escaping.escape(value)
+        end
+      end
+
+      # RFC 3986 URI. Not text-escaped.
+      class Uri < Base
+        def self.native?(value)
+          value.is_a?(::String)
+        end
+
+        def self.parse(wire)
+          URI.parse(wire)
+          raise URI::InvalidURIError, wire if wire.empty?
+
+          wire
+        rescue URI::InvalidURIError
+          invalid!("URI", wire)
+        end
+
+        def self.format(value)
+          parse(value.to_s)
+        end
+      end
+
+      # RFC 5646 language tag.
+      class LanguageTag < Base
+        GRANDFATHERED = %w[
+          en-GB-oed i-ami i-bnn i-default i-enochian i-hak i-klingon i-lux
+          i-mingo i-navajo i-pwn i-tao i-tay i-tsu sgn-BE-FR sgn-BE-NL
+          sgn-CH-DE
+        ].map(&:downcase).freeze
+        ALNUM = "[a-z0-9]"
+        LANGTAG = /\A
+          (?:[a-z]{2,3}(?:-[a-z]{3}){0,3}|[a-z]{4}|[a-z]{5,8})
+          (?:-[a-z]{4})?
+          (?:-(?:[a-z]{2}|\d{3}))?
+          (?:-(?:#{ALNUM}{5,8}|\d#{ALNUM}{3}))*
+          (?:-[0-9a-wy-z](?:-#{ALNUM}{2,8})+)*
+          (?:-x(?:-#{ALNUM}{1,8})+)?
+        \z/xi
+        PRIVATE_USE = /\Ax(?:-#{ALNUM}{1,8})+\z/i
+
+        def self.native?(value)
+          value.is_a?(::String) && valid?(value)
+        end
+
+        def self.parse(wire)
+          return wire if wire.match?(LANGTAG) || wire.match?(PRIVATE_USE) ||
+            GRANDFATHERED.include?(wire.downcase)
+
+          invalid!("language-tag", wire)
+        end
+
+        def self.format(value)
+          parse(value.to_s)
+        end
+      end
+
+      # Base64 (RFC 4648 section 4), strict. The native value is a Blob: a
+      # plain binary String would be re-labelled as UTF-8 by lutaml-model's
+      # attribute casting, which would make it unreadable as raw bytes.
+      class Binary < Base
+        # Immutable holder of raw bytes.
+        class Blob
+          attr_reader :bytes
+
+          def initialize(bytes)
+            @bytes = bytes.b.freeze
+            freeze
+          end
+
+          def ==(other)
+            other.is_a?(Blob) && bytes == other.bytes
+          end
+          alias eql? ==
+
+          def hash
+            bytes.hash
+          end
+
+          def to_s
+            bytes
+          end
+        end
+
+        def self.native?(value)
+          value.is_a?(Blob)
+        end
+
+        def self.parse(wire)
+          Blob.new(wire.unpack1("m0"))
+        rescue ::ArgumentError
+          invalid!("binary", wire)
+        end
+
+        def self.format(value)
+          bytes = value.is_a?(Blob) ? value.bytes : value.to_s
+          [bytes].pack("m0")
+        end
+
+        def self.serialize(value)
+          value.nil? ? nil : format(value)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/value.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "uri"
+require_relative "value/base"
+require_relative "value/text"
+require_relative "value/scalar"
+require_relative "value/date_and_or_time"
+
+module Lutaml
+  module Vformat
+    # The vObject value types.
+    module Value
+      TYPES = {
+        text: Text,
+        uri: Uri,
+        binary: Binary,
+        boolean: Boolean,
+        integer: Integer,
+        float: Float,
+        utc_offset: UtcOffset,
+        language_tag: LanguageTag,
+        date_and_or_time: DateAndOrTime,
+      }.freeze
+
+      # RFC 6350 VALUE= parameter spellings that are not just TYPES keys.
+      ALIASES = {
+        "date" => :date_and_or_time, "time" => :date_and_or_time,
+        "date-time" => :date_and_or_time,
+        "date-and-or-time" => :date_and_or_time,
+        "timestamp" => :date_and_or_time,
+        "utc-offset" => :utc_offset, "language-tag" => :language_tag
+      }.freeze
+
+      # @param name [Symbol, String] :integer, "integer", "language-tag", ...
+      def self.for(name)
+        key = name.to_s.downcase
+        TYPES[key.tr("-",
+                     "_").to_sym] || (ALIASES[key] && TYPES[ALIASES[key]]) ||
+          raise(ArgumentError, "unknown vObject value type: #{name.inspect}")
+      end
+    end
+  end
+end

data/lib/lutaml/vformat/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    VERSION = "0.1.0"
+  end
+end

data/lib/lutaml/vformat/writer.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Vformat
+    # Components to text: CRLF line endings, lines folded at 75 octets.
+    class Writer
+      QUOTE_NEEDED = /[:;,]/
+
+      def self.write(components)
+        new.write(components)
+      end
+
+      def write(components)
+        components.flat_map { |c| component_lines(c) }
+          .map { |line| Folding.fold(line) + Folding::CRLF }.join
+      end
+
+      private
+
+      def component_lines(component)
+        [
+          "BEGIN:#{component.name}",
+          *component.properties.map { |p| property_line(p) },
+          *component.components.flat_map { |c| component_lines(c) },
+          "END:#{component.name}",
+        ]
+      end
+
+      def property_line(property)
+        head = [property.group && "#{property.group}.", property.name].join
+        params = property.params.map { |k, v| ";#{k}=#{param_values(k, v)}" }
+        "#{head}#{params.join}:#{property.value}"
+      end
+
+      def param_values(name, values)
+        values.map { |v| param_value(name, v) }.join(",")
+      end
+
+      def param_value(name, value)
+        if value.match?(/["\r\n]/)
+          raise SerializeError,
+                "parameter #{name} value #{value.inspect} contains a " \
+                "double quote or line break, which cannot be written"
+        end
+
+        value.match?(QUOTE_NEEDED) ? "\"#{value}\"" : value
+      end
+    end
+  end
+end

data/lib/lutaml/vformat.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "vformat/version"
+require_relative "vformat/errors"
+require_relative "vformat/folding"
+require_relative "vformat/escaping"
+require_relative "vformat/structured"
+require_relative "vformat/property"
+require_relative "vformat/component"
+require_relative "vformat/parser"
+require_relative "vformat/writer"
+require_relative "vformat/document"
+require_relative "vformat/value"
+require_relative "vformat/codec"
+require_relative "vformat/adapter"
+require_relative "vformat/mapping_rule"
+require_relative "vformat/mapping"
+require_relative "vformat/model_support"
+require_relative "vformat/model_reader"
+require_relative "vformat/model_writer"
+require_relative "vformat/transform"
+
+module Lutaml
+  # The vObject wire format (vCard, iCalendar) for Lutaml::Model.
+  module Vformat
+    FORMAT = :vobject
+
+    # Registers :vobject into Lutaml::Model::FormatRegistry. Runs on require;
+    # calling it again is a no-op while this gem's registration is in place.
+    def self.register!
+      registry = Lutaml::Model::FormatRegistry
+      return if registry.mappings_class_for(FORMAT) == Mapping
+
+      registry.register(
+        FORMAT,
+        mapping_class: Mapping,
+        adapter_class: Adapter,
+        transformer: Transform,
+        error_types: [ParseError],
+      )
+    end
+
+    register!
+  end
+end

data/lutaml-vformat.gemspec

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "lib/lutaml/vformat/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "lutaml-vformat"
+  spec.version = Lutaml::Vformat::VERSION
+  spec.authors = ["Ribose Inc."]
+  spec.email = ["open.source@ribose.com"]
+
+  spec.summary = "vObject wire format (RFC 6350 / RFC 5545 style) for " \
+                 "Lutaml::Model"
+  spec.description = <<~DESC
+    Parses and serializes the vObject wire format used by vCard and iCalendar:
+    BEGIN/END component nesting, property parameters, structured values, text
+    escaping and 75-octet line folding, with the vObject value types. Registers
+    the :vobject format into Lutaml::Model::FormatRegistry when required.
+  DESC
+
+  spec.homepage = "https://github.com/lutaml/lutaml-vformat"
+  spec.license = "BSD-2-Clause"
+
+  spec.required_ruby_version = Gem::Requirement.new(">= 3.0.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/releases"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features|\.github)/})
+    end
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "lutaml-model", "~> 0.8.164"
+end

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification
+name: lutaml-vformat
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Ribose Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.164
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.164
+description: |
+  Parses and serializes the vObject wire format used by vCard and iCalendar:
+  BEGIN/END component nesting, property parameters, structured values, text
+  escaping and 75-octet line folding, with the vObject value types. Registers
+  the :vobject format into Lutaml::Model::FormatRegistry when required.
+email:
+- open.source@ribose.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.md
+- README.adoc
+- Rakefile
+- lib/lutaml/vformat.rb
+- lib/lutaml/vformat/adapter.rb
+- lib/lutaml/vformat/codec.rb
+- lib/lutaml/vformat/component.rb
+- lib/lutaml/vformat/document.rb
+- lib/lutaml/vformat/errors.rb
+- lib/lutaml/vformat/escaping.rb
+- lib/lutaml/vformat/folding.rb
+- lib/lutaml/vformat/mapping.rb
+- lib/lutaml/vformat/mapping_rule.rb
+- lib/lutaml/vformat/model_reader.rb
+- lib/lutaml/vformat/model_support.rb
+- lib/lutaml/vformat/model_writer.rb
+- lib/lutaml/vformat/parser.rb
+- lib/lutaml/vformat/property.rb
+- lib/lutaml/vformat/structured.rb
+- lib/lutaml/vformat/transform.rb
+- lib/lutaml/vformat/value.rb
+- lib/lutaml/vformat/value/base.rb
+- lib/lutaml/vformat/value/date_and_or_time.rb
+- lib/lutaml/vformat/value/scalar.rb
+- lib/lutaml/vformat/value/text.rb
+- lib/lutaml/vformat/version.rb
+- lib/lutaml/vformat/writer.rb
+- lutaml-vformat.gemspec
+homepage: https://github.com/lutaml/lutaml-vformat
+licenses:
+- BSD-2-Clause
+metadata:
+  homepage_uri: https://github.com/lutaml/lutaml-vformat
+  source_code_uri: https://github.com/lutaml/lutaml-vformat
+  changelog_uri: https://github.com/lutaml/lutaml-vformat/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: vObject wire format (RFC 6350 / RFC 5545 style) for Lutaml::Model
+test_files: []