soml-lang 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 451e02a56833294ea93a0ebb269889d8c20c377329572e6a27090a2d2a6a621b
-  data.tar.gz: 2956309298dbd2934603257d28903ee913b30f4a34a45f11261a09f6b96487a8
+  metadata.gz: 808fb7da3c2ca5866146bef2193cbf96c4d4e91077c65ada841afd077b1e5282
+  data.tar.gz: 03113f26b03a51156a4c7b30ac2dbde6fda0e908df06f5b11c349c69ef2619d7
 SHA512:
-  metadata.gz: 43bba0ce5a930333bcd33bb064a989e8a9cbb9b71bf409358778087c646f1a324306a264d5d8c575c76511ec2a56ef844c1b64198c8e1237ae12adc7b77adcd4
-  data.tar.gz: 57e43736b8cace1e4f049e34186f1cb4a47dc125ca854956fc93dc66ee732a5c465def2935dd9c96e0693b35d229ae5d1e2ae5668e9ba9edc2669c596055e7af
+  metadata.gz: 9ede6de7ba3eeea51fa44fe111832a090018d5f5ab589232702b4c0d8cff010f04da9e1a91c52a8a726d77afe2e9b37c14b070631a70bdbece238cc73ece047b
+  data.tar.gz: 2ba19a6d60471afa8d03dc54c0277bf628ee7cd0ba57620a9c5ea0c353805f2843160fa7dc8c1356215cbe12fbfede87b401c2cda355cf90c1c851073d0bd2b4

data/lib/soml/duration.rb

@@ -31,12 +31,12 @@ module SOML
 		# @raise [TypeError] When `text` is not a string.
 		def self.parse(text) = Parser.new(text).parse_duration_literal
 
-		# Make a duration from a number of seconds, the inverse of {#to_r}. The seconds are rounded to the nearest nanosecond, because a `Float` such as `0.1` is not exact.
+		# Make a duration from a number of seconds, the inverse of {#to_r}. The seconds are rounded to the nearest nanosecond, with ties to even, because a `Float` such as `0.1` is not exact.
 		#
 		# @param seconds [Numeric] An `Integer`, a `Float`, a `Rational`, or another real number.
 		# @return [Duration]
 		# @raise [TypeError] When `seconds` is not a number.
-		# @raise [RangeError] When `seconds` is not finite, not real, or outside the 64-bit range of nanoseconds.
+		# @raise [RangeError] When `seconds` is not finite or not real, or the rounded nanosecond count is outside the 64-bit range.
 		#
 		# @example
 		#   SOML::Duration.from_seconds(90)
@@ -48,7 +48,7 @@ module SOML
 			# `Numeric ===` checks the class itself, so an `ActiveSupport::Duration`, which only claims to be a `Numeric`, must be converted with `to_r` first. Its months are an average length.
 			raise TypeError, "A duration is made from a number of seconds, got #{Parser.describe_argument(seconds)}" unless Numeric === seconds
 
-			new(nanoseconds: (seconds.to_r * 1_000_000_000).round)
+			new(nanoseconds: (seconds.to_r * 1_000_000_000).round(half: :even))
 		end
 
 		# @param nanoseconds [Integer] The length in nanoseconds.

data/lib/soml/format.rb

@@ -321,6 +321,8 @@ module SOML
 		# Only spaces and tabs are whitespace in SOML. Any other character, such as a no-break space, is content.
 		def trim_trailing_whitespace(text)
 			# A loop rather than a regex, which would keep a backtracking entry for every space of a long run.
+			#
+			# Note: Not using `rstrip(" \t")` because it is slower for typical short lines.
 			finish = text.bytesize
 			finish -= 1 while finish.positive? && ((byte = text.getbyte(finish - 1)) == 0x20 || byte == 0x09)
 			text.byteslice(0, finish)
@@ -330,6 +332,7 @@ module SOML
 		def reindent_block_string(text, indentation)
 			lines = text.split("\n", -1)
 			closing = lines.last
+			# Note: Not using `lstrip(" \t")` because it allocates a string and is slower than this scan.
 			old_length = 0
 			old_length += 1 while (byte = closing.getbyte(old_length)) == 0x20 || byte == 0x09
 

data/lib/soml/generator.rb

@@ -6,6 +6,8 @@ module SOML
 	# @api private
 	class Generator
 		# A byte that cannot be in a `'...'` string: a control character, an apostrophe, or DEL. A string with one is written as `"..."`. The set is a byte table, because a scan of it is faster than the regex it replaces.
