releasehx 0.1.2 → 0.2.0

data/build/docs/sourcerer_readme.html

@@ -1,46 +0,0 @@
-<div class="paragraph">
-<p>This gem introduces a module called Sourcerer, by which AsciiDoc files can be parsed and their contents harvested for use in the application build.
-The module also handles Liquid template processing with enhanced attribute resolution capabilities.</p>
-</div>
-<div class="admonitionblock note">
-<table>
-<tr>
-<td class="icon">
-<div class="title">Note</div>
-</td>
-<td class="content">
-Sourcerer is intended to be spun off as its own gem once it successfully proves the concept in this gem.
-It will probably be called <em>AsciiSourcerer</em> and may replace an older and unmaintained utility of mine called LiquiDoc.
-</td>
-</tr>
-</table>
-</div>
-<div class="paragraph">
-<p>It is invoked in the Rakefile, establishing global namespaces:</p>
-</div>
-<div class="ulist">
-<ul>
-<li>
-<p><code>ReleaseHx::ATTRIBUTES[:globals]</code> (derived from this <code>README.adoc</code> file)</p>
-</li>
-<li>
-<p><code>ReleaseHx.read_built_snippet(:&lt;name&gt;)</code> (such as <code>:helpscreen</code>)</p>
-</li>
-</ul>
-</div>
-<div class="paragraph">
-<p>The Sourcerer module also generates files like <code>build/docs/manpage.adoc</code>, which generates the formatted terminal manual, using content from <code>build/docs/config-reference.adoc</code> and this README (<code>tags="cli_options"</code>, for instance).</p>
-</div>
-<div class="paragraph">
-<p>It also generates an AsciiDoc-formatted configuration reference, a machine-readable JSON reference, and a sample config using the <code>specs/data/config-def.yml</code> file.
-The Sourcerer system now supports <strong>attribute resolution</strong> from AsciiDoc source files, enabling templates to access README attributes during rendering, ensuring configuration documentation reflects actual default values.</p>
-</div>
-<div class="paragraph">
-<p>Sourcerer also performs basic testing of select commands in the ASciiDoc file that have been assigned a <code>testable</code> role.</p>
-</div>
-<div class="paragraph">
-<p>This is mostly just showing off what Sourcerer can do, and hopefully setting into habit some best practices for my more complicated apps.</p>
-</div>
-<div class="paragraph">
-<p>Sourcerer is also where integration with Jekyll&#8217;s extensions of Liquid occurs, bringing ReleaseHx&#8217;s templating powers closely in line with how Jekyll&#8217;s work, as described in <a href="#custom-liquid">[custom-liquid]</a>.</p>
-</div>

data/lib/schemagraphy/attribute_resolver.rb

@@ -1,48 +0,0 @@
-# frozen_string_literal: true
-
-module SchemaGraphy
-  # The AttributeResolver module provides methods for resolving AsciiDoc attribute references
-  # within a schema hash. It is used to substitute placeholders like `\{attribute_name}`
-  # with actual values.
-  module AttributeResolver
-    # Recursively walk a schema Hash and resolve `\{attribute_name}` references
-    # in 'dflt' values.
-    #
-    # @param schema [Hash] The schema or definition hash to process.
-    # @param attrs [Hash] The key-value pairs from AsciiDoc attributes to use for resolution.
-    # @return [Hash] The schema with resolved attributes.
-    def self.resolve_attributes! schema, attrs
-      case schema
-      when Hash
-        schema.transform_values! do |value|
-          if value.is_a?(Hash)
-            if value.key?('dflt') && value['dflt'].is_a?(String)
-              value['dflt'] = resolve_attribute_reference(value['dflt'], attrs)
-            end
-            resolve_attributes!(value, attrs)
-          else
-            value
-          end
-        end
-      end
-      schema
-    end
-
-    # Replace `\{attribute_name}` patterns with corresponding values from the attrs hash.
-    #
-    # @param value [String] The string to process.
-    # @param attrs [Hash] The attributes to use for resolution.
-    # @return [String] The processed string with attribute references replaced.
-    def self.resolve_attribute_reference value, attrs
-      # Handle \{attribute_name} references
-      if value.match?(/\{[^}]+\}/)
-        value.gsub(/\{([^}]+)\}/) do |match|
-          attr_name = ::Regexp.last_match(1)
-          attrs[attr_name] || match # Keep original if no matching attribute
-        end
-      else
-        value
-      end
-    end
-  end
-end

