jekyll-relationships 0.1.0.alpha

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9656850968f173e997fe9e9a0b5500f12682c94d613f84444827bc5e52aa955a
+  data.tar.gz: e56a5ec1a9a44b58d2aa03e2066e99f7a4b39df1335c449e5325f6a5599b6871
+SHA512:
+  metadata.gz: 010f090f1083c9f8ede2f8a99bd23e05a68b474f6c90b1519a4002c2446bf97eee6256b8cb7858cbd9a7e9aa9def901885fed07290e8a83c995656f71e47afd4
+  data.tar.gz: 1f0c0c85af8fd938f7d6d66a15e4dfb2941615057656867702a01b146e10426901969a2498e10d9fe08427d2226fe9d0f3968e50e262560223fff439ebfcda0f

data/lib/jekyll-relationships/configuration/debug_setting.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Normalises the `debug` config into one explicit set of enabled log areas.
+	#
+	# Supported areas:
+	# * `resolution`: relationship-resolution start and finish
+	# * `upgrading`: raw reference reading, resolution, and write-back
+	# * `mutations`: link and unlink operations
+	# * `resolvers`: resolver execution and helper calls
+	# * `trees`: tree discovery, edge handling, and tree write-back
+	class DebugSetting
+		AREAS = {
+			'resolution' => 'relationship-resolution lifecycle',
+			'upgrading' => 'reference upgrading and write-back',
+			'mutations' => 'link and unlink operations',
+			'resolvers' => 'resolver execution and helper calls',
+			'trees' => 'tree discovery, edge handling, and tree write-back'
+		}.freeze
+
+		ALL_AREAS = AREAS.keys.freeze
+
+		class << self
+			# Builds one explicit debug setting from a loose config value.
+			def build(value:, string_array:, context:)
+				return disabled if value.nil? || false_value?(value)
+				return all if true_value?(value)
+
+				raw_areas = string_array.interpret(value, split: true, flatten: true)
+				raise_invalid_value!(context: context) if raw_areas.empty?
+
+				areas = raw_areas.each_with_object([]) do |raw_area, interpreted_areas|
+					normalised_area = normalise_area(raw_area, context: context)
+					return all if normalised_area == 'all'
+
+					interpreted_areas << normalised_area
+				end
+
+				new(areas.uniq)
+			end
+
+			# Returns one disabled debug setting.
+			def disabled
+				new([])
+			end
+
+			# Returns one debug setting that enables every area.
+			def all
+				new(ALL_AREAS)
+			end
+
+			private
+
+			# Returns true when a loose value means "debug everything".
+			def true_value?(value)
+				value == true || value.to_s.strip.casecmp('true').zero?
+			end
+
+			# Returns true when a loose value means "debug nothing".
+			def false_value?(value)
+				value == false || value.to_s.strip.casecmp('false').zero?
+			end
+
+			# Normalises one configured area name and validates it.
+			def normalise_area(raw_area, context:)
+				area = raw_area.to_s.strip.downcase
+				raise_invalid_value!(context: context) if area.empty?
+				return 'all' if area == 'all'
+				return area if AREAS.key?(area)
+
+				raise ConfigurationError,
+					"`#{context}` contains unknown debug area `#{raw_area}`. Supported areas: #{ALL_AREAS.join(', ')}."
+			end
+
+			# Raises one shared error for invalid debug values.
+			def raise_invalid_value!(context:)
+				raise ConfigurationError,
+					"`#{context}` must be true, false, `all`, or a comma-delimited string/array of debug areas: #{ALL_AREAS.join(', ')}."
+			end
+		end
+
+		attr_reader :areas
+
+		# Captures one immutable set of enabled debug areas.
+		def initialize(areas)
+			@areas = areas.freeze
+		end
+
+		# Returns true when any debug area is enabled, or when one named area is enabled.
+		def enabled?(area = nil)
+			return !@areas.empty? if area.nil?
+
+			@areas.include?(normalise_runtime_area(area))
+		end
+
+		private
+
+		# Normalises one runtime area name and raises on internal typos.
+		def normalise_runtime_area(area)
+			string_area = area.to_s.strip.downcase
+			return string_area if self.class::ALL_AREAS.include?(string_area)
+
+			raise ArgumentError, "Unknown runtime debug area `#{area}`."
+		end
+	end
+end
+
+end
+
+end
+end

