punctuated 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 44f5d30890160857cc82ff20ffe096fb8c063c614a3dd22e6c7f187513431a4f
+  data.tar.gz: bf3c0eb0f0ac606d4f14c0996fc92879dec257290ba3afb665002dbc2004de71
+SHA512:
+  metadata.gz: 5b54216e598db32e130a5a9c3149eda0be6cb0376236ad3d98cd5ebc8e7ba6fabad2fb036b8f6789949d014a14bdf1249818a9c76dd94025310c513a4a454a1d
+  data.tar.gz: 94b72417fe7ebd12f61197a81a714154bcfff7c6bfe0b749c0e8787963e301f90ec70a74a750d6c55f6bc2ea609d803be05d1761d94d2f0f780b7b1b413f5205

data/changelog.md

@@ -0,0 +1,11 @@
+# Changelog
+
+
+## 0.9.0
+
+* Unicode-aware parsing of sentence terminals and surrounding wrappers at either string boundary.
+* APIs to detect, ensure, strip and replace punctuation, including mutable parsed objects and bang variants.
+* Coordinated inside/outside placement.
+* Strict option validation and string/symbol-indifferent configuration.
+* Support for Ruby 2.3 and later, with a cross-version continuous integration matrix.
+* Executable examples, package validation and release documentation.

data/lib/punctuated/component.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Punctuated
+	# A mutable parsed run. Setters delegate to Parsed so paired placements always remain coordinated.
+	class Component
+		attr_reader :raw, :placement
+
+		def initialize(owner, side, raw = "", placement = nil)
+			@owner = owner
+			@side = side
+			commit(raw, placement)
+		end
+
+		def raw=(value)
+			@owner.change_component(@side, kind, raw: value)
+		end
+
+		def placement=(value)
+			@owner.change_component(@side, kind, placement: value)
+		end
+
+		# Whitespace is formatting owned by the run, not one of its punctuation characters.
+		def chars
+			@raw.each_char.reject { |character| WHITESPACE.match(character) }
+		end
+
+		# The owner calculates this structurally, avoiding false matches when raw strings repeat.
+		def index
+			return -1 if @raw.empty?
+
+			@owner.component_index(self)
+		end
+
+		def kind
+			self.class::KIND
+		end
+
+		protected
+
+		def commit(raw, placement)
+			@raw = raw.dup
+			@placement = placement
+		end
+	end
+
+	# Describes one sentence-terminal run at the start or end of a parsed string.
+	class Terminal < Component
+		KIND = :terminal
+	end
+
+	# Describes one opening/closing/quotation run at the start or end of a parsed string.
+	class Wrapper < Component
+		KIND = :wrapper
+	end
+end

data/lib/punctuated/constants.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Punctuated
+	# Sentence-terminal characters recognised by Unicode, plus inverted sentence terminals omitted from STerm.
+	TERMINAL = /[\p{STerm}¡¿⸘]/u
+
+	# Opening, closing and quotation characters that may surround a sentence terminal.
+	WRAPPER = /(?:[\p{Ps}\p{Pe}\p{Pi}\p{Pf}]|\p{Quotation_Mark})/u
+
+	# Whitespace deliberately uses Ruby's normal \s semantics, as required by the public contract.
+	WHITESPACE = /\s/u
+end

data/lib/punctuated/options.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Punctuated
+	# Centralises strict option validation and string/symbol indifference for every public method.
+	module Options
+		module_function
+
+		def hash(positional, keywords, allowed:, label: "options")
+			unless positional.nil? || positional.is_a?(Hash)
+				raise ArgumentError, "#{label} must be a Hash"
+			end
+
+			normalised = {}
+			[positional || {}, keywords || {}].each do |source|
+				source.each do |key, value|
+					normalised_key = key(key)
+					unless allowed.include?(normalised_key)
+						raise ArgumentError, "unknown #{label} key: #{key.inspect}"
+					end
+					if normalised.key?(normalised_key)
+						raise ArgumentError, "duplicate #{label} key: #{normalised_key.inspect}"
+					end
+
+					normalised[normalised_key] = value
+				end
+			end
+
+			normalised
+		end
+
+		def key(value)
+			return value if value.is_a?(Symbol)
+			return value.to_sym if value.is_a?(String)
+
+			raise ArgumentError, "option keys must be Strings or Symbols"
+		end
+
+		def enum(value, allowed:, label:, allow_nil: false)
+			return nil if value.nil? && allow_nil
+
+			normalised = if value.is_a?(String)
+				value.to_sym
+			elsif value.is_a?(Symbol)
+				value
+			end
+			unless allowed.include?(normalised)
+				raise ArgumentError, "invalid #{label}: #{value.inspect}"
+			end
+
+			normalised
+		end
+
+		def placement(value, allow_nil: true)
+			enum(value, allowed: [:inside, :outside], label: "placement", allow_nil: allow_nil)
+		end
+
+		def side(value)
+			enum(value, allowed: [:start, :end], label: "side")
+		end
+
+		# Expands shorthand values to start/end pairs, optionally directing shorthand to one implicit side.
+		def sides(value, label:, side: nil, &validator)
+			implicit_side = side.nil? ? nil : self.side(side)
+			values = value.is_a?(Array) ? value.dup : [value]
+			case values.length
+			when 1
+				values = case implicit_side
+				when :start
+					[values.first, nil]
+				when :end
+					[nil, values.first]
+				else
+					[values.first, values.first]
+				end
+			when 2
+				# Already in the required two-sided form.
+			else
+				raise ArgumentError, "#{label} must contain one or two elements"
+			end
+
+			values.map(&validator)
+		end
+	end
+end