+		#
+		# Note: Not using `String#count` because it is slower for typical short strings.
 		NEEDS_ESCAPED_BYTE = Array.new(256) { |byte| byte < 0x20 || byte == 0x27 || byte == 0x7F }.freeze
 
 		ESCAPED_CHARACTER = /[\x00-\x1F"\\\x7F]/
@@ -30,6 +32,8 @@ module SOML
 
 		# The fraction of a second of an instant or a duration as a document writes it: a point and nine digits with the trailing zeros removed, or nothing when there is none.
 		#
+		# Note: Not using `sprintf` because its padding is slower than `to_s.rjust`.
+		#
 		# @param nanoseconds [Integer] The fraction, below one second.
 		# @return [String]
 		def self.format_fraction(nanoseconds) = nanoseconds.zero? ? '' : ".#{nanoseconds.to_s.rjust(9, '0').rstrip('0')}"
@@ -123,6 +127,11 @@ module SOML
 				write_string(value.name)
 			when Time
 				@buffer << format_instant(value)
+			# `DateTime` is a subclass of `Date`, so it must come first.
+			when DateTime
+				raise GenerateError, 'Cannot generate a DateTime. Convert it to a Time with to_time'
+			when Date
+				@buffer << format_date(value)
 			when Duration
 				@buffer << value.to_s
 			else
@@ -157,6 +166,7 @@ module SOML
 			@buffer << '[' << @line_break
 			index = 0
 
+			# Note: Not using `each_index` because its block overhead slows this hot loop under YJIT.
 			while index < array.length
 				@buffer << item_prefix(index, inner_indent)
 
@@ -210,6 +220,7 @@ module SOML
 
 		# Yields each member with its key as a UTF-8 string, in the order of the hash, or sorted by key for canonical form.
 		def each_member(hash)
+			# Note: Not using a `hash.each_key` enumerator because it is slower than iterating the key array.
 			keys = hash.keys
 			sort_keys!(keys) if @canonical
 			names = {}
@@ -259,6 +270,7 @@ module SOML
 			end
 
 			if index == length
+				# Note: Not using `append_as_bytes` because it is slower for typical short strings in the full generator.
 				@buffer << "'" << string << "'"
 				return
 			end
@@ -322,6 +334,16 @@ module SOML
 			value.negative? ? "-#{body}" : body
 		end
 
+		# Use the native components, even for a subclass that overrides them, and without converting through an instant or another calendar.
+		def format_date(date)
+			text = Date.instance_method(:iso8601).bind_call(date)
+			year = Date.instance_method(:year).bind_call(date)
+			raise GenerateError, "Cannot generate the date #{text}, because it is outside the years 0001 to 9999" unless year.between?(1, 9999)
+			raise GenerateError, "Cannot generate the Julian date #{text}. Convert it to a Gregorian Date with new_start(Date::GREGORIAN), which must be in the years 0001 to 9999" unless Date.instance_method(:gregorian?).bind_call(date)
+
+			text
+		end
+
 		def format_instant(time)
 			# `getutc` makes a copy, which a time in UTC, as `SOML.parse` returns it, does not need.
 			utc = time.utc? ? time : time.getutc
@@ -332,6 +354,8 @@ module SOML
 			raise GenerateError, "Cannot generate the instant #{Time.instance_method(:inspect).bind_call(time)}, because in UTC it falls outside the years 0001 to 9999" unless utc.year.between?(1, 9999)
 
 			# The year is 0001 to 9999, so `xmlschema` writes four digits, and a time in UTC ends with `Z`.
+			#
+			# Note: Not using `strftime` because Ruby 4's core `xmlschema` is faster.
 			text = utc.xmlschema
 			nanoseconds.zero? ? text : "#{text.chop}#{Generator.format_fraction(nanoseconds)}Z"
 		end
@@ -351,11 +375,7 @@ module SOML
 		end
 
 		def describe_unsupported(value)
-			if defined?(::DateTime) && ::DateTime === value
-				'Cannot generate a DateTime. Convert it to a Time with to_time'
-			elsif defined?(::Date) && ::Date === value
-				"Cannot generate a Date, because a date is not an instant. Write it as a String, such as '#{value}'"
-			elsif defined?(::ActiveSupport::Duration) && ::ActiveSupport::Duration === value
+			if defined?(::ActiveSupport::Duration) && ::ActiveSupport::Duration === value
 				# Rails code writes `5.minutes`. Its days, months, and years follow the calendar, so it is not converted.
 				"Cannot generate an ActiveSupport::Duration, because its days, months, and years are not a fixed length. Use a SOML::Duration, such as SOML::Duration.parse('5m')"
 			elsif Numeric === value
@@ -367,7 +387,7 @@ module SOML
 			elsif Pathname === value
 				"Cannot generate #{describe(value)}. Convert it to a String with to_s"
 			else
-				"Cannot generate #{describe(value)}. Only Hash, Array, String, Symbol, Integer, Float, true, false, nil, Time, and SOML::Duration can be generated"
+				"Cannot generate #{describe(value)}. Only Hash, Array, String, Symbol, Integer, Float, true, false, nil, Date, Time, and SOML::Duration can be generated"
 			end
 		end
 	end

data/lib/soml/parser.rb

@@ -43,7 +43,7 @@ module SOML
 
 		DURATION_UNIT_NAMES = DURATION_UNITS.keys.freeze
 
-		INSTANT_PREFIX = /\A[0-9]{4}-[0-9]{2}-[0-9]{2}/
+		DATE_PREFIX = /\A[0-9]{4}-[0-9]{2}-[0-9]{2}/
 		INSTANT = /\A[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?(?:Z|[+-][0-9]{2}:[0-9]{2})\z/
 		LOCAL_DATE_TIME = /\A[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\.[0-9]+)?\z/
 		INSTANT_FORMAT = 'An instant is written as 2026-09-19T14:00:00Z, with an optional fraction of up to nine digits and an offset of Z or ±HH:MM'
@@ -175,6 +175,8 @@ module SOML
 		end
 
 		# The length of `text` in UTF-16 code units, as JS counts it. A character outside the BMP is two code units, and its UTF-8 lead byte is 0xF0 to 0xF4. `String#count` with that range of characters instead would build a table of a million entries.
+		#
+		# Note: Not using UTF-16 encoding because it copies the text and is slower for short messages.
 		def self.utf16_length(text) = text.length + text.b.count("\xF0-\xF4".b)
 
 		# The string as `JSON.stringify` writes it, as the JS reference shows a quoted key, so that a control character, such as a line feed, shows as its escape.
@@ -727,9 +729,9 @@ module SOML
 			when 0x69 # i
 				keyword?('infinity') ? Float::INFINITY : fail_unexpected_value
 			when 0x2D # -
-				@source.getbyte(@index + 1) == 0x69 && keyword?('-infinity') ? -Float::INFINITY : (number = parse_number_or_instant)
+				@source.getbyte(@index + 1) == 0x69 && keyword?('-infinity') ? -Float::INFINITY : (number = parse_number_or_temporal)
 			when 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39
-				number = parse_number_or_instant
+				number = parse_number_or_temporal
 			else
 				fail_unexpected_value
 			end
@@ -1077,7 +1079,7 @@ module SOML
 			value << text.byteslice(chunk_start, text.bytesize - chunk_start)
 		end
 
-		def parse_number_or_instant
+		def parse_number_or_temporal
 			plain = parse_plain_number
 			return plain unless plain.nil?
 
@@ -1086,7 +1088,12 @@ module SOML
 			text = @source.byteslice(start, finish - start)
 			@index = finish
 
-			return parse_instant(text, start) if text.match?(INSTANT_PREFIX)
+			if text.match?(DATE_PREFIX)
+				# A time after spaces or tabs still gets the instant separator diagnostic.
+				return parse_date(text, start) if text.bytesize == 10 && !space_separated_time?
+
+				return parse_instant(text, start)
+			end
 
 			kind = classify_number(text)
 			return parse_duration(text, start) if kind.nil? && duration_like?(text)
@@ -1316,6 +1323,9 @@ module SOML
 		end
 
 		# The float nearest to `significand × 10^exponent`, rounding a tie to even, as IEEE 754 does. It uses exact integer arithmetic rather than `String#to_f`, which warns when a value overflows or underflows.
+		#
+		# Note: Not using `Float()` because it warns at the limits.
+		# Note: Not using `Rational#to_f` because it can round twice (Ruby bug #22246).
 		def decimal_to_float(significand, exponent)
 			numerator = exponent.negative? ? significand : significand * (10**exponent)
 			denominator = exponent.negative? ? 10**-exponent : 1
@@ -1338,11 +1348,28 @@ module SOML
 			Math.ldexp(quotient, shift)
 		end
 
+		# Whether a time follows after spaces or tabs, as in `2026-11-01 12:00`, which an instant's error describes better than a date followed by another entry.
+		def space_separated_time?
+			time_start = skip_spaces(@index)
+			time_start > @index && @source.byteslice(time_start, 5).b.match?(/\A[0-9]{1,2}:[0-9]{2}/)
+		end
+
+		# A calendar date alone, validated as a whole ten-byte token without a time or timezone conversion.
+		def parse_date(text, start)
+			year = digits_value(text, 0, 4)
+			month = digits_value(text, 5, 2)
+			day = digits_value(text, 8, 2)
+			reason = calendar_error(year, month, day)
+			fail_at("Invalid date #{text}: #{reason}", start) if reason
+
+			Date.new(year, month, day, Date::GREGORIAN)
+		end
+
 		def parse_instant(text, start)
 			unless text.bytesize <= MAX_DIAGNOSED_LENGTH && text.match?(INSTANT)
-				# A date, a space, and a time, as TOML and Python write a date and time.
-				time_start = @index + 1
-				finish = @source.getbyte(@index) == 0x20 && digit?(@source.getbyte(time_start)) ? number_end(time_start) : @index
+				# A date, spaces or tabs, and a time, as TOML and Python write a date and time.
+				time_start = skip_spaces(@index)
+				finish = time_start > @index && digit?(@source.getbyte(time_start)) ? number_end(time_start) : @index
 				time = finish > time_start ? @source.byteslice(time_start, finish - time_start) : ''
 				# More of the instant may follow, as in `14:00:00,5Z` or `14:00:00[Europe/Oslo]`, so it may have an offset.
 				is_whole_value = value_end?(finish) && !(@source.getbyte(finish) == 0x2C && digit?(@source.getbyte(finish + 1)))
@@ -1363,10 +1390,8 @@ module SOML
 			fraction_length = offset_start == 19 ? 0 : offset_start - 20
 
 			fail_instant(text, start, 'a fractional second has at most nine digits') if fraction_length > 9
-			fail_instant(text, start, 'the year must be 0001 to 9999') if year.zero?
-			fail_instant(text, start, 'the month must be 01 to 12') unless month.between?(1, 12)
-			last_day = days_in_month(year, month)
-			fail_instant(text, start, "the day must be 01 to #{last_day} in that month") unless day.between?(1, last_day)
+			reason = calendar_error(year, month, day)
+			fail_instant(text, start, reason) if reason
 			fail_instant(text, start, 'the hour must be 00 to 23') if hour > 23
 			fail_instant(text, start, 'the minute must be 00 to 59') if minute > 59
 			fail_instant(text, start, 'the second must be 00 to 59, and a leap second is not representable') if second > 59
@@ -1390,6 +1415,8 @@ module SOML
 		end
 
 		# The value of the `count` decimal digits at `offset` in `text`, which the caller checked are digits.
+		#
+		# Note: Not using a slice and `to_i` because they are slower for these small fields.
 		def digits_value(text, offset, count)
 			value = 0
 			finish = offset + count
@@ -1464,6 +1491,7 @@ module SOML
 			unless fraction.empty?
 				scale = 10**fraction.bytesize
 				fraction_nanoseconds = fraction.to_i * size
+				# Note: Not using `divmod` because it allocates an array and is slower for ordinary short fractions.
 				fail_duration(text, start, 'it is not a whole number of nanoseconds') unless (fraction_nanoseconds % scale).zero?
 				total += fraction_nanoseconds / scale
 			end
@@ -1507,7 +1535,7 @@ module SOML
 			skip_spaces(start) == offset ? offset - start : nil
 		end
 
-		# The end of the number, instant, or duration that starts at `start`: the end of the run of the bytes that one can hold.
+		# The end of the number, date, instant, or duration that starts at `start`: the end of the run of the bytes that one can hold.
 		def number_end(start)
 			finish = start
 
@@ -1565,10 +1593,21 @@ module SOML
 
 		def digit_or_underscore?(byte) = byte == 0x5F || digit?(byte)
 
-		def words_with_spaces?(text) = text.each_byte.all? { space?(it) || BARE_KEY_BYTE[it] }
+		# Note: Not using `String#count` because it scans the whole input even when its first character is invalid.
+		def words_with_spaces?(text) = !text.match?(/[^A-Za-z0-9_ \t-]/)
+
+		# Shared Gregorian validation for dates and the calendar portion of instants.
+		def calendar_error(year, month, day)
+			return 'the year must be 0001 to 9999' if year.zero?
+			return 'the month must be 01 to 12' unless month.between?(1, 12)
+
+			last_day = days_in_month(year, month)
+			"the day must be 01 to #{last_day} in that month" unless day.between?(1, last_day)
+		end
 
 		def days_in_month(year, month)
 			if month == 2
+				# Note: Not using `Date.gregorian_leap?` because it is slower.
 				is_leap_year = (year % 4).zero? && (!(year % 100).zero? || (year % 400).zero?)
 				return is_leap_year ? 29 : 28
 			end
@@ -1577,6 +1616,8 @@ module SOML
 		end
 
 		# Days since 1970-01-01 in the proleptic Gregorian calendar, from Howard Hinnant's `days_from_civil`.
+		#
+		# Note: Not using `Time.utc` because constructing it here is slower.
 		def days_from_civil(year, month, day)
 			year -= 1 if month <= 2
 			era = year.div(400)
@@ -1758,13 +1799,6 @@ module SOML
 			text.match?(/[A-Za-z]/) ? "Invalid number “#{abbreviate(text)}”. A string value must be quoted#{quoting_example(unquoted_text)}" : "Invalid number “#{abbreviate(text)}”"
 		end
 
-		# A date alone, which is not an instant. The instant it could be is only shown when the date exists, so that the example is valid.
-		def describe_date(date)
-			year, month, day = date.split('-').map(&:to_i)
-			is_existing = year >= 1 && month.between?(1, 12) && day.between?(1, days_in_month(year, month))
-			"#{date} is a date, not an instant. Write a date as a string, as in '#{date}'#{is_existing ? ". An instant needs a time and an offset, as in #{date}T00:00:00Z" : ''}"
-		end
-
 		# An offset on its own after spaces, as in `2026-09-19T14:00:00 Z`, which belongs directly after the time, or `nil`.
 		def offset_after_space
 			offset_start = skip_spaces(@index)
@@ -1782,7 +1816,7 @@ module SOML
 			if text.bytesize > MAX_DIAGNOSED_LENGTH
 				generic
 			elsif text.match?(/\A[0-9]{4}-[0-9]{2}-[0-9]{2}\z/)
-				time.match?(/\A[0-9]{2}:[0-9]{2}/) ? describe_space_separated_instant(text, time, is_whole_value) : describe_date(text)
+				describe_space_separated_instant(text, time, is_whole_value)
 			elsif text.match?(/\A[0-9]{4}-[0-9]{2}-[0-9]{2}t/)
 				'The date and time separator in an instant is an uppercase “T”'
 			elsif text.end_with?('z')

data/lib/soml/tree.rb

@@ -10,7 +10,7 @@ module SOML
 		# A `# ...` comment (`:line`) or a `/* ... */` comment (`:block`). `value` is its text without the delimiters.
 		Comment = Struct.new(:type, :start, :finish, :value)
 
-		# A lexical token with its original source text in `value`. `type` is `:punctuator`, `:bare_key`, `:string`, `:integer`, `:float`, `:keyword`, `:instant`, or `:duration`. Quoted keys are strings; booleans and null are keywords. Comments and whitespace are excluded.
+		# A lexical token with its original source text in `value`. `type` is `:punctuator`, `:bare_key`, `:string`, `:integer`, `:float`, `:keyword`, `:date`, `:instant`, or `:duration`. Quoted keys are strings; booleans and null are keywords. Comments and whitespace are excluded.
 		Token = Struct.new(:type, :start, :finish, :value)
 
 		# An object, written with braces or, only at the top level, without them.
@@ -32,7 +32,7 @@ module SOML
 			def type = :key
 		end
 
-		# A value that is not a collection. `kind` is `:string`, `:integer`, `:float`, `:boolean`, `:null`, `:instant`, or `:duration`, and `value` is decoded as by SOML.parse. `block` is whether it is a block string. Strings have `style: :literal` or `:escaped`; integers have `radix: 2`, `8`, `10`, or `16`. In other kinds, `style` and `radix` are nil and `block` is false.
+		# A value that is not a collection. `kind` is `:string`, `:integer`, `:float`, `:boolean`, `:null`, `:date`, `:instant`, or `:duration`, and `value` is decoded as by SOML.parse. `block` is whether it is a block string. Strings have `style: :literal` or `:escaped`; integers have `radix: 2`, `8`, `10`, or `16`. In other kinds, `style` and `radix` are nil and `block` is false.
 		ScalarNode = Struct.new(:block, :start, :finish, :kind, :value, :style, :radix) do
 			def type = :scalar
 		end
@@ -166,6 +166,7 @@ module SOML
 		# The number of characters that start in the `length` bytes from `start`: the bytes that are not UTF-8 continuation bytes. The bytes may begin or end inside a character.
 		def character_count(start, length)
 			bytes = @source.byteslice(start, length).b
+			# Note: Not using a complement count because it offers no measured speedup.
 			bytes.bytesize - bytes.count("\x80-\xBF".b)
 		end
 
@@ -357,6 +358,8 @@ module SOML
 				:boolean
 			when nil
 				:null
+			when Date
+				:date
 			when Time
 				:instant
 			when Duration

data/lib/soml/version.rb

@@ -2,5 +2,5 @@
 
 module SOML
 	# The version of this gem.
-	VERSION = '0.0.2'
+	VERSION = '0.0.3'
 end

data/lib/soml.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'date'
+
 require_relative 'soml/version'
 
 # Read and write SOML, a config format for humans.
@@ -25,7 +27,7 @@ module SOML
 	# A byte that a bare key can hold, as a table of 256 booleans, for the {Parser} and the {Tree}.
 	BARE_KEY_BYTE = Array.new(256) { it.chr.match?(/[A-Za-z0-9_-]/) }.freeze
 
-	# A number, an instant, or a duration is one maximal run of these bytes, which the {Parser} then validates as a whole. A keyword ends at the first byte that is not one, too, because the parser checked that it is followed by whitespace, a separator, a closing bracket, a comment, or the end.
+	# A number, a date, an instant, or a duration is one maximal run of these bytes, which the {Parser} then validates as a whole. A keyword ends at the first byte that is not one, too, because the parser checked that it is followed by whitespace, a separator, a closing bracket, a comment, or the end.
 	NUMBER_BYTE = Array.new(256) { it.chr.match?(/[A-Za-z0-9_.:+-]/) }.freeze
 
 	# A line of a block string without one of these is blank. A search for one character, because a repeat over a long line needs memory for every character.
@@ -59,6 +61,8 @@ module SOML
 		key = key.encode(Encoding::UTF_8) unless key.encoding.ascii_compatible?
 
 		# A scan of the bytes, which is faster than the regex it replaces and decides the same: a byte that is not an ASCII letter, digit, `_`, or `-` means the key needs quotes. A non-ASCII character is a run of bytes none of which a bare key can hold.
+		#
+		# Note: Not using `String#count` because it is slower for typical short keys.
 		return false if key.empty?
 
 		index = 0

data/readme.md

@@ -8,7 +8,7 @@
 ## Highlights
 
 - Strict: enforces every rule in the specification, with the same error messages as the JavaScript reference implementation
-- Exact: an int is an `Integer`, a float is a `Float`, an instant is a `Time` exact to the nanosecond, and a duration is an exact count of nanoseconds
+- Exact: an int is an `Integer`, a float is a `Float`, a date is a Gregorian `Date`, an instant is a `Time` exact to the nanosecond, and a duration is an exact count of nanoseconds
 - Canonical: `SOML.generate(value, canonical: true)` writes the one canonical form, so equal values give equal text
 - Familiar: the API of `json`, with `parse`, `load_file`, `generate`, `symbolize_names:`, and `freeze:`
 - Lossless: `SOML.format` and `SOML.edit` keep comments, member order, and spelling
@@ -40,6 +40,7 @@ config = SOML.parse(<<~SOML)
 	replicas: 3
 	timeout: 30.0
 	grace: 1m30s
+	launch-date: 2027-09-19
 	deployed-at: 2026-09-19T14:00:00Z
 	postgres: {host: 'db.internal'}
 SOML
@@ -48,6 +49,7 @@ SOML
 # 	"replicas" => 3,
 # 	"timeout" => 30.0,
 # 	"grace" => #<SOML::Duration 1m30s>,
+# 	"launch-date" => Date.new(2027, 9, 19, Date::GREGORIAN),
 # 	"deployed-at" => 2026-09-19 14:00:00 UTC,
 # 	"postgres" => {"host" => "db.internal"}
 # }
@@ -57,6 +59,7 @@ puts SOML.generate(config)
 # replicas: 3
 # timeout: 30.0
 # grace: 1m30s
+# launch-date: 2027-09-19
 # deployed-at: 2026-09-19T14:00:00Z
 # postgres: {
 # 	host: 'db.internal'
@@ -86,6 +89,7 @@ File.binwrite('config.soml', SOML.generate(config))
 | float | `Float` | |
 | bool | `true`, `false` | |
 | null | `nil` | |
+| date | `Date`, in the proleptic Gregorian calendar | a Gregorian `Date` in years 0001 to 9999 |
 | instant | `Time`, in UTC | a `Time` with any offset |
 | duration | [`SOML::Duration`](#somlduration) | |
 | array | `Array` | |
@@ -109,6 +113,8 @@ Two things always hold:
 - `SOML.parse(SOML.generate(value))` equals `value`, for a value made of the types `parse` returns. (A `Time` comes back in UTC, a `Symbol` as a `String`, and `-0.0` as `0.0`.)
 - `SOML.generate(SOML.parse(text), canonical: true)` is the canonical form of `text`.
 
+A date is a `Date` with Gregorian year, month, and day, without a time or timezone. For a date before 1582-10-15, construct it with `Date.new(year, month, day, Date::GREGORIAN)`, as in `Date.new(1582, 10, 10, Date::GREGORIAN)`. Ruby's default calendar uses the Julian calendar before 1582-10-05, skips 1582-10-05 through 1582-10-14, and uses the Gregorian calendar from 1582-10-15. Julian dates and `DateTime` values are rejected when writing.
+
 An instant is a `Time` in UTC, because the offset is not part of its value:
 
 ```ruby
@@ -181,10 +187,11 @@ Raises `SOML::GenerateError` for a value that cannot be written:
 - `Float::NAN` (use `nil` for a missing value)
 - an `Integer` outside the 64-bit range
 - a `Time` outside the years 0001 to 9999 in UTC, or finer than a nanosecond
+- a `Date` outside the years 0001 to 9999, or a Julian (non-Gregorian) `Date`
 - a string or key with a carriage return, or that is not valid UTF-8 and does not convert to it
 - a key that is not a `String` or a `Symbol`, and two keys that are the same string, such as `:a` and `'a'`
 - a circular reference, and nesting deeper than 100 levels
-- an object of any other class, such as a `Date` (write it as a string), a `Rational`, or an `ActiveSupport::Duration` (use a `SOML::Duration`). A `Struct`, `Data`, `Set`, or `Pathname` is not converted, because it would read back as another class. The message names the conversion to use, such as `to_h`.
+- an object of any other class, such as a `DateTime` (convert it with `to_time`), a `Rational`, or an `ActiveSupport::Duration` (use a `SOML::Duration`). A `Struct`, `Data`, `Set`, or `Pathname` is not converted, because it would read back as another class. The message names the conversion to use, such as `to_h`.
 
 The message says where the value is:
 
@@ -345,7 +352,7 @@ SOML::Duration.parse('1.5h')
 
 #### SOML::Duration.from_seconds(seconds)
 
-Make a duration from a number of seconds, the inverse of `#to_r`. The seconds are rounded to the nearest nanosecond, because a `Float` such as `0.1` is not exact. Raises `TypeError` when `seconds` is not a number, and `RangeError` when it is not finite or is outside the 64-bit range.
+Make a duration from a number of seconds, the inverse of `#to_r`. The seconds are rounded to the nearest nanosecond, with ties to even, because a `Float` such as `0.1` is not exact. Raises `TypeError` when `seconds` is not a number, and `RangeError` when it is not finite or the rounded nanosecond count is outside the 64-bit range.
 
 ```ruby
 SOML::Duration.from_seconds(90)
@@ -511,16 +518,16 @@ SOML.generate({timeout: SOML::Duration.from_seconds(5.minutes.to_r)})
 
 ## Benchmark
 
-CPU time to read and write the shared [benchmark fixtures](https://github.com/soml-lang/soml/blob/main/benchmark/readme.md), which hold the same data in SOML, JSON, and TOML, on an Apple M-series machine with Ruby 4.0 and YJIT. The numbers are rough. Lower is better.
+CPU time to read and write the shared [benchmark fixtures](https://github.com/soml-lang/soml/blob/main/benchmark/readme.md), which hold the same data in SOML, JSON, and TOML, on an Apple M-series machine with Ruby 4.0.6 and YJIT. The numbers are rough. Lower is better.
 
 | | this gem | `toml-rb` | `json` | `oj` |
 |---|---|---|---|---|
-| Read `service` (3 KB) | 78 µs | 174 µs | 10 µs | 11 µs |
-| Read `platform` (35 KB) | 0.61 ms | 1.2 ms | 0.10 ms | 0.07 ms |
-| Read `earthquakes` (733 KB) | 14 ms | 51 ms | 2.2 ms | 2.8 ms |
-| Write `service` | 51 µs | 105 µs | 8 µs | 8 µs |
-| Write `platform` | 0.34 ms | 0.65 ms | 0.06 ms | 0.03 ms |
-| Write `earthquakes` | 15 ms | 26 ms | 2.1 ms | 3.2 ms |
+| Read `service` (3 KB) | 59 µs | 152 µs | 9 µs | 10 µs |
+| Read `platform` (35 KB) | 0.54 ms | 1.3 ms | 0.09 ms | 0.07 ms |
+| Read `earthquakes` (733 KB) | 11 ms | 43 ms | 2.0 ms | 2.5 ms |
+| Write `service` | 46 µs | 97 µs | 7 µs | 7 µs |
+| Write `platform` | 0.35 ms | 0.61 ms | 0.05 ms | 0.03 ms |
+| Write `earthquakes` | 12 ms | 27 ms | 1.9 ms | 2.7 ms |
 
 `toml-rb` is pure Ruby, like this gem, and `json` and `oj` are C extensions. The script also compares `tomlib`, `perfect_toml`, and `tomlrb`, and times `SOML.format`, `SOML.edit`, and `SOML.parse_tree` on each fixture:
 
@@ -559,11 +566,11 @@ Every node, token, and comment has `start` and exclusive `finish` UTF-8 byte off
 | `Comment` | `:line` or `:block` | `value` (text without delimiters) |
 | `Token` | See below | `value` (original source text) |
 
-Scalar kinds are `:string`, `:integer`, `:float`, `:boolean`, `:null`, `:instant`, and `:duration`, with the same Ruby values as `SOML.parse`. Strings have `style: :literal` or `:escaped` and a `block` boolean; integers have `radix: 2`, `8`, `10`, or `16`. Otherwise, `style` and `radix` are `nil`, and `block` is `false`.
+Scalar kinds are `:string`, `:integer`, `:float`, `:boolean`, `:null`, `:date`, `:instant`, and `:duration`, with the same Ruby values as `SOML.parse`. Strings have `style: :literal` or `:escaped` and a `block` boolean; integers have `radix: 2`, `8`, `10`, or `16`. Otherwise, `style` and `radix` are `nil`, and `block` is `false`.
 
 ### Syntax highlighting
 
-Token types are `:punctuator` (`{}[]:,`), `:bare_key`, `:string`, `:integer`, `:float`, `:keyword` (`true`, `false`, `null`), `:instant`, and `:duration`. Quoted keys and whole block strings are string tokens; escapes stay within strings. Infinities are floats. Use key nodes to distinguish quoted keys from string values.
+Token types are `:punctuator` (`{}[]:,`), `:bare_key`, `:string`, `:integer`, `:float`, `:keyword` (`true`, `false`, `null`), `:date`, `:instant`, and `:duration`. Quoted keys and whole block strings are string tokens; escapes stay within strings. Infinities are floats. Use key nodes to distinguish quoted keys from string values.
 
 ```ruby
 (tree.tokens + tree.comments).sort_by(&:start).each do |token|

data/sig/manifest.yaml

@@ -0,0 +1,2 @@
+dependencies:
+  - name: date

data/sig/soml.rbs

@@ -3,7 +3,7 @@ module SOML
 	VERSION: String
 
 	# A value in a document, as `parse` returns it.
-	type value = String | Integer | Float | bool | nil | Time | Duration | Array[value] | Hash[String | Symbol, value]
+	type value = String | Integer | Float | bool | nil | Date | Time | Duration | Array[value] | Hash[String | Symbol, value]
 
 	# A whole document, which is always an object or an array.
 	type document = Hash[String | Symbol, value] | Array[value]
@@ -88,7 +88,7 @@ module SOML
 		# Read a duration written as in a document, such as `1h30m`.
 		def self.parse: (string text) -> Duration
 
-		# Make a duration from a number of seconds, rounded to the nearest nanosecond.
+		# Make a duration from a number of seconds, rounded to the nearest nanosecond, with ties to even.
 		def self.from_seconds: (Numeric seconds) -> Duration
 
 		def self.new: (nanoseconds: Integer) -> Duration
@@ -162,7 +162,7 @@ module SOML
 
 		# A lexical token, with its source text.
 		class Token < Struct[untyped]
-			attr_reader type: :punctuator | :bare_key | :string | :integer | :float | :keyword | :instant | :duration
+			attr_reader type: :punctuator | :bare_key | :string | :integer | :float | :keyword | :date | :instant | :duration
 			attr_reader start: Integer
 			attr_reader finish: Integer
 			attr_reader value: String
@@ -207,8 +207,8 @@ module SOML
 			attr_reader block: bool
 			attr_reader start: Integer
 			attr_reader finish: Integer
-			attr_reader kind: :string | :integer | :float | :boolean | :null | :instant | :duration
-			attr_reader value: String | Integer | Float | bool | nil | Time | Duration
+			attr_reader kind: :string | :integer | :float | :boolean | :null | :date | :instant | :duration
+			attr_reader value: String | Integer | Float | bool | nil | Date | Time | Duration
 			attr_reader style: (:literal | :escaped)?
 			attr_reader radix: (2 | 8 | 10 | 16)?
 			def type: () -> :scalar

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: soml-lang
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Sindre Sorhus
@@ -10,9 +10,9 @@ cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: A strict parser and a generator for SOML that keeps member order or writes
-  canonical form, with exact integers, instants, and durations, and an error message
-  that says what is wrong and where. With a formatter, an editor that keeps comments
-  and layout, and a syntax tree for linters.
+  canonical form, with exact integers, dates, instants, and durations, and an error
+  message that says what is wrong and where. With a formatter, an editor that keeps
+  comments and layout, and a syntax tree for linters.
 email:
 - sindresorhus@gmail.com
 executables: []
@@ -31,6 +31,7 @@ files:
 - lib/soml/version.rb
 - license
 - readme.md
+- sig/manifest.yaml
 - sig/soml.rbs
 homepage: https://github.com/soml-lang/soml-ruby
 licenses: