jekyll-relationships 0.1.0.alpha

data/lib/jekyll-relationships/support/data_path.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+module Relationships
+
+module Support
+
+# Reads and writes dot-separated frontmatter paths on plain nested hashes.
+#
+# This wrapper keeps all path mutation logic in one place so the rest of the
+# engine can stay focused on relationship behaviour rather than hash surgery.
+class DataPath
+	# Captures one concrete leaf reached by a dotted frontmatter path.
+	#
+	# Each match remembers the exact container and key so callers can update the
+	# original structure surgically without reshaping nearby hashes or arrays.
+	class Match
+		attr_reader :parent, :key, :value
+
+		# Builds one concrete leaf match.
+		def initialize(parent:, key:, value:)
+			@parent = parent
+			@key = key
+			@value = value
+		end
+
+		# Replaces the matched leaf in place.
+		def write(value)
+			@parent[@key] = value
+			@value = value
+		end
+	end
+
+	# Reports the raw value gathered from a path together with its concrete
+	# source leaves.
+	#
+	# `array_traversed?` distinguishes a simple hash path from one that expanded
+	# through array items and therefore cannot safely receive one consolidated
+	# write-back value.
+	class ReadResult
+		attr_reader :matches
+
+		# Builds one read result from the collected concrete matches.
+		def initialize(matches:, array_traversed:)
+			@matches = matches
+			@array_traversed = array_traversed
+		end
+
+		# Reassembles the public read value from the concrete matches.
+		def value
+			values = @matches.map(&:value)
+			return nil if values.empty?
+			return values.first if values.length == 1
+
+			values
+		end
+
+		# Returns true when the path resolved to at least one concrete leaf.
+		def present?
+			!@matches.empty?
+		end
+
+		# Returns true when path traversal expanded through an array.
+		def array_traversed?
+			@array_traversed
+		end
+	end
+
+	TraversalNode = Struct.new(:parent, :key, :value)
+
+	# Builds one reusable accessor.
+	def initialize
+		@reader = Jekyll::Plugins::Relationships::Support::FrontmatterPath.new
+	end
+
+	# Reads one value together with its concrete leaf matches.
+	def read_result(data, path)
+		return ReadResult.new(matches: [], array_traversed: false) if blank_path?(path)
+
+		matches, array_traversed = locate_matches(data, path)
+		ReadResult.new(matches: matches, array_traversed: array_traversed)
+	end
+
+	# Reads one value from a nested frontmatter hash.
+	def read(data, path)
+		read_result(data, path).value
+	end
+
+	# Writes one value to a nested frontmatter hash, creating hashes as needed.
+	#
+	# Existing non-hash ancestors are treated as errors so write-back never
+	# silently replaces arrays or scalar values with new hashes.
+	def write(data, path, value)
+		raise ArgumentError, 'Cannot write to a blank frontmatter path.' if blank_path?(path)
+
+		segments = Jekyll::Plugins::Relationships::Support::FrontmatterPath.split_path(path)
+		current_hash = data
+
+		segments[0..-2].each_with_index do |segment, segment_index|
+			next_hash = Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(current_hash, segment)
+			if next_hash.nil?
+				next_hash = {}
+				current_hash[segment] = next_hash
+			elsif !next_hash.is_a?(Hash)
+				failing_path = segments.first(segment_index + 1).join(@reader.separator.to_s)
+				raise ResolutionError, "Cannot write frontmatter path `#{path}` because `#{failing_path}` resolves to a #{next_hash.class}, not a hash."
+			end
+			current_hash = next_hash
+		end
+
+		current_hash[segments.last] = value
+	end
+
+	private
+
+	# Finds the concrete leaves currently matched by one path.
+	def locate_matches(data, path)
+		return [[], false] unless data.is_a?(Hash)
+
+		segments = Jekyll::Plugins::Relationships::Support::FrontmatterPath.split_path(path, @reader.separator)
+		return [[], false] if segments.empty?
+
+		nodes = [TraversalNode.new(nil, nil, data)]
+		array_traversed = false
+
+		segments.each_with_index do |_, segment_index|
+			requested_key_path = segments.first(segment_index + 1).join(@reader.separator.to_s)
+			next_nodes = []
+			last_segment = segment_index == segments.length - 1
+
+			nodes.each do |node|
+				if node.value.is_a?(Array)
+					array_traversed = true
+					next_nodes.concat(descend_array(node.value))
+					next
+				end
+				next unless node.value.is_a?(Hash)
+
+				resolved_key = Jekyll::Plugins::Relationships::Support::FrontmatterPath.resolve_hash_key(
+					node.value,
+					requested_key_path,
+					@reader.equivalent_lookup,
+					separator: @reader.separator
+				)
+				next if resolved_key.nil?
+
+				child_value = Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(node.value, resolved_key)
+				next if child_value.nil?
+
+				if child_value.is_a?(Array) && !last_segment
+					array_traversed = true
+					next_nodes.concat(descend_array(child_value))
+					next
+				end
+
+				next_nodes << TraversalNode.new(node.value, resolved_key, child_value)
+			end
+
+			nodes = next_nodes
+			break if nodes.empty?
+		end
+
+		[
+			nodes.map { |node| Match.new(parent: node.parent, key: node.key, value: node.value) },
+			array_traversed
+		]
+	end
+
+	# Applies the configured array-expansion rule while keeping exact indices.
+	def descend_array(array)
+		case @reader.arrays
+		when :first
+			return [] if array.empty?
+
+			[TraversalNode.new(array, 0, array.first)]
+		else
+			array.each_with_index.map do |entry, index|
+				TraversalNode.new(array, index, entry)
+			end
+		end
+	end
+
+	# Treats nil and empty strings as unset paths.
+	def blank_path?(path)
+		path.nil? || path.to_s.strip.empty?
+	end
+end
+
+end
+
+end
+end
+end

data/lib/jekyll-relationships/support/frontmatter_path.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+module Relationships
+
+module Support
+
+# Traverses frontmatter-style nested hashes using configurable path,
+# array, and equivalent-key rules.
+#
+# Use one instance per syntax configuration, then call `with` for scoped
+# variations such as template-level separator overrides.
+class FrontmatterPath
+
+	DEFAULT_SEPARATOR = '.'
+	DEFAULT_ARRAYS = :expand
+	UNSET = Object.new.freeze
+
+	attr_reader :separator, :arrays, :equivalent_lookup
+
+	# Splits one configured path into non-blank segments.
+	def self.split_path(path, separator = DEFAULT_SEPARATOR)
+		path.to_s.split(separator.to_s).map(&:strip).reject(&:empty?)
+	end
+
+	# Normalises equivalent-key definitions into a path-aware lookup table.
+	#
+	# Keys are stored against their full requested path so aliases can be
+	# scoped to one nested level only.
+	def self.build_equivalent_lookup(raw_equivalents, split_delimiter: StringArray::DEFAULT_DELIMITER)
+		return {} if raw_equivalents == false || raw_equivalents.nil?
+
+		string_array = Jekyll::Plugins::Relationships::Support::StringArray.new(delimiter: split_delimiter)
+		lookup = {}
+		groups = raw_equivalents.is_a?(Array) ? raw_equivalents : [raw_equivalents]
+
+		groups.each do |group|
+			keys = if group.is_a?(Array)
+								group.flat_map { |entry| string_array.interpret(entry, split: -1, flatten: true) }
+							else
+								string_array.interpret(group, split: -1, flatten: true)
+							end
+			keys = keys.map { |entry| entry.to_s.strip }.reject(&:empty?).uniq
+			next if keys.length < 2
+
+			keys.each { |key| lookup[key] = keys }
+		end
+
+		lookup
+	end
+
+	# Reads a hash entry using exact, string, or symbol lookup.
+	def self.read_hash(hash, key)
+		return hash[key] if hash.key?(key)
+
+		string_key = key.to_s
+		return hash[string_key] if hash.key?(string_key)
+
+		symbol_key = string_key.to_sym
+		return hash[symbol_key] if hash.key?(symbol_key)
+
+		nil
+	end
+
+	# Resolves the effective key present in one hash for the requested
+	# path-so-far.
+	def self.resolve_hash_key(hash, requested_key_path, equivalent_lookup, separator: DEFAULT_SEPARATOR)
+		string_key_path = requested_key_path.to_s.strip
+		return nil if string_key_path.empty?
+
+		group = equivalent_lookup[string_key_path] || [string_key_path]
+		candidate_segments = group.map { |candidate_path| split_path(candidate_path, separator).last }.reject(&:empty?).uniq
+
+		candidate_segments.reverse_each do |candidate|
+			return candidate if hash.key?(candidate)
+
+			symbol_candidate = candidate.to_sym
+			return symbol_candidate if hash.key?(symbol_candidate)
+		end
+
+		nil
+	end
+
+	# Builds a frontmatter-path helper for one default configuration.
+	def initialize(separator: DEFAULT_SEPARATOR, arrays: DEFAULT_ARRAYS, equivalents: nil, equivalent_lookup: UNSET)
+		@separator = normalise_separator(separator)
+		@arrays = normalise_array_mode(arrays)
+		@equivalent_lookup = equivalent_lookup.equal?(UNSET) ? self.class.build_equivalent_lookup(equivalents) : normalise_equivalent_lookup(equivalent_lookup)
+	end
+
+	# Builds a clone with selected configuration overrides.
+	def with(separator: UNSET, arrays: UNSET, equivalents: UNSET, equivalent_lookup: UNSET)
+		resolved_separator = separator.equal?(UNSET) ? @separator : separator
+		resolved_arrays = arrays.equal?(UNSET) ? @arrays : arrays
+
+		if !equivalent_lookup.equal?(UNSET)
+			return self.class.new(
+				separator: resolved_separator,
+				arrays: resolved_arrays,
+				equivalent_lookup: equivalent_lookup
+			)
+		end
+
+		if !equivalents.equal?(UNSET)
+			return self.class.new(
+				separator: resolved_separator,
+				arrays: resolved_arrays,
+				equivalents: equivalents
+			)
+		end
+
+		self.class.new(
+			separator: resolved_separator,
+			arrays: resolved_arrays,
+			equivalent_lookup: @equivalent_lookup
+		)
+	end
+
+	# Traverses one data structure and returns:
+	# - `nil` when the path is missing
+	# - one raw terminal value when one match is found
+	# - an array of raw terminal values when many matches are found
+	def traverse(data, path, separator: UNSET, arrays: UNSET, equivalents: UNSET, equivalent_lookup: UNSET)
+		active_separator = separator.equal?(UNSET) ? @separator : normalise_separator(separator)
+		active_arrays = arrays.equal?(UNSET) ? @arrays : normalise_array_mode(arrays)
+		active_lookup = resolve_lookup(equivalents, equivalent_lookup)
+
+		traverse_internal(data, path, separator: active_separator, arrays: active_arrays, equivalent_lookup: active_lookup)
+	end
+
+	private
+
+	# Walks the object graph using the effective traversal configuration.
+	def traverse_internal(data, path, separator:, arrays:, equivalent_lookup:)
+		return nil unless data.is_a?(Hash)
+
+		segments = self.class.split_path(path, separator)
+		return nil if segments.empty?
+
+		nodes = [data]
+		segments.each_with_index do |_, segment_index|
+			next_nodes = []
+			requested_key_path = segments.first(segment_index + 1).join(separator.to_s)
+
+			nodes.each do |node|
+				if node.is_a?(Array)
+					next_nodes.concat(descend_array(node, arrays))
+					next
+				end
+				next unless node.is_a?(Hash)
+
+				resolved_key = self.class.resolve_hash_key(node, requested_key_path, equivalent_lookup, separator: separator)
+				next if resolved_key.nil?
+
+				next_nodes << self.class.read_hash(node, resolved_key)
+			end
+
+			nodes = if segment_index == segments.length - 1
+								next_nodes.compact
+							else
+								next_nodes.flatten(1).compact
+							end
+			break if nodes.empty?
+		end
+
+		return nil if nodes.empty?
+		return nodes.first if nodes.length == 1
+
+		nodes
+	end
+
+	# Applies the configured array traversal mode to one intermediate array.
+	def descend_array(array, arrays)
+		case arrays
+		when :first
+			array.empty? ? [] : [array.first]
+		else
+			array
+		end
+	end
+
+	# Normalises one separator override.
+	def normalise_separator(raw_separator)
+		separator = raw_separator.to_s
+		separator.empty? ? DEFAULT_SEPARATOR : separator
+	end
+
+	# Normalises one configured array traversal mode.
+	def normalise_array_mode(raw_arrays)
+		mode = raw_arrays.to_s.strip.downcase
+		mode = DEFAULT_ARRAYS.to_s if mode.empty?
+
+		return :expand if %w[expand all].include?(mode)
+		return :first if mode == 'first'
+
+		raise ArgumentError, "Unsupported array traversal mode '#{raw_arrays}'."
+	end
+
+	# Accepts only hash lookups for prebuilt equivalent-key data.
+	def normalise_equivalent_lookup(raw_lookup)
+		raw_lookup.is_a?(Hash) ? raw_lookup : {}
+	end
+
+	# Resolves one optional lookup override against the instance default.
+	def resolve_lookup(raw_equivalents, raw_equivalent_lookup)
+		return normalise_equivalent_lookup(raw_equivalent_lookup) unless raw_equivalent_lookup.equal?(UNSET)
+		return self.class.build_equivalent_lookup(raw_equivalents) unless raw_equivalents.equal?(UNSET)
+
+		@equivalent_lookup
+	end
+end
+
+end
+end
+end
+end