data/lib/punctuated/parsed/composition.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Punctuated
+class Parsed
+	# Recombines parsed state and provides the single commit path for all component changes.
+	module Composition
+		# Rebuilds from current state on every call, so returned strings can be mutated safely.
+		def result
+			result_parts.map { |part| part.is_a?(Component) ? part.raw : part }.join
+		end
+
+		def component_index(target)
+			offset = 0
+			result_parts.each do |part|
+				return offset if part.equal?(target)
+
+				offset += part.is_a?(Component) ? part.raw.length : part.length
+			end
+			-1
+		end
+
+		# Raw and placement setters enter here so a public mutation commits one coordinated pair.
+		def change_component(side, kind, attributes)
+			change = {}
+			if attributes.key?(:raw)
+				change[:raw] = attributes[:raw]
+			end
+			if attributes.key?(:placement)
+				change[:placement] = attributes[:placement]
+				change[:placement_specified] = true
+			end
+
+			apply_component_changes(side => { kind => change })
+			component(side, kind)
+		end
+
+		private
+
+		def build_components
+			@terminals = [Terminal.new(self, 0), Terminal.new(self, 1)].freeze
+			@wrappers = [Wrapper.new(self, 0), Wrapper.new(self, 1)].freeze
+		end
+
+		def result_parts
+			ordered_components(0) + [@content] + ordered_components(1)
+		end
+
+		def ordered_components(side)
+			present = KINDS.map { |kind| component(side, kind) }.reject { |item| item.raw.empty? }
+			return present if present.length < 2
+
+			if side.zero?
+				present.sort_by { |item| item.placement == :outside ? 0 : 1 }
+			else
+				present.sort_by { |item| item.placement == :inside ? 0 : 1 }
+			end
+		end
+
+		# Every operation is fully validated and coordinated here before any component is committed.
+		def apply_component_changes(changes)
+			candidates = {}
+			changes.each do |side, pair_changes|
+				candidates[side] = coordinated_pair(side, pair_changes)
+			end
+
+			candidates.each do |side, pair|
+				KINDS.each do |kind|
+					state = pair[kind]
+					component(side, kind).__send__(:commit, state[:raw], state[:placement])
+				end
+			end
+		end
+
+		# Computes a complete candidate before committing, with explicit placement requests taking priority.
+		def coordinated_pair(side, changes)
+			current = {}
+			candidate = {}
+			explicit = {}
+			KINDS.each do |kind|
+				item = component(side, kind)
+				current[kind] = { raw: item.raw, placement: item.placement }
+				change = changes.fetch(kind, {})
+				raw = change.key?(:raw) ? change[:raw] : item.raw
+				unless raw.is_a?(String)
+					raise ArgumentError, "raw must be a String"
+				end
+				candidate[kind] = { raw: raw, placement: item.placement }
+				if change[:placement_specified]
+					explicit[kind] = Options.placement(change[:placement])
+				end
+			end
+
+			explicit.each do |kind, placement|
+				if candidate[kind][:raw].empty? && placement
+					raise ArgumentError, "an absent #{kind} cannot have a placement"
+				end
+			end
+
+			present = KINDS.reject { |kind| candidate[kind][:raw].empty? }
+			if present.empty?
+				KINDS.each { |kind| candidate[kind][:placement] = nil }
+			elsif present.length == 1
+				coordinate_lone_component(current, candidate, present.first, explicit)
+			else
+				coordinate_complete_pair(current, candidate, explicit)
+			end
+			candidate
+		end
+
+		def coordinate_lone_component(current, candidate, present_kind, explicit)
+			absent_kind = counterpart(present_kind)
+			candidate[absent_kind][:placement] = nil
+			removed_component = KINDS.any? { |kind| !current[kind][:raw].empty? && candidate[kind][:raw].empty? }
+			candidate[present_kind][:placement] = if removed_component
+				nil
+			elsif explicit.key?(present_kind)
+				explicit[present_kind]
+			else
+				current[present_kind][:placement]
+			end
+		end
+
+		def coordinate_complete_pair(current, candidate, explicit)
+			non_nil_preferences = explicit.reject { |_kind, placement| placement.nil? }
+			if non_nil_preferences.length == 2 && non_nil_preferences.values.uniq.length == 1
+				raise ArgumentError, "terminal and wrapper cannot have the same placement"
+			end
+
+			if !non_nil_preferences.empty?
+				preferred_kind, preferred_placement = non_nil_preferences.first
+				set_opposite_placements(candidate, preferred_kind, preferred_placement)
+			elsif !explicit.empty?
+				set_natural_placements(candidate)
+			elsif KINDS.all? { |kind| !current[kind][:raw].empty? }
+				candidate[:terminal][:placement] = current[:terminal][:placement]
+				candidate[:wrapper][:placement] = current[:wrapper][:placement]
+			else
+				existing_kind = KINDS.find { |kind| !current[kind][:raw].empty? }
+				if existing_kind && current[existing_kind][:placement]
+					set_opposite_placements(candidate, existing_kind, current[existing_kind][:placement])
+				else
+					set_natural_placements(candidate)
+				end
+			end
+		end
+
+		def set_opposite_placements(candidate, kind, placement)
+			candidate[kind][:placement] = placement
+			candidate[counterpart(kind)][:placement] = placement == :inside ? :outside : :inside
+		end
+
+		def set_natural_placements(candidate)
+			candidate[:terminal][:placement] = :inside
+			candidate[:wrapper][:placement] = :outside
+		end
+
+		def counterpart(kind)
+			kind == :terminal ? :wrapper : :terminal
+		end
+	end
+end
+end

