soml-lang 0.0.1

data/lib/soml/tree.rb

@@ -0,0 +1,239 @@
+# frozen_string_literal: true
+
+module SOML
+	# The syntax tree of a valid document, for {SOML.format} and {SOML.edit}.
+	#
+	# It is a port of the JS reference's `tree.ts`, with only what the formatter and the editor read. Every offset is a byte offset into the UTF-8 source, and `finish` is the offset after the node. A node has no line and column, a scalar has no value, and there is no list of tokens. The document is checked by {Parser} first, so the builder can assume valid input, and the comments are collected in source order.
+	#
+	# @api private
+	class Tree
+		# The nodes are structs rather than `Data`, whose `new` builds a hash of keywords for every node, which made building a tree several times as slow as parsing the document. Nothing changes a node once it is made.
+
+		# A `# ...` comment (`:line`) or a `/* ... */` comment (`:block`).
+		Comment = Struct.new(:type, :start, :finish)
+
+		# An object, written with braces or, only at the top level, without them.
+		ObjectNode = Struct.new(:members, :braced, :start, :finish) do
+			def type = :object
+		end
+
+		ArrayNode = Struct.new(:elements, :start, :finish) do
+			def type = :array
+		end
+
+		# A `key: value` member.
+		MemberNode = Struct.new(:key, :value, :start, :finish) do
+			def type = :member
+		end
+
+		# A key, with its decoded `value`.
+		KeyNode = Struct.new(:value, :start, :finish)
+
+		# A value that is not a collection. `block` is whether it is a block string.
+		ScalarNode = Struct.new(:block, :start, :finish) do
+			def type = :scalar
+		end
+
+		# The characters that end the search for the closing quote of a `"..."` string.
+		ESCAPED_STRING_SPECIAL = /["\\]/
+
+		private_constant(*constants(false))
+
+		# @return [String] The source, in UTF-8.
+		attr_reader :source
+
+		# @return [ObjectNode, ArrayNode] The document's collection.
+		attr_reader :body
+
+		# @return [Array<Comment>] Every comment, in source order.
+		attr_reader :comments
+
+		# @param source [String] The document, decoded as {SOML.parse} decodes it.
+		# @raise [ParseError] When the document is not valid, the same as {SOML.parse}.
+		def initialize(source)
+			# Validates the whole document, so the builder below can assume valid input.
+			parser = Parser.new(source)
+			parser.parse
+			@source = parser.source
+			@length = @source.bytesize
+			@index = 0
+			@comments = []
+
+			skip_trivia
+
+			@body = case @source.getbyte(@index)
+			when 0x7B # {
+				parse_object
+			when 0x5B # [
+				parse_array
+			else
+				parse_bare_object
+			end
+
+			skip_trivia
+		end
+
+		private
+
+		def skip_trivia
+			source = @source
+			index = @index
+
+			while (byte = source.getbyte(index))
+				case byte
+				when 0x20, 0x09, 0x0A
+					index += 1
+				when 0x23 # #
+					finish = source.byteindex("\n", index) || @length
+					@comments << Comment.new(:line, index, finish)
+					index = finish
+				when 0x2F # /
+					# The parser checked that every block comment ends, so the search finds its `*/`.
+					finish = source.byteindex('*/', index + 2) + 2
+					@comments << Comment.new(:block, index, finish)
+					index = finish
+				else
+					break
+				end
+			end
+
+			@index = index
+		end
+
+		def parse_bare_object
+			members = []
+
+			loop do
+				members << parse_member
+				skip_trivia
+				break if @index >= @length
+			end
+
+			ObjectNode.new(members, false, members.first.start, members.last.finish)
+		end
+
+		def parse_object
+			start = @index
+			members = parse_items(0x7D) { parse_member }
+			ObjectNode.new(members, true, start, @index)
+		end
+
+		def parse_array
+			start = @index
+			elements = parse_items(0x5D) { parse_value }
+			ArrayNode.new(elements, start, @index)
+		end
+
+		# The items between an opening bracket and its `closing` bracket, which is consumed too. The parser has already checked the separators, including that a comma is on the line of the item before it.
+		def parse_items(closing)
+			items = []
+			@index += 1
+			skip_trivia
+
+			until @source.getbyte(@index) == closing
+				items << yield
+				skip_trivia
+				next unless @source.getbyte(@index) == 0x2C # ,
+
+				@index += 1
+				skip_trivia
+			end
+
+			@index += 1
+			items
+		end
+
+		def parse_member
+			key = parse_key
+			@index += 1 # :
+			skip_trivia
+			value = parse_value
+			MemberNode.new(key, value, key.start, value.finish)
+		end
+
+		def parse_key
+			source = @source
+			start = @index
+			byte = source.getbyte(start)
+
+			if byte == 0x27 || byte == 0x22 # ' "
+				finish = string_end(start)
+				@index = finish
+				text = source.byteslice(start + 1, finish - start - 2)
+
+				# A `"..."` key with an escape is decoded by the parser itself, so that the tree and `SOML.parse` cannot disagree.
+				return KeyNode.new(byte == 0x22 && text.include?('\\') ? read_scalar(start, finish) : text, start, finish)
+			end
+
+			finish = start
+			finish += 1 while (byte = source.getbyte(finish)) && BARE_KEY_BYTE[byte]
+			@index = finish
+			KeyNode.new(source.byteslice(start, finish - start), start, finish)
+		end
+
+		def parse_value
+			source = @source
+			start = @index
+
+			case (byte = source.getbyte(start))
+			when 0x7B # {
+				parse_object
+			when 0x5B # [
+				parse_array
+			when 0x27, 0x22 # ' "
+				return parse_block_string(byte) if source.getbyte(start + 1) == byte && source.getbyte(start + 2) == byte
+
+				@index = string_end(start)
+				ScalarNode.new(false, start, @index)
+			else
+				finish = start + 1
+				finish += 1 while (byte = source.getbyte(finish)) && NUMBER_BYTE[byte]
+				@index = finish
+				ScalarNode.new(false, start, finish)
+			end
+		end
+
+		# The offset after the closing quote of the one-line string at `start`. `'...'` ends at the next `'`. `"..."` ends at the next `"` that is not escaped, and `\` always starts a two-character escape or a `\u{…}`, which holds no quote.
+		def string_end(start)
+			source = @source
+			return source.byteindex("'", start + 1) + 1 if source.getbyte(start) == 0x27
+
+			index = start + 1
+
+			loop do
+				index = source.byteindex(ESCAPED_STRING_SPECIAL, index)
+				return index + 1 if source.getbyte(index) == 0x22
+
+				index += 2
+			end
+		end
+
+		# The block ends at the first line whose first non-whitespace content is a run of exactly as many quotes as the opening delimiter.
+		def parse_block_string(quote)
+			source = @source
+			start = @index
+			delimiter_length = 0
+			delimiter_length += 1 while source.getbyte(start + delimiter_length) == quote
+			line_start = source.byteindex("\n", start) + 1
+
+			loop do
+				delimiter_start = line_start
+				delimiter_start += 1 while (byte = source.getbyte(delimiter_start)) == 0x20 || byte == 0x09
+				run_length = 0
+				run_length += 1 while source.getbyte(delimiter_start + run_length) == quote
+
+				if run_length == delimiter_length
+					@index = delimiter_start + delimiter_length
+					return ScalarNode.new(true, start, @index)
+				end
+
+				line_start = source.byteindex("\n", line_start) + 1
+			end
+		end
+
+		# The value of the scalar from `start` to `finish`, read by the parser. A scalar's validity does not depend on its context, so it parses on its own inside an array.
+		def read_scalar(start, finish)
+			Parser.new("[#{@source.byteslice(start, finish - start)}]").parse.first
+		end
+	end
+end

data/lib/soml/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module SOML
+	# The version of this gem.
+	VERSION = '0.0.1'
+end

data/lib/soml-lang.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# The gem is named `soml-lang`, so that `Bundler.require` finds this file. The library is `require 'soml'`.
+require_relative 'soml'

data/lib/soml.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require_relative 'soml/version'
+
+# Read and write SOML, a config format for humans.
+#
+# @see https://github.com/soml-lang/soml The specification
+module SOML
+	# The deepest nesting either direction accepts. Every array and object is one level, including the document's own collection.
+	MAX_DEPTH = 100
+
+	INT64_MIN = -(2**63)
+	INT64_MAX = (2**63) - 1
+
+	# The duration units in their required order, with their length in nanoseconds.
+	DURATION_UNITS = {
+		'h' => 3_600_000_000_000,
+		'm' => 60_000_000_000,
+		's' => 1_000_000_000,
+		'ms' => 1_000_000,
+		'us' => 1000,
+		'ns' => 1
+	}.freeze
+
+	# 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) { |byte| byte.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.
+	NUMBER_BYTE = Array.new(256) { |byte| byte.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.
+	NOT_BLANK_CHARACTER = /[^\t ]/
+
+	# The default of the `value` of {SOML.edit}, which tells a missing value from `nil`.
+	NO_VALUE = Object.new.freeze
+
+	# The indentation of each level, so that the {Generator} and the {Printer} make no string for each line they indent. The {Printer} indents a value after a comment one level deeper than its key, so each container can be two levels deeper than the one that holds it, and a value after a comment in the deepest container is at level 200.
+	INDENTS = Array.new((MAX_DEPTH * 2) + 1) { |level| ("\t" * level).freeze }.freeze
+
+	private_constant :MAX_DEPTH, :INT64_MIN, :INT64_MAX, :DURATION_UNITS, :NO_VALUE, :BARE_KEY_BYTE, :NUMBER_BYTE, :NOT_BLANK_CHARACTER, :INDENTS
+
+	# Whether a key can be written without quotes, as a bare key: one or more ASCII letters, digits, `_`, or `-`, in any order, so `404` and `-x` are bare keys too. {SOML.generate} writes such a key bare and quotes every other key.
+	#
+	# @param key [String, Symbol] A key in UTF-8, or a symbol, which is read as its name. A key in an encoding that is not compatible with ASCII, such as UTF-16, is read as the UTF-8 string it converts to, as {SOML.generate} reads it. Any other object is not a key, so it gives false.
+	# @return [Boolean]
+	#
+	# @example
+	#   SOML.bare_key?('content-type')
+	#   #=> true
+	#
+	#   SOML.bare_key?('a.b')
+	#   #=> false
+	def self.bare_key?(key)
+		# Only a String or a Symbol is a key. Anything else, such as a number or nil, could never be a bare key, so the answer is false rather than a crash on its missing `encoding`.
+		return false unless String === key || Symbol === key
+
+		# The byte scan needs a String, so a Symbol is read as its name. A String, even a subclass, is left as it is, as the regex did.
+		key = key.to_s unless String === key
+		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.
+		return false if key.empty?
+
+		index = 0
+		length = key.bytesize
+
+		while index < length
+			return false unless BARE_KEY_BYTE[key.getbyte(index)]
+
+			index += 1
+		end
+
+		true
+	rescue ArgumentError, EncodingError
+		# Invalid bytes, or a key that does not convert to UTF-8.
+		false
+	end
+
+	# Parse a document.
+	#
+	# @param source [String] The document. A UTF-8, binary, or US-ASCII string is read as UTF-8, and a string in another encoding is converted to UTF-8 first.
+	# @param symbolize_names [Boolean] Whether object keys are symbols rather than strings.
+	# @param freeze [Boolean] Whether the result is deeply frozen, which also makes it shareable between ractors.
+	# @return [Hash, Array] The object or array the document contains.
+	# @raise [ParseError] When the document is not valid.
+	# @raise [TypeError] When `source` is not a string.
+	# @raise [EncodingError] When `source` is in an encoding other than UTF-8, binary, or US-ASCII, and does not convert to UTF-8.
+	#
+	# @example
+	#   SOML.parse(<<~SOML)
+	#     name: 'api-gateway'
+	#     replicas: 3
+	#     timeout: 30s
+	#     postgres: {host: 'db.internal'}
+	#   SOML
+	#   #=> {"name" => "api-gateway", "replicas" => 3, "timeout" => #<SOML::Duration 30s>, "postgres" => {"host" => "db.internal"}}
+	def self.parse(source, symbolize_names: false, freeze: false)
+		Parser.new(source, symbolize_names:, freeze:).parse
+	end
+
+	# Read and parse a file.
+	#
+	# The file is read in binary mode, so that a carriage return, which a document may not contain, is not hidden by a text-mode conversion. An error names the file, as in `Duplicate key port at config.soml:3:1`.
+	#
+	# @param path [String, #to_path] The file, such as a `Pathname` or a `File`.
+	# @param symbolize_names [Boolean] See {SOML.parse}.
+	# @param freeze [Boolean] See {SOML.parse}.
+	# @return [Hash, Array] The object or array the document contains.
+	# @raise [ParseError] When the document is not valid. Its message and {ParseError#path} name the file.
+	# @raise [SystemCallError] When the file cannot be read, such as `Errno::ENOENT`.
+	#
+	# @example
+	#   config = SOML.load_file('config.soml', symbolize_names: true)
+	def self.load_file(path, symbolize_names: false, freeze: false)
+		Parser.new(File.binread(path), symbolize_names:, freeze:, path: File.path(path)).parse
+	end
+
+	# Write a hash or an array as SOML.
+	#
+	# Members keep the order of their hash, nesting is written with braces and tabs, and the text ends with one line feed. Comments and block strings are never written. Everything but the order of members is canonical form, so the text is canonical form when the keys are already sorted.
+	#
+	# With `canonical: true`, members are sorted by key too, so the text is canonical form. Two equal values then give the same text, which can be hashed, signed, or compared.
+	#
+	# @param value [Hash, Array] The document.
+	# @param canonical [Boolean] Whether to write canonical form, with members sorted by key.
+	# @return [String] The text, in UTF-8.
+	# @raise [GenerateError] For a value that cannot be written, such as NaN, an integer outside the 64-bit range, a key that is not a string or a symbol, or an object of another class.
+	#
+	# @example
+	#   SOML.generate({name: 'api-gateway', replicas: 3, ratio: 0.5})
+	#   #=> "name: 'api-gateway'\nreplicas: 3\nratio: 0.5\n"
+	#
+	#   SOML.generate({name: 'api-gateway', replicas: 3, ratio: 0.5}, canonical: true)
+	#   #=> "name: 'api-gateway'\nratio: 0.5\nreplicas: 3\n"
+	def self.generate(value, canonical: false)
+		Generator.new(canonical:).generate(value)
+	end
+
+	# Format a document. Returns the document with its layout normalized, ending with one line feed.
+	#
+	# The layout follows the formatter in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. An object or an array whose brackets are on one line stays on one line, as in `ports: [80, 443]`, with a comma and a space between its members or items. To give a one-line container one member or item per line, put a line break anywhere inside it. Comments, member order, block strings, and the spelling of every value stay as they are, so the value never changes. The one change inside a block comment is the same layout rule: trailing whitespace is removed, and runs of blank lines collapse to one.
+	#
+	# In detail, as the specification states:
+	#
+	# - A block comment that a value follows on the same line, as in `1, /* note */ 2`, stays in front of that value when each item goes on its own line.
+	# - One space follows each `:`, as in canonical form.
+	# - A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key, and the blank lines between them are removed.
+	# - A block string begins on the line after its key, and its delimiters and content have the indentation of that line. Its lines are not otherwise changed.
+	# - There are no blank lines at the start of the file or directly inside brackets.
+	#
+	# @param source [String] The document, read as {SOML.parse} reads it.
+	# @return [String] The formatted document, in UTF-8, ending with one line feed.
+	# @raise [ParseError] When the document is not valid, the same as {SOML.parse}.
+	# @raise [TypeError] When `source` is not a string.
+	# @raise [EncodingError] When `source` is in an encoding other than UTF-8, binary, or US-ASCII, and does not convert to UTF-8.
+	#
+	# @example
+	#   SOML.format('pool: {min: 2,   max: 16,} # Connections')
+	#   #=> "pool: {min: 2, max: 16} # Connections\n"
+	#
+	#   SOML.format("pool: {\nmin: 2, max: 16}")
+	#   #=> "pool: {\n\tmin: 2\n\tmax: 16\n}\n"
+	def self.format(source)
+		Printer.new(Tree.new(source)).print
+	end
+
+	# Change one value in a document, and keep everything else as it is written: comments, member order, layout, and the spelling of every other value. For tools that update a config file, such as a dependency bumper or a `set` command.
+	#
+	# The value at `path` is replaced, or added when it does not exist yet, and `delete: true` removes it. Only the changed part of the text is rewritten, and an edit to a formatted document leaves it formatted.
+	#
+	# - A new value is written as {SOML.generate} writes it, in canonical form except that its members keep their order, at the indentation of its line. So `0xFF` that is replaced by `255` is written `255`. In a container that is on one line, it is written on one line too, so `[1, 2]` with a new item `{a: 3}` becomes `[1, 2, {a: 3}]`.
+	# - A new member goes after the last member of its object. Missing objects on the way are created.
+	# - A new item can be added at the end of an array, with the index that is its length.
+	# - A new member or item goes on its own line without a comma, after the comments that the one before it owns (see below), and the commas of the other members and items stay as they are. When something follows the member or item before it on the same line, such as the closing bracket of the one-line container `{a: 1}`, it goes on that line after a comma, as in `{a: 1, b: 2}`. In an empty `[]` or `{}`, it goes on a line of its own, unless that container is inside a container on one line, so `a: [1, []]` becomes `a: [1, [2]]`.
+	# - A removed member or item takes the comments it owns, which in a formatted document are the ones that {SOML.format} keeps with it: the comments after it on its line, also after its comma when nothing else follows there, and the block comments before it on its line, after the comma or bracket before it. So removing `2` from `[1, /* note */ 2]` gives `[1]`. A comment on a line of its own belongs to no member or item, so it stays. A removed member or item also removes its lines when nothing else is on them. A line that a block comment after it continues onto counts as one of its lines. Removing every item of a container closes it up to `[]` or `{}`, unless a comment is left inside.
+	# - A removed member or item takes its comma with it. When the removed items are the last ones and have no comma after them, they take the comma directly before them instead, when only spaces, tabs, and the comments they own are between, so `[1, 2]` becomes `[1]`.
+	# - Removing the only member of a document without braces leaves `{}`.
+	#
+	# Comments inside a value that is replaced or removed are removed with it. In a layout that {SOML.format} never writes, such as an item after a closing block string delimiter on its line, a new item can be indented differently from its neighbors, but the document is always valid and has the right value. Removing a value that does not exist changes nothing and is not an error: a missing member, a missing object or array on the way, or an index at or past the end of its array. So removing the same path twice is safe. The result has the same bytes as `source` exactly when nothing was removed, so `SOML.edit(source, path, delete: true).b == source.b` tells whether something was removed. The `.b` compares the bytes, because a source read in binary mode is not `==` to the UTF-8 result when it has a character that is not ASCII. This holds for a source in UTF-8, binary, or US-ASCII, because one in another encoding is converted to UTF-8.
+	#
+	# The result is parsed before it is returned, so a bug in `edit` raises a `RuntimeError` rather than returning a broken document.
+	#
+	# @overload edit(source, path, value)
+	#   @param source [String] The document, read as {SOML.parse} reads it.
+	#   @param path [Array<String, Symbol, Integer>] The keys and array indexes that lead to the value, such as `['servers', 0, 'port']`.
+	#   @param value [Object] The new value, of the types that {SOML.generate} accepts. Write a `Hash` with braces, because without them Ruby passes its members as keyword arguments.
+	#   @return [String] The changed document, in UTF-8.
+	# @overload edit(source, path, delete: true)
+	#   @param source [String] The document, read as {SOML.parse} reads it.
+	#   @param path [Array<String, Symbol, Integer>] The keys and array indexes that lead to the value.
+	#   @param delete [true] Remove the value.
+	#   @return [String] The changed document, in UTF-8.
+	# @raise [ParseError] When the document is not valid, the same as {SOML.parse}.
+	# @raise [ArgumentError] When both a value and `delete: true` are given, or neither.
+	# @raise [TypeError] When `source` is not a string, when `path` is not a non-empty array of keys and array indexes, when it leads through a value that is not an object or an array, or when it has a key where an array is or an index where an object is.
+	# @raise [IndexError] When a value is set at an index past the end of its array, or at an index under a value that does not exist.
+	# @raise [GenerateError] For a value or a key that {SOML.generate} cannot write, and when the change would nest the document more than 100 levels deep.
+	# @raise [EncodingError] When `source` is in an encoding other than UTF-8, binary, or US-ASCII, and does not convert to UTF-8.
+	#
+	# @example
+	#   SOML.edit("name: 'api' # The service\nport: 8080\n", ['port'], 9090)
+	#   #=> "name: 'api' # The service\nport: 9090\n"
+	#
+	#   SOML.edit("postgres: {\n\thost: 'db'\n}\n", ['postgres', 'port'], 5432)
+	#   #=> "postgres: {\n\thost: 'db'\n\tport: 5432\n}\n"
+	#
+	#   SOML.edit("a: 1\nb: 2\n", ['a'], delete: true)
+	#   #=> "b: 2\n"
+	def self.edit(source, path, value = NO_VALUE, delete: false)
+		if delete
+			raise ArgumentError, 'Pass either a value or delete: true, not both' unless NO_VALUE.equal?(value)
+		elsif NO_VALUE.equal?(value)
+			raise ArgumentError, 'Pass the new value, or delete: true to remove the value'
+		end
+
+		Editor.new(source, path, value, delete:).edit
+	end
+end
+
+require_relative 'soml/error'
+require_relative 'soml/duration'
+require_relative 'soml/parser'
+require_relative 'soml/generator'
+require_relative 'soml/tree'
+require_relative 'soml/format'
+require_relative 'soml/edit'

data/license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+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.