data/lib/jekyll-relationships/support/hash_deep_merge.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+module Relationships
+
+module Support
+	module_function
+
+	# Deep-merges two hashes without mutating either input.
+	#
+	# Values from `right_hash` win over values from `left_hash`. Nested hashes are
+	# merged recursively, while all other values are treated as leaf replacements.
+	def hash_deep_merge(left_hash, right_hash)
+		left = stringify_hash(left_hash)
+		right = stringify_hash(right_hash)
+
+		left.each_with_object({}) do |(key, value), merged|
+			right_value = fetch_hash_value(right, key)
+
+			merged[key] = if value.is_a?(Hash) && right_value.is_a?(Hash)
+									hash_deep_merge(value, right_value)
+								elsif hash_key?(right, key)
+									right_value
+								else
+									value
+								end
+		end.tap do |merged|
+			right.each do |key, value|
+				next if merged.key?(key)
+
+				merged[key] = value
+			end
+		end
+	end
+
+	# Returns true when a string- or symbol-keyed hash contains the given key.
+	def hash_key?(hash, key)
+		return false unless hash.is_a?(Hash)
+
+		hash.key?(key) || hash.key?(key.to_s) || hash.key?(key.to_sym)
+	end
+
+	# Reads one value from a string- or symbol-keyed hash.
+	def fetch_hash_value(hash, key)
+		return nil unless hash.is_a?(Hash)
+
+		Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(hash, key)
+	end
+
+	# Returns one shallow string-keyed copy of a hash.
+	def stringify_hash(hash)
+		return {} unless hash.is_a?(Hash)
+
+		hash.each_with_object({}) do |(key, value), stringified|
+			stringified[key.to_s] = value
+		end
+	end
+
+end
+end
+end
+end