data/lib/punctuated/parsed/operations.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+module Punctuated
+class Parsed
+	# Implements punctuation queries and transformations over already parsed state.
+	module Operations
+		QUERY_METHODS = [:start_with?, :end_with?].freeze
+		TRANSFORMING_METHODS = [:ensure, :ensure_start, :strip, :lstrip, :rstrip, :replace].freeze
+		METHODS = (QUERY_METHODS + TRANSFORMING_METHODS).freeze
+		METHOD_SIDES = {
+			start_with?: :start,
+			end_with?: :end,
+			lstrip: :start,
+			rstrip: :end
+		}.freeze
+
+		# Non-bang transformations are uniformly independent views of their bang implementation.
+		TRANSFORMING_METHODS.each do |method_name|
+			define_method(method_name) do |*arguments, **keywords, &block|
+				copy = dup
+				copy.public_send("#{method_name}!", *arguments, **keywords, &block)
+				copy.result
+			end
+		end
+
+		def start_with?(terminal = nil, options = nil, **keywords)
+			terminal, settings = terminal_and_options(terminal, options, keywords, allowed: [:placement])
+			matches_terminal?(0, terminal, settings)
+		end
+
+		def end_with?(terminal = nil, options = nil, **keywords)
+			terminal, settings = terminal_and_options(terminal, options, keywords, allowed: [:placement])
+			matches_terminal?(1, terminal, settings)
+		end
+
+		alias at_start? start_with?
+		alias at_end? end_with?
+
+		def ensure!(terminal = DEFAULT_TERMINALS, options = nil, **keywords)
+			terminal, settings = terminal_and_options(terminal, options, keywords, allowed: [:placement], default_terminal: DEFAULT_TERMINALS)
+			terminals = Options.sides(terminal, label: "terminal", side: :end) { |value| validate_terminal(value) }
+			placements = if settings.key?(:placement)
+				Options.sides(settings[:placement], label: "placement", side: :end) { |value| Options.placement(value) }
+			else
+				[nil, nil]
+			end
+			changes = {}
+
+			2.times do |side|
+				fallback = terminals[side]
+				next if fallback.nil?
+
+				terminal_component = component(side, :terminal)
+				placement = placements[side]
+				if terminal_component.raw.empty?
+					next if fallback.empty?
+
+					terminal_change = { raw: fallback, placement: placement || :inside, placement_specified: true }
+				elsif placement
+					terminal_change = { placement: placement, placement_specified: true }
+				else
+					next
+				end
+
+				changes[side] = {
+					terminal: terminal_change
+				}
+			end
+			apply_component_changes(changes)
+			self
+		end
+
+		def ensure_start!(terminal, options = nil, **keywords)
+			validate_single_terminal(terminal)
+			settings = Options.hash(options, keywords, allowed: [:placement])
+			if settings.key?(:placement)
+				if settings[:placement].is_a?(Array)
+					raise ArgumentError, "ensure_start placement does not accept Arrays"
+				end
+				settings[:placement] = [settings[:placement], nil]
+			end
+			ensure!([terminal, nil], settings, **{})
+		end
+
+		def strip!(options = nil, **keywords)
+			settings = Options.hash(options, keywords, allowed: [:terminals, :wrappers], label: "strip options")
+			terminal_settings = Options.sides(settings.fetch(:terminals, true), label: "terminals") { |value| validate_strip_value(value) }
+			wrapper_settings = Options.sides(settings.fetch(:wrappers, nil), label: "wrappers") { |value| validate_strip_value(value) }
+			changes = {}
+
+			# Select everything against the original placements before coordinating any removals.
+			2.times do |side|
+				pair_changes = {}
+				if strip_selected?(side, :terminal, terminal_settings[side])
+					pair_changes[:terminal] = { raw: "" }
+				end
+				if strip_selected?(side, :wrapper, wrapper_settings[side])
+					pair_changes[:wrapper] = { raw: "" }
+				end
+				changes[side] = pair_changes unless pair_changes.empty?
+			end
+			apply_component_changes(changes)
+			self
+		end
+
+		def lstrip!(options = nil, **keywords)
+			side_strip!(0, options, keywords)
+		end
+
+		def rstrip!(options = nil, **keywords)
+			side_strip!(1, options, keywords)
+		end
+
+		def replace!(replacements = nil, **keywords)
+			settings = Options.hash(replacements, keywords, allowed: [:terminals, :wrappers], label: "replacement options")
+			if settings.empty?
+				raise ArgumentError, "replace requires wrappers and/or terminals"
+			end
+
+			normalised = {}
+			settings.each do |kind_plural, value|
+				normalised[kind_plural] = Options.sides(value, label: kind_plural.to_s) { |entry| entry }
+			end
+
+			# Resolve every Proc and validate every candidate before changing either side.
+			changes = {}
+			2.times do |side|
+				pair_changes = {}
+				{ terminals: :terminal, wrappers: :wrapper }.each do |plural, kind|
+					next unless normalised.key?(plural)
+
+					replacement = replacement_change(normalised[plural][side], component(side, kind).raw)
+					pair_changes[kind] = replacement if replacement
+				end
+				changes[side] = pair_changes unless pair_changes.empty?
+			end
+			apply_component_changes(changes)
+			self
+		end
+
+		private
+
+		def terminal_and_options(terminal, options, keywords, allowed:, default_terminal: nil)
+			if terminal.is_a?(Hash) && options.nil?
+				settings = Options.hash(terminal, keywords, allowed: allowed)
+				terminal = default_terminal
+			else
+				settings = Options.hash(options, keywords, allowed: allowed)
+			end
+			[terminal, settings]
+		end
+
+		def validate_terminal(value)
+			return value if value.nil? || value.is_a?(String)
+
+			raise ArgumentError, "terminal must be nil or a String"
+		end
+
+		def validate_single_terminal(value)
+			if value.is_a?(Array)
+				raise ArgumentError, "terminal must not be an Array"
+			end
+			validate_terminal(value)
+		end
+
+		def matches_terminal?(side, expected, settings)
+			validate_terminal(expected)
+			placement = settings.key?(:placement) ? Options.placement(settings[:placement], allow_nil: false) : nil
+			terminal = component(side, :terminal)
+			return false if terminal.raw.empty?
+			if placement && !component(side, :wrapper).raw.empty? && terminal.placement != placement
+				return false
+			end
+			return true if expected.nil?
+
+			actual_chars = terminal.chars.join
+			expected_chars = expected.each_char.reject { |character| whitespace?(character) }.join
+			side.zero? ? actual_chars.start_with?(expected_chars) : actual_chars.end_with?(expected_chars)
+		end
+
+		def validate_strip_value(value)
+			return value if value.nil? || value == true
+
+			Options.placement(value, allow_nil: false)
+		end
+
+		def strip_selected?(side, kind, setting)
+			item = component(side, kind)
+			return false if setting.nil? || item.raw.empty?
+			return true if setting == true
+			return true if component(side, counterpart(kind)).raw.empty?
+
+			item.placement == setting
+		end
+
+		def side_strip!(side, options, keywords)
+			settings = Options.hash(options, keywords, allowed: [:terminals, :wrappers], label: "strip options")
+			terminal_setting = settings.fetch(:terminals, true)
+			wrapper_setting = settings.fetch(:wrappers, nil)
+			if terminal_setting.is_a?(Array) || wrapper_setting.is_a?(Array)
+				raise ArgumentError, "lstrip and rstrip options do not accept Arrays"
+			end
+			validate_strip_value(terminal_setting)
+			validate_strip_value(wrapper_setting)
+
+			terminal_sides = side.zero? ? [terminal_setting, nil] : [nil, terminal_setting]
+			wrapper_sides = side.zero? ? [wrapper_setting, nil] : [nil, wrapper_setting]
+			strip!({ terminals: terminal_sides, wrappers: wrapper_sides }, **{})
+		end
+
+		def replacement_change(value, current_raw, allow_proc: true)
+			if value.nil?
+				return nil
+			elsif value.is_a?(Proc)
+				unless allow_proc
+					raise ArgumentError, "a replacement Proc cannot return another Proc"
+				end
+				return replacement_change(value.call(current_raw), current_raw, allow_proc: false)
+			elsif value.is_a?(String)
+				return { raw: value }
+			elsif value.is_a?(Hash)
+				settings = Options.hash(value, {}, allowed: [:new, :placement], label: "replacement")
+				unless settings.key?(:new)
+					raise ArgumentError, "replacement Hash requires new"
+				end
+				unless settings[:new].is_a?(String)
+					raise ArgumentError, "replacement new must be a String"
+				end
+
+				change = { raw: settings[:new] }
+				if settings.key?(:placement)
+					change[:placement] = Options.placement(settings[:placement], allow_nil: false)
+					change[:placement_specified] = true
+				end
+				return change
+			end
+
+			raise ArgumentError, "invalid replacement: #{value.inspect}"
+		end
+	end
+end
+end