data/lib/jekyll-relationships/configuration/defaults.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Holds the built-in configuration defaults used when the site omits them.
+	module Defaults
+		ENABLED = true
+		DEBUG = false
+
+		FRONTMATTER = {
+			'base' => 'relationships',
+			'primary' => nil,
+			'foreign' => '<collection>',
+			'output' => nil
+		}.freeze
+
+		TREE = {
+			'frontmatter' => {
+				'parent' => 'parent',
+				'child' => 'child',
+				'parents' => 'parents',
+				'children' => 'children',
+				'ancestors' => 'ancestors',
+				'descendants' => 'descendants'
+			}.freeze,
+			'max' => {
+				'parents' => -1,
+				'children' => -1
+			}.freeze,
+			'url' => false
+		}.freeze
+
+		MULTIPLE = {
+			'mode' => 'drop',
+			'sort' => nil
+		}.freeze
+
+		KEYWORDS = {
+			'self' => 'self',
+			'others' => 'others',
+			'all' => 'all'
+		}.freeze
+	end
+end
+
+end
+
+end
+end

data/lib/jekyll-relationships/configuration/frontmatter.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Encapsulates one merged frontmatter configuration block.
+	#
+	# Instances resolve `base`, `primary`, `foreign`, and `output` paths so the
+	# rest of the engine can work with explicit values only.
+	class Frontmatter
+		# Builds one frontmatter configuration helper.
+		def initialize(raw_config:, string_array:)
+			@raw_config = raw_config.is_a?(Hash) ? raw_config : {}
+			@string_array = string_array
+		end
+
+		# Returns the configured base path.
+		def base
+			raw_base = fetch_value('base')
+			return '' if raw_base.nil?
+
+			raw_base.to_s
+		end
+
+		# Returns the resolved primary-key path, or nil for the default key rule.
+		def primary_path
+			raw_primary = fetch_value('primary')
+			return nil if raw_primary.nil?
+
+			apply_base(raw_primary.to_s)
+		end
+
+		# Returns the resolved foreign input paths for one target collection.
+		def foreign_paths_for(to_collection:)
+			raw_foreign = fetch_value('foreign')
+			paths = @string_array.interpret(raw_foreign, split: true, flatten: true)
+			raise ConfigurationError, 'Each normal relationship must define at least one foreign path.' if paths.empty?
+
+			paths.map do |path|
+				string_path = path.to_s.strip
+				raise ConfigurationError, 'Foreign paths cannot be blank.' if string_path.empty?
+
+				resolve_collection_path(path: string_path, to_collection: to_collection)
+			end.uniq
+		end
+
+		# Returns the resolved output path, if one is configured.
+		def output_path_for(to_collection:)
+			raw_output = fetch_value('output')
+			return nil if raw_output.nil? || raw_output.to_s.strip.empty?
+
+			resolve_collection_path(path: raw_output.to_s.strip, to_collection: to_collection)
+		end
+
+		# Returns one arbitrary path with the active base applied.
+		def path_with_base(path)
+			apply_base(path.to_s)
+		end
+
+		# Returns a cloned frontmatter configuration with one override merged in.
+		def merge(raw_override)
+			self.class.new(
+				raw_config: Configuration::HashUtilities.merge_hash(@raw_config, raw_override),
+				string_array: @string_array
+			)
+		end
+
+		private
+
+		# Reads one configured property from the raw hash.
+		def fetch_value(key)
+			Configuration::HashUtilities.fetch_hash_value(@raw_config, key)
+		end
+
+		# Applies the active base path to one relative path.
+		def apply_base(path)
+			return path if base.empty?
+			return base if path.to_s.empty?
+
+			"#{base}.#{path}"
+		end
+
+		# Resolves one path that may include the active collection placeholder.
+		def resolve_collection_path(path:, to_collection:)
+			apply_base(path.gsub(collection_placeholder, to_collection))
+		end
+
+		# Returns the active `<collection>` placeholder token.
+		def collection_placeholder
+			Jekyll::Plugins::Relationships::Support::Placeholders::COLLECTION
+		end
+	end
+end
+
+end
+
+end
+end