data/lib/jekyll-relationships/support/placeholders.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+module Relationships
+
+module Support
+
+	# Stores the literal placeholder tokens used in relationship configuration.
+	module Placeholders
+		KEY = '<key>'.freeze
+		COLLECTION = '<collection>'.freeze
+		PAGE = '<page>'.freeze
+		COUNT = '<count>'.freeze
+	end
+
+end
+
+end
+end
+end

data/lib/jekyll-relationships/support/string_array.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+module Relationships
+
+module Support
+
+# Interprets loose config/frontmatter values as arrays.
+#
+# Use one instance per delimiter configuration, then call `with` to derive
+# a nearby variant without restating the full configuration.
+class StringArray
+
+	DEFAULT_DELIMITER = ','
+	UNSET = Object.new.freeze
+
+	attr_reader :delimiter
+
+	# Builds a string-array helper for one default delimiter.
+	def initialize(delimiter: DEFAULT_DELIMITER)
+		@delimiter = self.class.normalise_delimiter(delimiter, DEFAULT_DELIMITER)
+	end
+
+	# Builds a clone with selected configuration overrides.
+	def with(delimiter: UNSET)
+		self.class.new(
+			delimiter: delimiter.equal?(UNSET) ? @delimiter : delimiter
+		)
+	end
+
+	# Normalises one configured delimiter.
+	#
+	# Blank or unsupported values fall back to `default_delimiter`.
+	# `false` disables string splitting.
+	def self.normalise_delimiter(raw_delimiter, default_delimiter = DEFAULT_DELIMITER)
+		return false if raw_delimiter == false
+		return default_delimiter unless raw_delimiter.is_a?(String)
+
+		delimiter = raw_delimiter
+		return false if delimiter.strip.downcase == 'false'
+
+		delimiter.empty? ? default_delimiter : delimiter
+	end
+
+	# Interprets a scalar or array as an array with configurable string
+	# splitting depth.
+	#
+	# `split` modes:
+	# - `true` / `0`: split only a top-level string
+	# - `false`: never split strings, only wrap
+	# - positive integer: split strings found at that array depth
+	# - `-1`: split strings at any depth
+	#
+	# `flatten: true` promotes split values into the surrounding array.
+	# `flatten: false` keeps split values nested at the point they arose.
+	def interpret(value, split: true, flatten: false, delimiter: UNSET)
+		active_delimiter = effective_delimiter(delimiter)
+		active_split_depth = normalise_split_depth(split)
+		interpret_value(value, split_depth: active_split_depth, flatten: !!flatten, current_level: 0, delimiter: active_delimiter)
+	end
+
+	private
+
+	# Interprets one value at one traversal depth.
+	def interpret_value(value, split_depth:, flatten:, current_level:, delimiter:)
+		return [] if value.nil?
+		return interpret_array(value, split_depth: split_depth, flatten: flatten, current_level: current_level, delimiter: delimiter) if value.is_a?(Array)
+		return interpret_string(value, split_depth: split_depth, current_level: current_level, delimiter: delimiter) if value.is_a?(String)
+
+		[value]
+	end
+
+	# Interprets one array and recursively flattens nested array structure
+	# while respecting string-splitting depth.
+	def interpret_array(array, split_depth:, flatten:, current_level:, delimiter:)
+		array.flatten(1).compact.each_with_object([]) do |entry, interpreted|
+			if entry.is_a?(Array)
+				interpreted.concat(
+					interpret_array(
+						entry,
+						split_depth: split_depth,
+						flatten: flatten,
+						current_level: current_level + 1,
+						delimiter: delimiter
+					)
+				)
+				next
+			end
+
+			if entry.is_a?(String)
+				string_value = interpret_string(entry, split_depth: split_depth, current_level: current_level + 1, delimiter: delimiter)
+				if should_split_string?(split_depth, current_level + 1) && !flatten && string_value.length > 1
+					interpreted << string_value
+				else
+					interpreted.concat(string_value)
+				end
+				next
+			end
+
+			interpreted << entry
+		end
+	end
+
+	# Interprets one string according to the configured split depth.
+	def interpret_string(value, split_depth:, current_level:, delimiter:)
+		return [value] unless should_split_string?(split_depth, current_level)
+
+		split_string(value, delimiter)
+	end
+
+	# Splits one string with the active delimiter, trimming and discarding
+	# blank entries.
+	def split_string(value, delimiter)
+		if delimiter == false
+			entry = value.to_s.strip
+			return [] if entry.empty?
+
+			return [entry]
+		end
+
+		split_pattern = Regexp.new(Regexp.escape(delimiter.to_s))
+		value.to_s.split(split_pattern, -1).map(&:strip).reject(&:empty?)
+	end
+
+	# Resolves whether strings should be split at the current array depth.
+	def should_split_string?(split_depth, current_level)
+		return false if split_depth == false
+		return true if split_depth == -1
+
+		current_level == split_depth
+	end
+
+	# Normalises the configured split depth.
+	def normalise_split_depth(raw_split)
+		return false if raw_split == false
+		return 0 if raw_split == true
+		return raw_split if raw_split.is_a?(Integer)
+
+		return raw_split.to_i if raw_split.is_a?(String) && raw_split.strip.match?(/\A-?\d+\z/)
+
+		raise ArgumentError, "Unsupported string-array split depth '#{raw_split}'."
+	end
+
+	# Resolves one optional delimiter override against the instance
+	# default.
+	def effective_delimiter(raw_override)
+		return @delimiter if raw_override.equal?(UNSET)
+
+		self.class.normalise_delimiter(raw_override, @delimiter)
+	end
+end
+
+end
+end
+end
+end