data/lib/punctuated/parsed/parsing.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module Punctuated
+class Parsed
+	# Discovers the terminal and wrapper runs at the requested string boundaries.
+	module Parsing
+		private
+
+		def parse_constraints(settings, key)
+			return [nil, nil] unless settings.key?(key)
+
+			Options.sides(settings[key], label: key.to_s) { |value| Options.placement(value) }
+		end
+
+		def parse_string(string)
+			unless string.is_a?(String)
+				parse_failure("input is not a String")
+				return
+			end
+
+			unless string.valid_encoding?
+				parse_failure("input has an invalid encoding")
+				return
+			end
+
+			begin
+				parse_valid_string(string)
+			rescue Encoding::CompatibilityError, ArgumentError => error
+				parse_failure(error.message)
+			end
+		end
+
+		def parse_failure(reason)
+			Kernel.warn("Punctuated could not parse input: #{reason}")
+			@original = "".freeze
+			@content = ""
+		end
+
+		def parse_valid_string(string)
+			@original = string.dup.freeze
+			if string.empty?
+				@content = ""
+				return
+			end
+
+			case @side_mode
+			when :start
+				start_boundary = constrained_boundary(scan_start(string), 0)
+				commit_parsed_boundary(start_boundary, 0)
+				@content = string[start_boundary_position(start_boundary), string.length] || ""
+			when :end
+				end_boundary = constrained_boundary(scan_end(string), 1)
+				commit_parsed_boundary(end_boundary, 1)
+				@content = string[0, end_boundary_position(end_boundary, string.length)] || ""
+			else
+				end_boundary = constrained_boundary(scan_end(string), 1)
+				end_position = end_boundary_position(end_boundary, string.length)
+				start_source = string[0, end_position] || ""
+				start_boundary = constrained_boundary(scan_start(start_source), 0)
+				start_position = start_boundary_position(start_boundary)
+				commit_parsed_boundary(start_boundary, 0)
+				commit_parsed_boundary(end_boundary, 1)
+				@content = string[start_position, end_position - start_position] || ""
+			end
+		end
+
+		# Returns outer-to-inner runs and their exact character offsets at the start boundary.
+		def scan_start(string)
+			characters = string.each_char.to_a
+			cursor = 0
+			cursor += 1 while cursor < characters.length && whitespace?(characters[cursor])
+			outer_kind = character_kind(characters[cursor])
+			return [] unless outer_kind
+
+			outer_end = scan_run_forward(characters, cursor, outer_kind)
+			runs = [{ kind: outer_kind, raw: string[0, outer_end], begin: 0, end: outer_end }]
+			inner_kind = character_kind(characters[outer_end])
+			if inner_kind && inner_kind != outer_kind
+				inner_end = scan_run_forward(characters, outer_end, inner_kind)
+				runs << { kind: inner_kind, raw: string[outer_end, inner_end - outer_end], begin: outer_end, end: inner_end }
+			end
+			runs
+		end
+
+		def scan_run_forward(characters, cursor, kind)
+			while cursor < characters.length
+				if character_kind(characters[cursor]) == kind
+					cursor += 1
+					next
+				end
+				break unless whitespace?(characters[cursor])
+
+				cursor += 1 while cursor < characters.length && whitespace?(characters[cursor])
+				break unless cursor < characters.length && character_kind(characters[cursor]) == kind
+			end
+			cursor
+		end
+
+		# Scans from the outside edge backwards, retaining offsets in normal string order.
+		def scan_end(string)
+			characters = string.each_char.to_a
+			cursor = characters.length - 1
+			cursor -= 1 while cursor >= 0 && whitespace?(characters[cursor])
+			outer_kind = character_kind(characters[cursor])
+			return [] unless outer_kind
+
+			outer_begin = scan_run_backward(characters, cursor, outer_kind)
+			runs = [{ kind: outer_kind, raw: string[outer_begin, characters.length - outer_begin], begin: outer_begin, end: characters.length }]
+			inner_cursor = outer_begin - 1
+			inner_kind = character_kind(characters[inner_cursor])
+			if inner_kind && inner_kind != outer_kind
+				inner_begin = scan_run_backward(characters, inner_cursor, inner_kind)
+				runs << { kind: inner_kind, raw: string[inner_begin, outer_begin - inner_begin], begin: inner_begin, end: outer_begin }
+			end
+			runs
+		end
+
+		def scan_run_backward(characters, cursor, kind)
+			while cursor >= 0
+				if character_kind(characters[cursor]) == kind
+					cursor -= 1
+					next
+				end
+				break unless whitespace?(characters[cursor])
+
+				cursor -= 1 while cursor >= 0 && whitespace?(characters[cursor])
+				break unless cursor >= 0 && character_kind(characters[cursor]) == kind
+			end
+			cursor + 1
+		end
+
+		def character_kind(character)
+			return nil unless character
+			return :terminal if TERMINAL.match(character)
+			return :wrapper if WRAPPER.match(character)
+
+			nil
+		end
+
+		def whitespace?(character)
+			WHITESPACE.match(character)
+		end
+
+		# A rejected inner run leaves it in content; rejecting an outer run makes the boundary inaccessible.
+		def constrained_boundary(runs, side)
+			return runs unless runs.length == 2
+
+			if @wrapper_constraints[side]
+				target_kind = :wrapper
+				constraint = @wrapper_constraints[side]
+			elsif @terminal_constraints[side]
+				target_kind = :terminal
+				constraint = @terminal_constraints[side]
+			else
+				return runs
+			end
+			target_index = runs.index { |run| run[:kind] == target_kind }
+			actual = target_index.zero? ? :outside : :inside
+			return runs if actual == constraint
+
+			target_index.zero? ? [] : [runs.first]
+		end
+
+		def start_boundary_position(runs)
+			runs.empty? ? 0 : runs.last[:end]
+		end
+
+		def end_boundary_position(runs, string_length)
+			runs.empty? ? string_length : runs.last[:begin]
+		end
+
+		def commit_parsed_boundary(runs, side)
+			runs.each_with_index do |run, index|
+				placement = runs.length == 1 ? nil : (index.zero? ? :outside : :inside)
+				component(side, run[:kind]).__send__(:commit, run[:raw], placement)
+			end
+		end
+	end
+end
+end

data/lib/punctuated/parsed.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative "component"
+require_relative "options"
+require_relative "parsed/composition"
+require_relative "parsed/parsing"
+require_relative "parsed/operations"
+
+module Punctuated
+	# Holds a decomposed string while focused concerns parse, inspect and transform its state.
+	class Parsed
+		DEFAULT_TERMINALS = ".".freeze
+		KINDS = [:terminal, :wrapper].freeze
+
+		include Composition
+		include Parsing
+		include Operations
+
+		attr_reader :original, :terminals, :wrappers
+
+		def initialize(string, options = nil, **keywords)
+			settings = Options.hash(options, keywords, allowed: [:side, :wrappers, :terminals], label: "parse options")
+			if settings.key?(:wrappers) && settings.key?(:terminals)
+				raise ArgumentError, "wrappers and terminals placement constraints are mutually exclusive"
+			end
+
+			@side_mode = settings.key?(:side) ? Options.side(settings[:side]) : nil
+			@wrapper_constraints = parse_constraints(settings, :wrappers)
+			@terminal_constraints = parse_constraints(settings, :terminals)
+			build_components
+			parse_string(string)
+		end
+
+		def initialize_copy(source)
+			super
+			@original = source.original.dup.freeze
+			@content = source.content.dup
+			@side_mode = source.instance_variable_get(:@side_mode)
+			@wrapper_constraints = source.instance_variable_get(:@wrapper_constraints).dup
+			@terminal_constraints = source.instance_variable_get(:@terminal_constraints).dup
+			build_components
+			2.times do |side|
+				KINDS.each do |kind|
+					source_component = source.component(side, kind)
+					component(side, kind).__send__(:commit, source_component.raw, source_component.placement)
+				end
+			end
+		end
+
+		def content
+			@content
+		end
+
+		def content=(value)
+			unless value.is_a?(String)
+				raise ArgumentError, "content must be a String"
+			end
+
+			@content = value
+		end
+
+		# Internal access is public for collaborating Component instances, but is not part of the documented API.
+		def component(side, kind)
+			kind == :terminal ? @terminals[side] : @wrappers[side]
+		end
+	end
+end

data/lib/punctuated/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Punctuated
+	VERSION = "0.9.0"
+end

data/lib/punctuated.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative "punctuated/constants"
+require_relative "punctuated/version"
+require_relative "punctuated/parsed"
+
+module Punctuated
+	class << self
+		# Parse is an alias of new so either entry point produces the same mutable representation.
+		def new(string, options = nil, **keywords)
+			Parsed.new(string, options, **keywords)
+		end
+		alias parse new
+
+		# Each static API method delegates to the corresponding Parsed implementation.
+		Parsed::Operations::METHODS.each do |method_name|
+			side = Parsed::Operations::METHOD_SIDES[method_name]
+			define_method(method_name) do |string, *arguments, **keywords, &block|
+				parsed = side ? Parsed.new(string, side: side) : Parsed.new(string)
+				parsed.public_send(method_name, *arguments, **keywords, &block)
+			end
+		end
+
+		# Static bang methods share the same declaration and differ only in their String commit semantics.
+		Parsed::Operations::TRANSFORMING_METHODS.each do |method_name|
+			side = Parsed::Operations::METHOD_SIDES[method_name]
+			bang_method_name = "#{method_name}!"
+			define_method(bang_method_name) do |string, *arguments, **keywords, &block|
+				mutate_string(string, side: side) do |parsed|
+					parsed.public_send(bang_method_name, *arguments, **keywords, &block)
+				end
+			end
+		end
+
+		alias at_start? start_with?
+		alias at_end? end_with?
+
+		private
+
+		# Static bang methods preserve normal String mutation behaviour and nil-on-no-change semantics.
+		def mutate_string(string, side: nil)
+			parsed = side ? Parsed.new(string, side: side) : Parsed.new(string)
+			yield(parsed)
+			unless string.is_a?(String)
+				raise TypeError, "no implicit conversion of #{string.class} into String"
+			end
+
+			value = parsed.result
+			return nil if string == value
+
+			string.replace(value)
+		end
+	end
+end