data/lib/schemagraphy/cfgyml/definition.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-require_relative '../loader'
-require_relative '../schema_utils'
-
-module SchemaGraphy
-  # A module for handling CFGYML, a schema-driven configuration system.
-  module CFGYML
-    # Represents a configuration definition loaded from a schema file.
-    # It provides methods for accessing defaults and rendering documentation.
-    class Definition
-      # @return [Hash] The loaded schema hash.
-      attr_reader :schema
-
-      # @return [Hash] The attributes used for resolving placeholders in the schema.
-      attr_reader :attributes
-
-      # @param schema_path [String] The path to the schema YAML file.
-      # @param attrs [Hash] A hash of attributes for placeholder resolution.
-      def initialize schema_path, attrs = {}
-        @schema = Loader.load_yaml_with_attributes(schema_path, attrs)
-        @attributes = attrs
-      end
-
-      # Extract default values from the loaded schema.
-      # @return [Hash] A hash of default values.
-      def defaults
-        SchemaUtils.crawl_defaults(@schema)
-      end
-
-      # Get the search paths for templates.
-      # @return [Array<String>] An array of template paths.
-      def template_paths
-        @template_paths ||= [
-          File.join(File.dirname(__FILE__), '..', 'templates', 'cfgyml'),
-          *additional_template_paths
-        ]
-      end
-
-      # Render a configuration reference or sample in the specified format.
-      #
-      # @param format [Symbol] The output format (`:adoc` or `:yaml`).
-      # @return [String] The rendered output.
-      # @raise [ArgumentError] if the format is unsupported.
-      def render_reference format = :adoc
-        template = case format
-                   when :adoc
-                     'config-reference.adoc.liquid'
-                   when :yaml
-                     'sample-config.yaml.liquid'
-                   else
-                     raise ArgumentError, "Unsupported format: #{format}"
-                   end
-
-        render_template(template)
-      end
-
-      private
-
-      # Render a template using the Liquid engine.
-      def render_template template_name
-        template_path = find_template(template_name)
-        raise "Template not found: #{template_name}" unless template_path
-
-        require 'liquid'
-        template_content = File.read(template_path)
-        template = Liquid::Template.parse(template_content)
-
-        template.render(
-          'config_def' => @schema,
-          'attrs' => @attributes)
-      end
-
-      # Find a template file in the configured template paths.
-      def find_template name
-        template_paths.each do |path|
-          file = File.join(path, name)
-          return file if File.exist?(file)
-        end
-        nil
-      end
-
-      # Provides an extension point for subclasses to add more template paths.
-      def additional_template_paths
-        # Can be overridden by subclasses
-        []
-      end
-    end
-  end
-end

data/lib/schemagraphy/cfgyml/doc_builder.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module SchemaGraphy
-  module CFGYML
-    # Builds documentation-friendly CFGYML references for machine consumption.
-    module DocBuilder
-      module_function
-
-      def call schema, options = {}
-        pretty = options.fetch(:pretty, true)
-        data = reference_hash(schema)
-        pretty ? JSON.pretty_generate(data) : JSON.generate(data)
-      end
-
-      def reference_hash schema
-        {
-          'format' => 'releasehx-config-reference',
-          'version' => 1,
-          'properties' => build_properties(schema['properties'], [])
-        }
-      end
-
-      def build_properties properties, path
-        return {} unless properties.is_a?(Hash)
-
-        properties.each_with_object({}) do |(key, definition), acc|
-          next unless definition.is_a?(Hash)
-
-          current_path = path + [key]
-          entry = build_entry(current_path, definition)
-          children = build_properties(definition['properties'], current_path)
-          entry['properties'] = children unless children.empty?
-          acc[key] = entry
-        end
-      end
-
-      def build_entry path, definition
-        entry = {
-          'path' => path.join('.'),
-          'desc' => definition['desc'],
-          'docs' => definition['docs'],
-          'type' => definition['type'],
-          'templating' => definition['templating'],
-          'default' => definition.key?('dflt') ? definition['dflt'] : nil
-        }
-        entry.compact
-      end
-    end
-  end
-end

