jcard_jcal 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 299d8848386a5c2d4135c70971b2d3d86c936e6b30d4a10dd566decf2e6ce209
+  data.tar.gz: f1a458a16b7372f372c923dc1e38c3948582f017f818b622e7e33efd0ec39d96
+SHA512:
+  metadata.gz: c11c6411c6e8ade8821fdabce43e460599d4cd2dfdaab6d2de912361d91e49e6e535b63dfed4bdae62783d5fd7ae6d012f30e6deb3aea38f64a20f007ac99d0b
+  data.tar.gz: 8e56ea0a3543d5885da109c88fdc0c303e21287a2f5adce38774ada875b95ff06d6f7aca5855e67b5a129661e1a7af91662896e4b306481d73c19841de6425f0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-10-11
+
+Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+# jcard_jcal
+
+Convert vCard 4.0 and iCalendar text to and from their JSON representations,
+[jCard (RFC 7095)](https://www.rfc-editor.org/rfc/rfc7095) and
+[jCal (RFC 7265)](https://www.rfc-editor.org/rfc/rfc7265).
+Requires Ruby 3.3 or later and json 2.19.4 or later (including json 3.x).
+
+```sh
+gem install jcard_jcal
+```
+
+```ruby
+require "jcard_jcal" # or require "jcard" / require "jcal"
+
+card = JCard.from_vcard("BEGIN:VCARD\nVERSION:4.0\nFN:Alice\nEND:VCARD\n").first
+card.properties("fn").first.values # => ["Alice"]
+card.to_json                       # => '["vcard",[["version",{},"text","4.0"],["fn",{},"text","Alice"]]]'
+card.to_vcard                      # CRLF line endings, UTF-8 safe folding
+
+calendar = JCal.from_ical(File.read("calendar.ics"))
+calendar.components("vevent").each do |event|
+  puts event.property("dtstart")&.values
+end
+JCal.parse(calendar.to_json).to_ical
+```
+
+`JCard.from_vcard` returns an array because a text document can contain several
+cards. `JCard.parse` and `JCal.parse` each read one JSON component. Properties retain
+their order. `to_a`, `params`, and `values` return copies; unknown properties,
+parameters, and explicitly declared extension value types are preserved.
+
+## Supported formats
+
+| Supported | Outside this library's scope |
+| --- | --- |
+| vCard 4.0 ↔ jCard | vCard 2.1/3.0, xCard |
+| Nested iCalendar ↔ jCal | Calendar semantic rules such as mandatory DTSTART |
+| RFC 6350/5545 value types, partial dates, structured values | Time zone conversion and recurrence expansion |
+| RFC 7529 recurrence syntax, including RSCALE/SKIP and leap months | Non-Gregorian calendar calculations |
+| RFC 6868 parameter escaping and 75-octet line folding | CardDAV/CalDAV transport, URL fetching |
+| RFC 7986 calendar properties and RFC 9554 contact extensions | Other extension-specific semantics without a custom registry |
+
+Text serialization normalizes capitalization, parameter order, folding, and
+VERSION placement. It selects the scalar form for a single structured component
+and a single parameter value. Binary iCalendar output includes `ENCODING=BASE64`.
+These equivalent forms need not retain identical JSON array shapes or parameters
+after a round trip. Recurrence rule object keys are lowercase; value case is
+preserved. Numeric spelling is normalized, and jCard integer output follows
+RFC 7095's truncation rule for fractional JSON numbers.
+
+## Validation and limits
+
+Parsing is strict by default. Syntax failures raise `JCardJCal::ParseError`;
+property violations raise `ValidationError` or its subclass `ValueError`.
+Errors expose `line_number` for text input or `pointer` for JSON input.
+`JcardJcal` remains an alias for compatibility with the generated gem namespace.
+
+```ruby
+card = JCard.from_vcard(text, strict: false).first
+card.warnings.each { |warning| warn warning.message }
+```
+
+Lenient text parsing retains an invalid property value as type `unknown` and
+records a warning. Lenient JSON parsing retains invalid values with warnings.
+Malformed structures, component boundaries, duplicate JSON keys, and resource
+limit violations still raise errors. Generation always validates the model.
+Binary values remain encoded; the library does not decode attachments.
+
+Both entry points accept the following limits:
+
+| Option | Default |
+| --- | ---: |
+| `max_input_size` | 16 MiB |
+| `max_line_length` | 1 MiB per unfolded content line |
+| `max_properties` | 10,000 across the input |
+| `max_depth` | 32 component levels |
+| `max_binary_size` | 1 MiB of decoded attachment data |
+
+```ruby
+JCal.from_ical(text, max_depth: 8, max_properties: 1000)
+```
+
+## Custom properties
+
+Default registries are frozen. Duplicate one to add application-specific defaults
+without affecting other callers:
+
+```ruby
+registry = JCard::Registry.default.dup
+registry.register("x-website", type: "uri")
+card = JCard.from_vcard(text, registry: registry).first
+card.to_vcard # reuses the same registry
+```
+
+Register a multiple-valued property with `multiple: true`, or a semicolon-separated
+structured property with `structured: true`. An unregistered property without a
+VALUE parameter uses `unknown`, keeping the raw content-line value.
+Register structured or multiple-valued extensions before converting them through
+text; their separators cannot otherwise be distinguished from literal values.
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+COVERAGE=1 bundle exec rake test
+bundle exec rubocop
+bundle exec rbs -I sig validate
+```
+
+The first test run needs `curl` and HTTPS access to RFC Editor to prepare fixtures
+under ignored `tmp/rfc/`; later runs reuse verified source downloads. Before
+running RSpec directly, run `bundle exec rake fixtures`. See
+[conformance maintenance](docs/conformance.md) for fixture updates, property
+tables, and interoperability checks.
+
+## Releases
+
+Update `lib/jcard_jcal/version.rb` and add a user-facing entry to `CHANGELOG.md`,
+then push the matching `vVERSION` tag after main's checks pass. The tag workflow
+tests, builds, publishes to RubyGems, and creates a GitHub release from that entry.
+Documentation-only and internal maintenance changes do not need a release.
+
+Before the first tag, configure a RubyGems trusted publisher for gem `jcard_jcal`,
+owner `ydah`, repository `jcard_jcal`, workflow `release.yml`, and environment
+`release`.
+
+## License
+
+MIT; see [LICENSE.txt](LICENSE.txt). Downloaded RFC documents and generated test
+fixtures are excluded from Git and the gem and retain their own
+[license notices](docs/conformance.md#rfc-examples).

data/SECURITY.md

@@ -0,0 +1,10 @@
+# Security
+
+Report security issues privately to t.yudai92@gmail.com. Include the affected
+version and a small reproduction. Do not include private contact or calendar
+data. Security fixes target the latest released version.
+
+The library does not fetch URLs, evaluate recurrence rules, or decode binary
+attachments automatically. Input size, content-line length, component depth,
+property count, and binary attachment size are bounded. Keep those limits in
+place when processing untrusted input.

data/data/ical_properties.yml

@@ -0,0 +1,52 @@
+calscale: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.7.1'}
+method: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.7.2'}
+prodid: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.7.3'}
+version: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.7.4'}
+attach: {type: uri, types: [uri, binary], multiple: false, structured: false, source: 'RFC5545 3.8.1.1'}
+categories: {type: text, types: [text], multiple: true, structured: false, source: 'RFC5545 3.8.1.2'}
+class: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.1.3'}
+comment: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.1.4'}
+description: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.1.5'}
+geo: {type: float, types: [float], multiple: false, structured: true, source: 'RFC5545 3.8.1.6', components: [2]}
+location: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.1.7'}
+percent-complete: {type: integer, types: [integer], multiple: false, structured: false, source: 'RFC5545 3.8.1.8'}
+priority: {type: integer, types: [integer], multiple: false, structured: false, source: 'RFC5545 3.8.1.9'}
+resources: {type: text, types: [text], multiple: true, structured: false, source: 'RFC5545 3.8.1.10'}
+status: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.1.11'}
+summary: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.1.12'}
+completed: {type: date-time, types: [date-time], multiple: false, structured: false, source: 'RFC5545 3.8.2.1'}
+dtend: {type: date-time, types: [date-time, date], multiple: false, structured: false, source: 'RFC5545 3.8.2.2'}
+due: {type: date-time, types: [date-time, date], multiple: false, structured: false, source: 'RFC5545 3.8.2.3'}
+dtstart: {type: date-time, types: [date-time, date], multiple: false, structured: false, source: 'RFC5545 3.8.2.4'}
+duration: {type: duration, types: [duration], multiple: false, structured: false, source: 'RFC5545 3.8.2.5'}
+freebusy: {type: period, types: [period], multiple: true, structured: false, source: 'RFC5545 3.8.2.6'}
+transp: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.2.7'}
+tzid: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.3.1'}
+tzname: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.3.2'}
+tzoffsetfrom: {type: utc-offset, types: [utc-offset], multiple: false, structured: false, source: 'RFC5545 3.8.3.3'}
+tzoffsetto: {type: utc-offset, types: [utc-offset], multiple: false, structured: false, source: 'RFC5545 3.8.3.4'}
+tzurl: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC5545 3.8.3.5'}
+attendee: {type: cal-address, types: [cal-address], multiple: false, structured: false, source: 'RFC5545 3.8.4.1'}
+contact: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.4.2'}
+organizer: {type: cal-address, types: [cal-address], multiple: false, structured: false, source: 'RFC5545 3.8.4.3'}
+recurrence-id: {type: date-time, types: [date-time, date], multiple: false, structured: false, source: 'RFC5545 3.8.4.4'}
+related-to: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.4.5'}
+url: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC5545 3.8.4.6'}
+uid: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.4.7'}
+exdate: {type: date-time, types: [date-time, date], multiple: true, structured: false, source: 'RFC5545 3.8.5.1'}
+rdate: {type: date-time, types: [date-time, date, period], multiple: true, structured: false, source: 'RFC5545 3.8.5.2'}
+rrule: {type: recur, types: [recur], multiple: false, structured: false, source: 'RFC5545 3.8.5.3'}
+action: {type: text, types: [text], multiple: false, structured: false, source: 'RFC5545 3.8.6.1'}
+repeat: {type: integer, types: [integer], multiple: false, structured: false, source: 'RFC5545 3.8.6.2'}
+trigger: {type: duration, types: [duration, date-time], multiple: false, structured: false, source: 'RFC5545 3.8.6.3'}
+created: {type: date-time, types: [date-time], multiple: false, structured: false, source: 'RFC5545 3.8.7.1'}
+dtstamp: {type: date-time, types: [date-time], multiple: false, structured: false, source: 'RFC5545 3.8.7.2'}
+last-modified: {type: date-time, types: [date-time], multiple: false, structured: false, source: 'RFC5545 3.8.7.3'}
+sequence: {type: integer, types: [integer], multiple: false, structured: false, source: 'RFC5545 3.8.7.4'}
+request-status: {type: text, types: [text], multiple: false, structured: true, source: 'RFC5545 3.8.8.3', components: [2, 3]}
+name: {type: text, types: [text], multiple: false, structured: false, source: 'RFC7986 5.1'}
+refresh-interval: {type: unknown, types: [duration], multiple: false, structured: false, source: 'RFC7986 5.7', value_required: true}
+source: {type: unknown, types: [uri], multiple: false, structured: false, source: 'RFC7986 5.8', value_required: true}
+color: {type: text, types: [text], multiple: false, structured: false, source: 'RFC7986 5.9'}
+image: {type: unknown, types: [uri, binary], multiple: false, structured: false, source: 'RFC7986 5.10', value_required: true}
+conference: {type: unknown, types: [uri], multiple: false, structured: false, source: 'RFC7986 5.11', value_required: true}

data/data/vcard_properties.yml

@@ -0,0 +1,42 @@
+# Property defaults and value shapes; cardinality is separate from multiple values on one line.
+source: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.1.3'}
+kind: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.1.4'}
+xml: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.1.5'}
+fn: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.2.1'}
+n: {type: text, types: [text], multiple: false, structured: true, source: 'RFC6350 6.2.2', component_multiple: true, components: [5, 7], extension_source: 'RFC9554 2.2'}
+nickname: {type: text, types: [text], multiple: true, structured: false, source: 'RFC6350 6.2.3'}
+photo: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.2.4'}
+bday: {type: date-and-or-time, types: [date-and-or-time, date, time, date-time, text], multiple: false, structured: false, source: 'RFC6350 6.2.5', conversion_source: 'RFC7095 3.5.3'}
+anniversary: {type: date-and-or-time, types: [date-and-or-time, date, time, date-time, text], multiple: false, structured: false, source: 'RFC6350 6.2.6', conversion_source: 'RFC7095 3.5.5'}
+gender: {type: text, types: [text], multiple: false, structured: true, source: 'RFC6350 6.2.7', components: [1, 2]}
+adr: {type: text, types: [text], multiple: false, structured: true, source: 'RFC6350 6.3.1', component_multiple: true, components: [7, 18], extension_source: 'RFC9554 2.1'}
+tel: {type: text, types: [text, uri], multiple: false, structured: false, source: 'RFC6350 6.4.1'}
+email: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.4.2'}
+impp: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.4.3'}
+lang: {type: language-tag, types: [language-tag], multiple: false, structured: false, source: 'RFC6350 6.4.4'}
+tz: {type: text, types: [text, uri, utc-offset], multiple: false, structured: false, source: 'RFC6350 6.5.1'}
+geo: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.5.2'}
+title: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.6.1'}
+role: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.6.2'}
+logo: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.6.3'}
+org: {type: text, types: [text], multiple: false, structured: true, source: 'RFC6350 6.6.4'}
+member: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.6.5'}
+related: {type: uri, types: [uri, text], multiple: false, structured: false, source: 'RFC6350 6.6.6'}
+categories: {type: text, types: [text], multiple: true, structured: false, source: 'RFC6350 6.7.1'}
+note: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.7.2'}
+prodid: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.7.3'}
+rev: {type: timestamp, types: [timestamp], multiple: false, structured: false, source: 'RFC6350 6.7.4'}
+sound: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.7.5'}
+uid: {type: uri, types: [uri, text], multiple: false, structured: false, source: 'RFC6350 6.7.6'}
+clientpidmap: {type: text, types: [text], multiple: false, structured: true, source: 'RFC6350 6.7.7', components: [2]}
+url: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.7.8'}
+version: {type: text, types: [text], multiple: false, structured: false, source: 'RFC6350 6.7.9'}
+key: {type: uri, types: [uri, text], multiple: false, structured: false, source: 'RFC6350 6.8.1'}
+fburl: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.9.1'}
+caladruri: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.9.2'}
+caluri: {type: uri, types: [uri], multiple: false, structured: false, source: 'RFC6350 6.9.3'}
+created: {type: timestamp, types: [timestamp], multiple: false, structured: false, source: 'RFC9554 3.1'}
+gramgender: {type: text, types: [text], multiple: false, structured: false, source: 'RFC9554 3.2'}
+language: {type: language-tag, types: [language-tag], multiple: false, structured: false, source: 'RFC9554 3.3'}
+pronouns: {type: text, types: [text], multiple: false, structured: false, source: 'RFC9554 3.4'}
+socialprofile: {type: uri, types: [uri, text], multiple: false, structured: false, source: 'RFC9554 3.5'}

data/lib/jcal.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "jcard_jcal"
+
+module JCal
+  # An iCalendar property in RFC 7265 array form.
+  class Property < JCardJCal::Property
+    private
+
+    def default_registry = Registry.default
+    def format = :ical
+  end
+
+  # An iCalendar component, including vendor components.
+  class Component < JCardJCal::Component
+    def to_ical = to_text(:ical)
+  end
+
+  class Calendar < Component; end
+
+  # Parse one jCal JSON document.
+  def self.parse(source, **)
+    JCardJCal::Converter.new(format: :ical, **).parse_json(source)
+  end
+
+  # Convert a VCALENDAR text document and its nested components.
+  def self.from_ical(source, **)
+    JCardJCal::Converter.new(format: :ical, **).parse_text(source)
+  end
+end

data/lib/jcard.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require_relative "jcard_jcal"
+
+module JCard
+  # A vCard property in RFC 7095 array form.
+  class Property < JCardJCal::Property
+    private
+
+    def default_registry = Registry.default
+    def format = :vcard
+  end
+
+  # A vCard 4.0 represented as jCard.
+  class Card < JCardJCal::Component
+    def to_vcard = to_text(:vcard)
+  end
+
+  # Parse one jCard JSON document. Lenient parsing attaches validation warnings.
+  def self.parse(source, **)
+    JCardJCal::Converter.new(format: :vcard, **).parse_json(source)
+  end
+
+  # Convert one or more vCards to ordered card objects.
+  def self.from_vcard(source, **)
+    JCardJCal::Converter.new(format: :vcard, **).parse_text(source)
+  end
+end

data/lib/jcard_jcal/component.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module JCardJCal
+  # Ordered properties and nested components with lossless JSON serialization.
+  class Component
+    attr_reader :name, :warnings
+
+    def initialize(name, properties, components = [], warnings: [], registry: nil, max_binary_size: 1_048_576)
+      @name = name
+      @properties = properties
+      @components = components
+      @warnings = warnings
+      @registry = registry
+      @max_binary_size = max_binary_size
+    end
+
+    def properties(name = nil)
+      return @properties.dup unless name
+
+      @properties.select { |property| property.name == name.downcase }
+    end
+
+    def property(name) = properties(name).first
+
+    def components(name = nil)
+      return @components.dup unless name
+
+      @components.select { |component| component.name == name.downcase }
+    end
+
+    def to_a
+      result = [@name, @properties.map(&:to_a)]
+      result << @components.map(&:to_a) unless @name == "vcard"
+      result
+    end
+
+    def to_json(*)
+      validate!
+      JSON.generate(to_a, *)
+    end
+
+    def validate!
+      valid_name = @name.is_a?(String) && /\A[a-z0-9-]+\z/.match?(@name)
+      valid_name &&= @name == "vcard" if is_a?(JCard::Card)
+      valid_name &&= @name == "vcalendar" if is_a?(JCal::Calendar)
+      raise ValidationError.new("invalid component name", pointer: "/0") unless valid_name
+      unless @properties.is_a?(Array) && @properties.all?(Property) && @components.is_a?(Array) && @components.all?(Component)
+        raise ValidationError, "invalid component children"
+      end
+      raise ValidationError, "vCard cannot contain components" if is_a?(JCard::Card) && !@components.empty?
+
+      @properties.each(&:validate!)
+      @components.each(&:validate!)
+      return self unless @name == "vcard"
+
+      versions = properties("version")
+      unless versions.size == 1 && versions.first.type == "text" && versions.first.values == ["4.0"]
+        raise ValidationError.new("vCard requires exactly one VERSION:4.0 property", pointer: "/1")
+      end
+      raise ValidationError.new("VERSION must be the first vCard property", pointer: "/1/0") unless @properties.first == versions.first
+
+      self
+    end
+
+    private
+
+    def to_text(format)
+      validate!
+      Converter.write(self, format: format, registry: @registry, max_binary_size: @max_binary_size)
+    end
+  end
+end

data/lib/jcard_jcal/content_line/param_codec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module JCardJCal
+  module ContentLine
+    # RFC 6868 escaping and content-line parameter quoting.
+    module ParamCodec
+      module_function
+
+      def decode(value)
+        value = validate(value)
+        if value.start_with?('"') && value.end_with?('"') && value.length >= 2
+          value = value[1...-1]
+          invalid = value.include?('"')
+        else
+          invalid = value.match?(/[":;,]/)
+        end
+        raise ValueError, "Invalid parameter quoting" if invalid || value.match?(/[\r\n]/)
+
+        value.gsub(/\^[n'^]/) do |escape|
+          { "^n" => "\n", "^'" => '"', "^^" => "^" }.fetch(escape)
+        end
+      end
+
+      def encode(value)
+        value = validate(value)
+        encoded = value.gsub(/\r\n|[\r\n"^]/) do |character|
+          case character
+          when '"' then "^'"
+          when "^" then "^^"
+          else "^n"
+          end
+        end
+        encoded.empty? || encoded.match?(/[:;,]/) ? "\"#{encoded}\"" : encoded
+      end
+
+      def validate(value)
+        value = value.dup.force_encoding(Encoding::UTF_8) if value.is_a?(String)
+        unless value.is_a?(String) && value.valid_encoding? &&
+               !value.match?(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/)
+          raise ValueError, "Parameter value must be a string without control characters"
+        end
+
+        value
+      end
+      private_class_method :validate
+    end
+  end
+end

data/lib/jcard_jcal/content_line/reader.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "strscan"
+require_relative "param_codec"
+
+module JCardJCal
+  module ContentLine
+    Line = Struct.new(:name, :group, :params, :value, :line_number, keyword_init: true)
+
+    # Enumerates unfolded lines, reporting the first physical line of each one.
+    class Reader
+      include Enumerable
+
+      def initialize(text, max_line_length: 1_048_576)
+        raise ArgumentError, "text must be a string" unless text.is_a?(String)
+        raise ArgumentError, "max_line_length must be a positive integer" unless max_line_length.is_a?(Integer) && max_line_length.positive?
+
+        @text = text
+        @max_line_length = max_line_length
+      end
+
+      def each
+        return enum_for(__method__) unless block_given?
+
+        unfolded = nil
+        first_line = nil
+        # Unfold bytes before checking UTF-8; peers may split a multibyte character.
+        @text.b.each_line.with_index(1) do |physical, number|
+          physical.delete_suffix!("\r") if physical.delete_suffix!("\n")
+          check_length(physical.bytesize, number)
+          if physical.start_with?(" ", "\t")
+            fail_line("Continuation without a preceding line", number) unless unfolded
+            check_length(unfolded.bytesize + physical.bytesize - 1, first_line)
+            unfolded << physical.byteslice(1..)
+          else
+            yield parse(unfolded, first_line) if unfolded
+            unfolded = physical
+            first_line = number
+          end
+        end
+        yield parse(unfolded, first_line) if unfolded
+        self
+      end
+
+      private
+
+      def parse(text, number)
+        text.force_encoding(Encoding::UTF_8)
+        fail_line("Invalid UTF-8 or control character", number) unless text.valid_encoding? && !text.match?(/[\x00-\x08\x0a-\x1f\x7f]/)
+
+        scanner = StringScanner.new(text)
+        name = scanner.scan(/[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)?/)
+        fail_line("Invalid property name", number) unless name
+        group, name = name.split(".", 2) if name.include?(".")
+        params = {}
+        while scanner.scan(";")
+          key = scanner.scan(/[A-Za-z0-9-]+/)&.downcase
+          fail_line("Invalid parameter name or missing equals sign", number) unless key && scanner.scan("=")
+          fail_line("Duplicate parameter #{key}", number) if params.key?(key)
+
+          values = []
+          loop do
+            raw = scanner.peek(1) == '"' ? scanner.scan(/"[^"]*"/) : scanner.scan(/[^":;,]*/)
+            fail_line("Invalid parameter quoting", number) unless raw
+            values << ParamCodec.decode(raw)
+            break unless scanner.scan(",")
+          end
+          params[key] = values.length == 1 ? values.first : values
+        end
+        fail_line("Missing colon or malformed parameter", number) unless scanner.scan(":")
+
+        Line.new(name: name.downcase, group: group, params: params, value: scanner.rest, line_number: number)
+      rescue ValueError => e
+        fail_line(e.message, number)
+      end
+
+      def check_length(length, number)
+        fail_line("Content line exceeds maximum length of #{@max_line_length} bytes", number) if length > @max_line_length
+      end
+
+      def fail_line(message, number)
+        raise ParseError.new(message, line_number: number)
+      end
+    end
+  end
+end

data/lib/jcard_jcal/content_line/text_codec.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module JCardJCal
+  module ContentLine
+    # Escaping for TEXT property values (RFC 5545 section 3.3.11).
+    module TextCodec
+      module_function
+
+      def decode(value)
+        value = validate(value)
+        value.gsub(/\\([\\,;nN])|\\(.)|\\\z/m) do
+          escaped = Regexp.last_match(1)
+          raise ValueError, "Invalid TEXT escape" unless escaped
+
+          %w[n N].include?(escaped) ? "\n" : escaped
+        end
+      end
+
+      def encode(value)
+        value = validate(value)
+        value.gsub(/\r\n|[\r\n\\,;]/) do |character|
+          ["\r\n", "\r", "\n"].include?(character) ? '\n' : "\\#{character}"
+        end
+      end
+
+      # Split before decoding so escaped list and field separators remain data.
+      def split(value, delimiter)
+        value = validate(value)
+        raise ArgumentError, "delimiter must be one character" unless delimiter.is_a?(String) && delimiter.length == 1
+
+        parts = [String.new]
+        escaped = false
+        value.each_char do |character|
+          if character == delimiter && !escaped
+            parts << String.new
+          else
+            parts.last << character
+          end
+          escaped = character == "\\" && !escaped
+        end
+        parts
+      end
+
+      def validate(value)
+        value = value.dup.force_encoding(Encoding::UTF_8) if value.is_a?(String)
+        unless value.is_a?(String) && value.valid_encoding? &&
+               !value.match?(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/)
+          raise ValueError, "TEXT value must be a string without control characters"
+        end
+
+        value
+      end
+      private_class_method :validate
+    end
+  end
+end

data/lib/jcard_jcal/content_line/writer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "param_codec"
+
+module JCardJCal
+  module ContentLine
+    # Serializes an already encoded property value, folding at UTF-8 boundaries.
+    module Writer
+      module_function
+
+      def line(name:, params:, value:, group: nil)
+        validate_name(name)
+        validate_name(group) unless group.nil?
+        value = value.dup.force_encoding(Encoding::UTF_8) if value.is_a?(String)
+        unless value.is_a?(String) && value.valid_encoding? &&
+               !value.match?(/[\x00-\x08\x0a-\x1f\x7f]/)
+          raise ValueError, "Property value must be a string without line breaks or control characters"
+        end
+        raise ValueError, "Parameters must be a hash" unless params.is_a?(Hash)
+
+        content = group ? "#{group}.#{name.upcase}" : name.upcase
+        seen = {}
+        params.each do |key, parameter|
+          validate_name(key)
+          raise ValueError, "Duplicate parameter #{key}" if seen[key.downcase]
+
+          seen[key.downcase] = true
+          values = parameter.is_a?(Array) ? parameter : [parameter]
+          raise ValueError, "Parameter lists cannot be empty" if values.empty?
+
+          content << ";#{key.upcase}=#{values.map { |item| ParamCodec.encode(item) }.join(",")}"
+        end
+        content << ":#{value}"
+        content.force_encoding(Encoding::UTF_8)
+        result = String.new
+        width = 0
+        content.each_char do |character|
+          if width + character.bytesize > 75
+            result << "\r\n "
+            width = 1
+          end
+          result << character
+          width += character.bytesize
+        end
+        result << "\r\n"
+      end
+
+      def validate_name(name)
+        unless name.is_a?(String) && name.valid_encoding? && name.encoding.ascii_compatible? &&
+               name.match?(/\A[A-Za-z0-9-]+\z/)
+          raise ValueError, "Invalid property, group, or parameter name"
+        end
+      end
+      private_class_method :validate_name
+    end
+  end
+end