data/lib/jekyll-relationships/configuration/hash_utilities.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Provides shared hash-reading helpers for configuration components.
+	module HashUtilities
+		module_function
+
+		# Returns true when a string- or symbol-keyed hash includes one 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 string- or symbol-keyed hash value.
+		def fetch_hash_value(hash, key)
+			return nil unless hash.is_a?(Hash)
+
+			Jekyll::Plugins::Relationships::Support::FrontmatterPath.read_hash(hash, key)
+		end
+
+		# Deep-merges two hashes without mutating either.
+		def merge_hash(base_hash, override_hash)
+			Jekyll::Plugins::Relationships::Support.hash_deep_merge(base_hash, override_hash)
+		end
+
+		# Converts one config value to an integer with a helpful error.
+		def integer_value(value, context)
+			return value if value.is_a?(Integer)
+			return value.to_i if value.is_a?(String) && value.strip.match?(/\A-?\d+\z/)
+
+			raise ConfigurationError, "`#{context}` must be an integer."
+		end
+
+		# Converts one config value to a boolean with a helpful error.
+		def boolean_value(value, context)
+			return value if value == true || value == false
+			return true if value.is_a?(String) && value.strip.casecmp('true').zero?
+			return false if value.is_a?(String) && value.strip.casecmp('false').zero?
+
+			raise ConfigurationError, "`#{context}` must be true or false."
+		end
+	end
+end
+
+end
+
+end
+end

data/lib/jekyll-relationships/configuration/multiple_settings.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Jekyll
+module Plugins
+
+module Relationships
+
+class Configuration
+
+	# Encapsulates the configured handling for duplicate normal relationships.
+	#
+	# The selected mode determines whether duplicates are counted, dropped, or
+	# preserved, while the optional sort controls the final output order in count
+	# mode only.
+	class MultipleSettings
+		attr_reader :mode, :sort
+
+		# Builds one multiple-settings helper from raw configuration.
+		def initialize(raw_config:)
+			config = normalise_config(raw_config)
+			@mode = normalise_mode(config['mode'])
+			@sort = normalise_sort(config['sort'])
+			validate!
+		end
+
+		# Returns true when duplicate links should aggregate into counts.
+		def count?
+			@mode == 'count'
+		end
+
+		# Returns true when duplicate links should be dropped.
+		def drop?
+			@mode == 'drop'
+		end
+
+		# Returns true when duplicate links should be preserved individually.
+		def keep?
+			@mode == 'keep'
+		end
+
+		# Returns true when counted output should be sorted in ascending order.
+		def sort_ascending?
+			@sort == 'asc'
+		end
+
+		# Returns true when counted output should be sorted in descending order.
+		def sort_descending?
+			@sort == 'desc'
+		end
+
+		private
+
+		# Converts the loose raw value into a normalised hash.
+		def normalise_config(raw_config)
+			case raw_config
+			when nil
+				Defaults::MULTIPLE
+			when String, Symbol
+				{ 'mode' => raw_config.to_s }
+			when Hash
+				Configuration::HashUtilities.merge_hash(Defaults::MULTIPLE, raw_config)
+			else
+				raise ConfigurationError, '`relationships.multiple` must be a string or hash.'
+			end
+		end
+
+		# Resolves one configured duplicate-handling mode.
+		def normalise_mode(raw_mode)
+			string_mode = raw_mode.to_s.strip.downcase
+			string_mode = Defaults::MULTIPLE.fetch('mode') if string_mode.empty?
+
+			return string_mode if %w[count drop keep].include?(string_mode)
+
+			raise ConfigurationError, "Unsupported relationships.multiple mode `#{raw_mode}`."
+		end
+
+		# Resolves one configured count-sort direction.
+		def normalise_sort(raw_sort)
+			return nil if raw_sort.nil?
+
+			string_sort = raw_sort.to_s.strip.downcase
+			return nil if string_sort.empty?
+			return 'asc' if %w[asc ascending].include?(string_sort)
+			return 'desc' if %w[desc descending].include?(string_sort)
+
+			raise ConfigurationError, "Unsupported relationships.multiple.sort value `#{raw_sort}`."
+		end
+
+		# Raises for mode combinations that are not meaningful.
+		def validate!
+			return if @sort.nil? || count?
+
+			raise ConfigurationError, '`relationships.multiple.sort` is only supported when `relationships.multiple` is `count`.'
+		end
+	end
+end
+
+end
+
+end
+end