data/readme.md

@@ -0,0 +1,174 @@
+# Punctuated (Ruby Gem)
+
+A utility for detecting, adding and removing punctuation at the beginning or end of strings.
+
+Punctuation is composed of **terminals** and **wrappers**.
+
+* A **terminal** is a sentence-ending (or sometimes sentence-beginning) character like `.`, `?` and `!`. An example of a sentence-beginning terminal would be `¿`.
+* A **wrapper** is a character that can appear next to a terminal, and is considered part of the same sentence, like `"`, `'` or `)`.
+
+For instance, `("¿Dónde está?")` can be analysed as:
+
+| Start Wrapper | Start Terminal | Content | End Terminal | End Wrapper |
+| ---- | ---- | ---------- | ---- | ---- |
+| `("` | `¿`  | Dónde está | `?`  | `")` |
+
+Wrappers don't always appear outside terminals. Punctuated lets you detect, add, remove and move terminals and wrappers both inside and outside.
+
+Punctuated does not detect every occurrence of a terminal or wrapper -- only one consecutive series of them at either end of the string. The series can contain white space.
+
+Comprehensive [examples of input and output](/docs/spec/examples.md) are documented.
+
+
+## Detect punctuation
+
+Check for any terminal, or for a particular terminal sequence:
+
+```ruby
+Punctuated.at_end?("Ready?")                   #=> true
+Punctuated.at_end?("Ready?!", "!")             #=> true
+Punctuated.at_end?("Ready?!", "?")             #=> false
+Punctuated.at_start?("\u{BF}Ready?", "\u{BF}") #=> true
+```
+
+`at_start?` and `at_end?` are aliases for `start_with?` and `end_with?`.
+
+`start_with?` compares from the start of the captured terminal run; `end_with?` compares from its end. Whitespace within a terminal run is ignored when matching.
+
+Use `placement` to check for punctuation that's specifically inside or outside any wrapper:
+
+```ruby
+Punctuated.end_with?(%q{"Ready!"}, "!", placement: :inside) #=> true
+Punctuated.end_with?(%q{"Ready"!}, "!", placement: :outside) #=> true
+```
+
+
+## Ensure a string is punctuated
+
+`ensure` adds punctuation only when it is missing; it never replaces an existing terminal. By default it ensures a full stop at the end.
+
+```ruby
+Punctuated.ensure("Ready")                 #=> "Ready."
+Punctuated.ensure("Ready!")                #=> "Ready!"
+Punctuated.ensure(%q{"Ready"}, "!")        #=> "\"Ready!\""
+Punctuated.ensure_start("Ready", "\u{BF}") #=> "\u{BF}Ready"
+```
+
+Unlike other two-sided methods, a scalar or one-element array passed to `ensure` implicitly targets the end. Pass a two-element array to control the start and end explicitly:
+
+```ruby
+Punctuated.ensure("Ready", ["\u{BF}", "?"]) #=> "\u{BF}Ready?"
+```
+
+Missing punctuation is placed inside any wrapper by default. Existing punctuation is left in place unless `placement` is supplied. Placement values follow the same rules as terminal values: a scalar or one-element array implicitly targets the end, while a two-element array controls the start and end explicitly.
+
+
+## Remove punctuation and wrappers
+
+`strip` removes terminals from both ends by default. Wrappers are retained unless requested:
+
+```ruby
+Punctuated.strip(%q{"Ready!!?"})   #=> "\"Ready\""
+Punctuated.strip(%q{"Ready!!?"},
+  terminals: true, wrappers: true) #=> "Ready"
+Punctuated.lstrip("\u{BF})Ready?") #=> "Ready?"
+Punctuated.rstrip("\u{BF}Ready?")  #=> "\u{BF}Ready"
+```
+
+Use `:inside` or `:outside` instead of `true` to remove only components in that position. `strip` also accepts two-element arrays whose first value controls the start and second controls the end.
+
+
+## Replace punctuation and wrappers
+
+`replace` changes the captured runs. A single value applies to both ends; an array supplies start and end replacements:
+
+```ruby
+Punctuated.replace(%q{"Ready?!"}, terminals: [nil, "."]) #=> "\"Ready.\""
+Punctuated.replace(%q{"Ready!"}, wrappers: ["(", ")"])   #=> "(Ready!)"
+```
+
+Use an empty string to remove a run. A Proc can derive a replacement from the current raw run:
+
+```ruby
+Punctuated.replace("Ready ? !", terminals: ->(raw) { raw.delete(" ") }) #=> "Ready?!"
+```
+
+A replacement Hash uses `new` for its replacement text and can specify its position relative to a wrapper:
+
+```ruby
+Punctuated.replace(%q{"Ready!"}, terminals: [nil, {
+  new: ".",
+  placement: :outside,
+}]) #=> "\"Ready\"."
+```
+
+
+## Inspect and edit parsed punctuation
+
+`parse` returns a mutable representation when you need to inspect or make several changes:
+
+```ruby
+parsed = Punctuated.parse(%q{"Ready!"})
+
+parsed.original         #=> "\"Ready!\""
+parsed.content          #=> "Ready"
+parsed.terminals[1].raw #=> "!"
+parsed.wrappers[1].raw  #=> "\""
+
+parsed.terminals[1].raw = "."
+parsed.result           #=> "\"Ready.\""
+```
+
+`terminals` and `wrappers` contain the start and end components. Each component exposes `raw`, `chars`, `index` and `placement`. `content`, component `raw` values and component placements can be assigned directly; `result` recomposes the current string.
+
+`terminals` and `wrappers` always contain start and end components. Use `parse(str, side: :start)` or `side: :end` to inspect only one boundary; the uninspected boundary has empty terminal and wrapper components.
+
+
+## Mutating strings
+
+Every modifying method has a bang form, including `ensure!`, `strip!`, `replace!`, `lstrip!` and `rstrip!`:
+
+```ruby
+text = "Ready"
+Punctuated.ensure!(text) #=> "Ready."
+text                     #=> "Ready."
+Punctuated.ensure!(text) #=> nil
+```
+
+Module-level bang methods mutate the passed string and return `nil` when it was already correct. Bang methods on a parsed object mutate that object and return the object itself.
+
+Options and enum values accept equivalent strings or symbols. Unknown, duplicate or malformed options raise `ArgumentError`.
+
+
+## Versioning
+
+Punctuated follows semantic versioning. Until version 1.0, a minor version may contain breaking API changes; patch versions remain backwards compatible within their minor release.
+
+
+## Installation
+
+Punctuated supports Ruby 2.3 and later.
+
+```bash
+gem install punctuated
+```
+
+Or add it to your bundle:
+
+```ruby
+gem "punctuated", "~> 0.9.0"
+```
+
+Then load it with `require "punctuated"`.
+
+
+## Development
+
+Install dependencies and run the test suite:
+
+```bash
+bundle install
+bundle exec rake test
+```
+
+The examples in [`docs/spec/examples.md`](docs/spec/examples.md) are executable specifications and run as part of the suite. See [`docs/releasing.md`](docs/releasing.md) for the release procedure.

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: punctuated
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Convincible Media
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-08-16 00:00:00.000000000 Z
+dependencies: []
+description: A utility for detecting, adding and removing punctuation at the beginning
+  or end of strings. Punctuated detects a wide range of punctuation, and is aware
+  of a wide range of wrappers that may appear around punctuation.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- changelog.md
+- lib/punctuated.rb
+- lib/punctuated/component.rb
+- lib/punctuated/constants.rb
+- lib/punctuated/options.rb
+- lib/punctuated/parsed.rb
+- lib/punctuated/parsed/composition.rb
+- lib/punctuated/parsed/operations.rb
+- lib/punctuated/parsed/parsing.rb
+- lib/punctuated/version.rb
+- readme.md
+homepage: https://github.com/ConvincibleMedia/ruby-gem-punctuated
+licenses:
+- "'LGPL-3.0-or-later'"
+metadata:
+  bug_tracker_uri: https://github.com/ConvincibleMedia/ruby-gem-punctuated/issues
+  changelog_uri: https://github.com/ConvincibleMedia/ruby-gem-punctuated/blob/master/changelog.md
+  homepage_uri: https://github.com/ConvincibleMedia/ruby-gem-punctuated
+  source_code_uri: https://github.com/ConvincibleMedia/ruby-gem-punctuated/tree/v0.9.0
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.22
+signing_key: 
+specification_version: 4
+summary: Detect, add and remove sentence punctuation around string boundaries.
+test_files: []