data/lib/schemagraphy/cfgyml/path_reference.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-require 'json'
-
-module SchemaGraphy
-  module CFGYML
-    # Loads and queries a JSON config reference using JSON Pointer.
-    class PathReference
-      def initialize data
-        @data = data
-      end
-
-      def self.load path
-        new(JSON.parse(File.read(path)))
-      end
-
-      def get pointer
-        SchemaGraphy::DataQuery::JSONPointer.resolve(@data, pointer)
-      end
-    end
-
-    Reference = PathReference
-  end
-end

data/lib/schemagraphy/data_query/json_pointer.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module SchemaGraphy
-  module DataQuery
-    # Resolves JSON Pointer queries against a Hash or Array.
-    module JSONPointer
-      module_function
-
-      def resolve data, pointer
-        return data if pointer.nil? || pointer == ''
-        raise ArgumentError, "Invalid JSON Pointer: #{pointer}" unless pointer.start_with?('/')
-
-        tokens = pointer.split('/')[1..]
-        tokens.reduce(data) do |current, token|
-          key = unescape(token)
-          resolve_token(current, key, pointer)
-        end
-      end
-
-      def resolve_token current, key, pointer
-        case current
-        when Array
-          index = Integer(key, 10)
-          current.fetch(index)
-        when Hash
-          return current.fetch(key) if current.key?(key)
-          return current.fetch(key.to_sym) if current.key?(key.to_sym)
-
-          raise KeyError, "JSON Pointer not found: #{pointer}"
-        else
-          raise KeyError, "JSON Pointer not found: #{pointer}"
-        end
-      rescue ArgumentError, IndexError, KeyError
-        raise KeyError, "JSON Pointer not found: #{pointer}"
-      end
-
-      def unescape token
-        token.gsub('~1', '/').gsub('~0', '~')
-      end
-    end
-  end
-end

data/lib/schemagraphy/loader.rb

@@ -1,59 +0,0 @@
-# frozen_string_literal: true
-
-require 'yaml'
-require 'psych'
-require_relative 'attribute_resolver'
-
-module SchemaGraphy
-  # The Loader class provides methods for loading YAML files while preserving
-  # custom tags and resolving attribute references.
-  class Loader
-    # Load a YAML file and resolve AsciiDoc attribute references like `\{attribute_name}`.
-    #
-    # @param path [String] The path to the YAML file.
-    # @param attrs [Hash] The AsciiDoc attributes to use for resolution.
-    # @return [Hash] The loaded YAML data with attributes resolved.
-    def self.load_yaml_with_attributes path, attrs = {}
-      raw_data = load_yaml_with_tags(path)
-      AttributeResolver.resolve_attributes!(raw_data, attrs)
-      raw_data
-    end
-
-    # Load a YAML file, preserving any custom tags (e.g., `!foo`).
-    # Custom tags are attached to the data structure.
-    #
-    # @param path [String] The path to the YAML file.
-    # @return [Hash] The loaded YAML data with custom tags attached.
-    def self.load_yaml_with_tags path
-      return {} if File.empty?(path)
-
-      data = Psych.load_file(path, aliases: true, permitted_classes: [Date, Time])
-      ast  = Psych.parse_file(path)
-      attach_tags(ast.root, data)
-      data
-    end
-
-    # Recursively attach YAML tags to the loaded data structure for template processing.
-    #
-    # @param node [Psych::Nodes::Node] The current AST node.
-    # @param data [Object] The data corresponding to the current node.
-    # @api private
-    def self.attach_tags node, data
-      return unless node.is_a?(Psych::Nodes::Mapping)
-
-      node.children.each_slice(2) do |key_node, val_node|
-        key = key_node.value
-
-        if val_node.respond_to?(:tag) && val_node.tag && data[key].is_a?(String)
-          normalized_tag = val_node.tag.sub(/^!+/, '').sub(/^.*:/, '')
-          data[key] = {
-            'value' => data[key],
-            '__tag__' => normalized_tag
-          }
-        elsif data[key].is_a?(Hash)
-          attach_tags(val_node, data[key])
-        end
-      end
-    end
-  end
-end

data/lib/schemagraphy/regexp_utils.rb

@@ -1,235 +0,0 @@
-# frozen_string_literal: true
-
-require 'to_regexp'
-
-module SchemaGraphy
-  # A utility module for robustly parsing and using regular expressions.
-  # It handles various formats, including literals and plain strings,
-  # and provides helpers for extracting captured content.
-  module RegexpUtils
-    module_function
-
-    # Parse a regex pattern string using the `to_regexp` gem for robust parsing.
-    # Handles `/pattern/flags`, `%r{pattern}flags`, and plain text formats.
-    #
-    # @example
-    #   parse_pattern("/^hello.*$/im")
-    #   # => { pattern: "^hello.*$", flags: "im", regexp: /^hello.*$/im, options: 6 }
-    #
-    # @example
-    #   parse_pattern("hello world")
-    #   # => { pattern: "hello world", flags: "", regexp: /hello world/, options: 0 }
-    #
-    # @example
-    #   parse_pattern("hello world", "i")
-    #   # => { pattern: "hello world", flags: "i", regexp: /hello world/i, options: 1 }
-    #
-    # @param input [String] The input string, e.g., "/pattern/flags" or "plain pattern".
-    # @param default_flags [String] Default flags to apply if none are specified (default: "").
-    # @return [Hash, nil] A hash with `:pattern`, `:flags`, `:regexp`, and `:options`, or `nil`.
-    def parse_pattern input, default_flags = ''
-      return nil if input.nil? || input.to_s.strip.empty?
-
-      input_str = input.to_s.strip
-
-      # Remove surrounding quotes that might come from YAML parsing
-      clean_input = input_str.gsub(/^["']|["']$/, '')
-
-      # Manual parsing for /pattern/flags format (common in YAML configs)
-      if clean_input =~ %r{^/(.+)/([a-z]*)$}
-        pattern_str = Regexp.last_match(1)
-        flags_str = Regexp.last_match(2)
-        options = flags_to_options(flags_str)
-
-        begin
-          regexp_obj = Regexp.new(pattern_str, options)
-
-          return {
-            pattern: pattern_str,
-            flags: flags_str,
-            regexp: regexp_obj,
-            options: options
-          }
-        rescue RegexpError => e
-          raise RegexpError, "Invalid regex pattern '#{input}': #{e.message}"
-        end
-      end
-
-      # Heuristic to detect if it's a Regexp literal
-      is_literal = clean_input.start_with?('%r{')
-
-      if is_literal
-        # Try to parse as regex literal using to_regexp
-        begin
-          regexp_obj = clean_input.to_regexp(detect: true)
-
-          # Extract pattern and flags from the compiled regexp
-          pattern_str = regexp_obj.source
-          flags_str = extract_flags_from_regexp(regexp_obj)
-
-          {
-            pattern: pattern_str,
-            flags: flags_str,
-            regexp: regexp_obj,
-            options: regexp_obj.options
-          }
-        rescue RegexpError => e
-          # Malformed literal is an error
-          raise RegexpError, "Invalid regex literal '#{input}': #{e.message}"
-        end
-      else
-        # Treat as plain pattern string with default flags
-        flags_str = default_flags.to_s
-        options = flags_to_options(flags_str)
-
-        begin
-          regexp_obj = Regexp.new(clean_input, options)
-
-          {
-            pattern: clean_input,
-            flags: flags_str,
-            regexp: regexp_obj,
-            options: options
-          }
-        rescue RegexpError => e
-          raise RegexpError, "Invalid regex pattern '#{input}': #{e.message}"
-        end
-      end
-    end
-
-    # @note Not yet implemented.
-    # Future enhancement to parse structured pattern definitions from a Hash.
-    # @param pattern_hash [Hash] A hash with 'pattern' and 'flags' keys.
-    # @raise [NotImplementedError] Always raises this error.
-    def parse_structured_pattern pattern_hash
-      # TODO: Implement structured pattern parsing
-      # pattern_hash should have 'pattern' and 'flags' keys
-      # flags can be string or array
-      raise NotImplementedError, 'Structured pattern parsing not yet implemented'
-    end
-
-    # @note Not yet implemented.
-    # Future enhancement to parse custom YAML tags for regular expressions.
-    # @param tagged_input [String] The input string with a YAML tag.
-    # @param tag_type [Symbol] The type of tag, e.g., `:literal` or `:pattern`.
-    # @raise [NotImplementedError] Always raises this error.
-    def parse_tagged_pattern tagged_input, tag_type
-      # TODO: Implement custom YAML tag parsing
-      # tag_type would be :literal or :pattern
-      raise NotImplementedError, 'Tagged pattern parsing not yet implemented'
-    end
-
-    # Convert a flags string (ex: "im") to a Regexp options integer.
-    #
-    # @param flags [String] String containing regex flags.
-    # @return [Integer] Regexp options integer.
-    def flags_to_options flags
-      options = 0
-      flags = flags.to_s
-
-      options |= Regexp::IGNORECASE if flags.include?('i')
-      options |= Regexp::MULTILINE if flags.include?('m')
-      options |= Regexp::EXTENDED if flags.include?('x')
-
-      # NOTE: 'g' (global) and 'o' (once) are not standard Ruby flags
-      # encoding flags ('n', 'e', 's', 'u') are handled by to_regexp
-
-      options
-    end
-
-    # Extract a flags string from a compiled Regexp object.
-    #
-    # @param regexp [Regexp] A compiled regexp object.
-    # @return [String] String representation of the flags (e.g., "im").
-    def extract_flags_from_regexp regexp
-      flags = ''
-      flags += 'i' if regexp.options.anybits?(Regexp::IGNORECASE)
-      flags += 'm' if regexp.options.anybits?(Regexp::MULTILINE)
-      flags += 'x' if regexp.options.anybits?(Regexp::EXTENDED)
-      flags
-    end
-
-    # Create a Regexp object from a pattern string and explicit flags.
-    #
-    # @param pattern [String] The regex pattern (without delimiters).
-    # @param flags [String] The flags string (ex: "im").
-    # @return [Regexp] The compiled Regexp object.
-    def create_regexp pattern, flags = ''
-      options = flags_to_options(flags)
-      Regexp.new(pattern, options)
-    end
-
-    # Extract content using named or positional capture groups.
-    #
-    # @param text [String] The text to match against.
-    # @param pattern_info [Hash] The hash result from `parse_pattern`.
-    # @param capture_name [String] The name of the capture group to extract (optional).
-    # @return [String, nil] The extracted text, or `nil` if no match is found.
-    def extract_capture text, pattern_info, capture_name = nil
-      return nil unless text && pattern_info
-
-      regexp = pattern_info[:regexp]
-      match = text.match(regexp)
-
-      return nil unless match
-
-      if capture_name && match.names.include?(capture_name.to_s)
-        # Extract named capture group
-        match[capture_name.to_s]
-      elsif match.captures.any?
-        # Extract first capture group
-        match[1]
-      else
-        # Return the entire match
-        match[0]
-      end
-    end
-
-    # Extract all named capture groups as a hash or positional captures as an array.
-    #
-    # @param text [String] The text to match against.
-    # @param pattern_info [Hash] The hash result from `parse_pattern`.
-    # @return [Hash, Array, nil] A hash of named captures, an array of positional captures, or `nil`.
-    def extract_all_captures text, pattern_info
-      return nil unless text && pattern_info
-
-      regexp = pattern_info[:regexp]
-      match = text.match(regexp)
-
-      return nil unless match
-
-      if match.names.any?
-        # Return hash of named captures
-        match.names.each_with_object({}) do |name, captures|
-          captures[name] = match[name]
-        end
-      else
-        # Return array of positional captures
-        match.captures
-      end
-    end
-
-    # A convenience method that combines parsing and a single extraction.
-    #
-    # @param text [String] The text to match against.
-    # @param pattern_input [String] The pattern string (with or without /flags/).
-    # @param capture_name [String] Name of the capture group to extract (optional).
-    # @param default_flags [String] Default flags if the pattern has no flags.
-    # @return [String, nil] The extracted text, or `nil` if no match is found.
-    def parse_and_extract text, pattern_input, capture_name = nil, default_flags = ''
-      pattern_info = parse_pattern(pattern_input, default_flags)
-      extract_capture(text, pattern_info, capture_name)
-    end
-
-    # A convenience method that combines parsing and extraction of all captures.
-    #
-    # @param text [String] The text to match against.
-    # @param pattern_input [String] The pattern string (with or without /flags/).
-    # @param default_flags [String] Default flags if the pattern has no flags.
-    # @return [Hash, Array, nil] All captured content, or `nil` if no match is found.
-    def parse_and_extract_all text, pattern_input, default_flags = ''
-      pattern_info = parse_pattern(pattern_input, default_flags)
-      extract_all_captures(text, pattern_info)
-    end
-  end
-end