ceedling 1.0.1 → 1.1.0

data/lib/ceedling/includes/includes.rb

@@ -0,0 +1,341 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+class Includes
+  # Class method to convert mixed list of Include objects into an order-preserving list of hashes
+  #
+  # @param includes [Array<Include>] List of UserInclude and SystemInclude objects
+  # @return [Array<Hash>] Array of hashes, each with 'type' and 'filepath' keys
+  # @example
+  #   includes = [
+  #     UserInclude.new("header.h"),
+  #     SystemInclude.new("stdio.h"),
+  #     UserInclude.new("module.h")
+  #   ]
+  #   Include.to_hash(includes)
+  #   # => [
+  #   #   { 'type' => 'user', 'filepath' => 'header.h' },
+  #   #   { 'type' => 'system', 'filepath' => 'stdio.h' },
+  #   #   { 'type' => 'user', 'filepath' => 'module.h' }
+  #   # ]
+  def self.to_hashes(includes)
+    return includes.map do |include|
+      type = 
+        case include
+        when MockInclude then 'mock'
+        when UserInclude then 'user'
+        when SystemInclude then 'system'
+        else raise ArgumentError, "Unknown Include type: #{include.class}"
+        end
+
+      {
+        'type' => type,
+        'filepath' => include.filepath,
+      }
+    end
+  end
+
+  # Class method to convert a list of hashes back into Include objects
+  #
+  # @param hashes [Array<Hash>] Array of hashes with 'type' and 'filepath' keys
+  # @return [Array<Include>] List of UserInclude and SystemInclude objects
+  # @raise [ArgumentError] If hash is missing required keys or has invalid type
+  # @example
+  #   hashes = [
+  #     { 'type' => 'user', 'filepath' => 'header.h' },
+  #     { 'type' => 'system', 'filepath' => 'stdio.h' },
+  #     { 'type' => 'user', 'filepath' => 'module.h' }
+  #   ]
+  #   Include.from_hashes(hashes)
+  #   # => [
+  #   #   UserInclude.new("header.h"),
+  #   #   SystemInclude.new("stdio.h"),
+  #   #   UserInclude.new("module.h")
+  #   # ]
+  def self.from_hashes(hashes)
+    return hashes.map do |hash|
+      raise ArgumentError, "Hash missing 'type' key" unless hash.key?('type')
+      raise ArgumentError, "Hash missing 'filepath' key" unless hash.key?('filepath')
+      
+      case hash['type']
+      when 'user'
+        UserInclude.new(hash['filepath'])
+      when 'mock'
+        MockInclude.new(hash['filepath'])
+      when 'system'
+        SystemInclude.new(hash['filepath'])
+      else
+        raise ArgumentError, "Invalid include type: #{hash['type']}. Must be 'user' or 'system'"
+      end
+    end
+  end
+
+  # Class method to extract all matching includes by filename pattern
+  def self.filter(includes, pattern)
+    includes.select { |include| include.filename =~ pattern }
+  end
+
+  # Class method to extract all system includes
+  def self.system(includes)
+    includes.select { |include| include.is_a?(SystemInclude) }
+  end
+
+  # Class method to extract all user includes
+  def self.user(includes)
+    includes.select { |include| include.is_a?(UserInclude) }
+  end
+
+  # Class method to check for a filename in the collection
+  def self.contains?(includes, filename)
+    includes.any? { |include| include.filename == filename }
+  end
+
+  # Class method for non-mutating sanitize
+  #
+  # @param includes [Array<Include>] List of includes to sanitize
+  # @param block [Proc] Optional block passed to reject! for custom filtering
+  # @yield [include] Each include object for custom rejection logic
+  # @return [Array<Include>] New sanitized list
+  # @example Basic usage
+  #   Includes.sanitize(includes)
+  # @example Custom rejection
+  #   Includes.sanitize(includes) { |include, all| ... }
+  def self.sanitize(includes, &block)
+    _includes = includes.clone
+    self.sanitize!(_includes, &block)
+    return _includes
+  end
+
+  # Class method for mutating sanitize
+  #
+  # @param includes [Array<Include>] List of includes to sanitize in place
+  # @param block [Proc] Optional block passed to reject! for custom filtering
+  # @yield [include] Each include object for custom rejection logic
+  # @return [Array<Include>] The modified includes list
+  # @example Basic usage
+  #   Includes.sanitize!(includes)
+  # @example Custom rejection
+  #   Includes.sanitize!(includes) { |include, all| ... }
+  def self.sanitize!(includes, &block)
+    # Remove any duplicates
+    includes.uniq!
+
+    # Apply custom rejection with access to full list if block provided
+    if block_given?
+      includes.reject! { |include| block.call(include, includes) }
+    end
+
+    # Ensure system includes come first
+    self.sort!(includes)
+
+    return includes
+  end
+
+  # Class method to reconcile bare, user, and system includes returning a list of
+  # reconciled user and system includes.
+  #
+  # Purpose
+  # -------
+  # Bare include preprocessing extracts user and system includes, but there's no way
+  # to explicitly differentiate these. Meanwhile, by necessity, user and system include 
+  # extraction can identify too many includes. This class method uses the knowledeg of
+  # the different types of extraction to reconcile the two lists. It accomplishes:
+  #  1. Paring down system includes to the include directives used in original file.
+  #  2. Paring down user includes to the include directives used in original file.
+  #  3. Reconciling a list of user & system includes properly distinguished.
+  #
+  # Method
+  # ------
+  # Compares bare includes against user and system includes and applies the following rules:
+  # 1. Intersection of bare includes and system includes.
+  # 2. Intersection of bare includes and user includes.
+  def self.reconcile(bare:, user:, system:)
+    # Validate input types
+
+    # `bare` can only be base Include objects, no sub-classes.
+    unless bare.is_a?(Array) && bare.all? { |include| include.class == Include }
+      raise ArgumentError, "`bare` must be an Array of Include objects"
+    end
+
+    # Ensure `user` is an array of UserInclude objects or sub-classes
+    unless user.is_a?(Array) && user.all? { |include| include.is_a?(UserInclude) }    
+      raise ArgumentError, "`user` must be an Array of UserInclude objects"
+    end
+    
+    # Ensure `system` is an array of SystemInclude objects or sub-classes
+    unless system.is_a?(Array) && system.all? { |include| include.is_a?(SystemInclude) }    
+      raise ArgumentError, "`system` must be an Array of SystemInclude objects"
+    end
+
+    return [] if bare.empty?
+
+    system_includes = []
+    user_includes = []
+
+    # Create set of bare include filenames for O(1) lookup
+    bare_filenames = Set.new(bare.map(&:filename))
+
+    # Intersect system includes with bare includes based on filename.
+    # Keep system includes that have matching filenames in bare list.
+    system_includes = system.select do |include|
+      bare_filenames.include?(include.filename)
+    end
+
+    # Intersect user includes with bare includes based on filename.
+    # Keep user includes (including subclasses) that have matching filenames in bare list.
+    user_includes = user.select do |include|
+      bare_filenames.include?(include.filename)
+    end    
+
+    # Construct reconciled list of includes with reconciled results.
+    # Always system includes first (C best practice).
+    return (system_includes + user_includes)
+  end
+
+  # Sort list so system includes are at the beginning
+  # (Best practice)
+  def self.sort(includes)
+    _includes = includes.clone
+    self.sort!(_includes)
+    return _includes
+  end
+
+  def self.sort!(includes)
+    includes.sort_by! { |include| include.is_a?(SystemInclude) ? 0 : 1 }
+    return includes
+  end
+end
+
+
+# Base class for C header includes
+class Include
+  attr_reader :filepath
+  attr_reader :filename
+  attr_reader :path
+
+  # Initialize an Include object from a C include statement or simple filepath.
+  #
+  # @param statement [String] A C include statement. Examples:
+  #  - #include "header.h"
+  #  - #include <stdio.h>
+  #  - A quoted/bracketed filepath (e.g., '"header.h"' or <stdio.h>')
+  #  - A plain filepath (e.g., 'path/to/header.h')
+  # @param use_path [Boolean] (default: false)
+  #  - If true, use the full filepath in the include directive
+  #  - If false, use only the filename
+  # @raise [ArgumentError] If the statement is empty or becomes empty after cleaning
+  def initialize(statement, use_path: false)
+    @filepath = clean(statement)
+
+    raise ArgumentError, "Empty include statement" if @filepath.empty?
+
+    @filename = File.basename(@filepath)
+    @path = File.dirname(@filepath)
+    @use_path = use_path
+  end
+
+  # Method specialized by subclasses
+  def to_s()
+    # Simple string representation of class contents with no additional formatting or #include decoration
+    return @filename
+  end
+
+  def to_str()
+    # Coerce to string for implicit conversions (e.g., string interpolation, concatenation)
+    # For instance, Rake#FileList needs this to treat Include objects as strings when extending with #pathmap
+    return @filename
+  end
+
+  # Equality operator -- for Include objects and strings
+  def ==(other)
+    case other
+    when String
+      include == other
+    when UserInclude, MockInclude
+      if self.is_a?(SystemInclude)
+        false
+      else
+        include == other.include
+      end
+    when SystemInclude
+      if self.is_a?(UserInclude)
+        false
+      else
+        include == other.include
+      end
+    when Include
+      include == other.include
+    else
+      false
+    end
+  end
+
+  # Matching operator for pattern matching on filename
+  def =~(pattern)
+    @filename =~ pattern
+  end
+
+  # Not matching operator for pattern matching on filename
+  def !~(pattern)
+    @filename !~ pattern
+  end
+
+  # Hash method for use in sets and as hash keys
+  def hash()
+    include.hash
+  end
+
+  # Alias for == to support case equality
+  alias eql? ==
+
+  # Returns the configured entry to use in the include directive
+  def include()
+    @use_path ? @filepath : @filename
+  end
+
+  private
+
+  def clean(line)
+    # Remove any initial `#include` statement
+    _line = line.gsub(/#\s*include/, '')
+    
+    # Remove any quotation marks from an extracted user include directive
+    _line.gsub!(/"/, '')
+    
+    # Remove any angle brackets from an extracted system include directive
+    _line.gsub!(/</, '')
+    _line.gsub!(/>/, '')
+    
+    # Whitespace cleanup
+    _line.strip!
+
+    return _line
+  end
+end
+
+# UserInclude generates #include "header.h" (with quotes)
+class UserInclude < Include
+  def to_s()
+    "#include \"#{include}\""
+  end
+end
+
+# MockInclude generates #include "<subdir>/header.h" (with quotes)
+# Specialization to support include directive paths for mocks before path are supported everywhere
+class MockInclude < UserInclude
+  def to_s()
+    "#include \"#{filepath}\""
+  end
+end
+
+
+# SystemInclude generates #include <header.h> (with brackets)
+class SystemInclude < Include
+  def to_s()
+    "#include <#{include}>"
+  end
+end

data/lib/ceedling/loginator.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
@@ -38,8 +38,17 @@ class Loginator
 
     @replace = {
       # Problematic characters pattern => Simple characters
-      /↳/ => '>>', # Config sub-entry notation
-      /•/ => '*',  # Bulleted lists
+
+      # Config sub-entry notation
+      /↳/ => '>>',
+      # Bulleted lists
+      /•/ => '*',
+      # Triangle
+      /▶️/ => '>',
+      # Right arrow
+      /➡️/ => '->',
+      # Double right arrow
+      /⏩️/ => '>>',
     }
 
     @project_logging = false
@@ -79,13 +88,19 @@ class Loginator
                 logfile( sanitize( file_msg, false ), extract_stream_name( stream ) )
               end
         
-              # Only output to console when message reaches current verbosity level
-              if !stream.nil? && (@verbosinator.should_output?( verbosity ))
+              # Output to console -- desired verbosity was checked at enqueueing
+              if !stream.nil?
                 # Add labels and fun characters
                 console_msg = format( message, verbosity, label, @decorators )
-        
+
                 # Write to output stream after optionally removing any problematic characters
                 stream.print( sanitize( console_msg, @decorators ) )
+
+                # Flush immediately.
+                # Required on Windows where $stdout connected to a pipe is fully buffered.
+                # Without an explicit flush, messages sit in Ruby's IO buffer and can be lost
+                # when the process exits before the C runtime drains the buffer.
+                stream.flush
               end
             end
           rescue ThreadError
@@ -121,6 +136,7 @@ class Loginator
   # Write the given string to an optional log file and to the console
   #  - Logging statements to a file are always at the highest verbosity
   #  - Console logging is controlled by the verbosity level
+  #  - Ensure at least one newline at the end of each message but collapse multiple newlines as two (for extra whitespace)
   #
   # For default label of LogLabels::AUTO
   #  - If verbosity ERRORS, add ERROR: heading
@@ -141,6 +157,59 @@ class Loginator
   #    simpler variants
 
   def log(message="\n", verbosity=Verbosity::NORMAL, label=LogLabels::AUTO, stream=nil)
+    # No sense posting if our verbosity is too low and we're not logging
+    return unless (@project_logging || @verbosinator.should_output?( verbosity ) )
+
+    # Choose appropriate console stream
+    stream = get_stream( verbosity, stream )
+
+    # Flatten if needed
+    message = message.flatten.join("\n") if (message.class == Array)
+
+    # Ensure at least one newline but no more than two newlines at the end
+    message = message.rstrip + (message.rstrip != message.chomp ? "\n\n" : "\n")
+
+    # Add item to the queue
+    item = {
+      :message => message,
+      :verbosity => verbosity,
+      :label => label,
+      :stream => stream
+    }
+    @queue << item
+  end
+
+  # Write a bulleted list to the log with an optional header.
+  #  - If the list is nil or empty, append "<none>" as a placeholder
+  #  - For a multiline header (e.g. a banner), "<none>" begins on its own line
+  #  - For a single-line header, "<none>" is appended inline after a space
+  def log_list(list, header='', verbosity=Verbosity::NORMAL, label=LogLabels::AUTO, stream=nil)
+    msg = (header.nil? or header.empty?) ? '' : header.rstrip
+
+    if list.nil? or list.empty?
+      msg += (msg.include?("\n") ? "\n" : ' ') if !msg.empty?
+      msg += "<none>"
+    else
+      list.each { |item| msg += "\n • #{item}" }
+    end
+
+    log(msg + "\n\n", verbosity, label, stream)
+  end
+
+  # This is a version of the log function which performs lazy evaluation of the message itself.
+  # The purpose of this version is to improve performance by only building strings that are needed
+  # by the current log level
+  def lazy(verbosity=Verbosity::NORMAL, label=LogLabels::AUTO, stream=nil, &block)
+    # No sense posting if our verbosity is too low and we're not logging
+    return unless (@project_logging || @verbosinator.should_output?( verbosity ) )
+
+    # we've decided we need to actually use this string, so figure it out!
+    message = if block_given?
+      yield block
+    else
+      "\n"
+    end
+
     # Choose appropriate console stream
     stream = get_stream( verbosity, stream )
 
@@ -160,14 +229,36 @@ class Loginator
     @queue << item
   end
 
-
   def log_debug_backtrace(exception)
-      log( "\nDebug Backtrace ==>", Verbosity::DEBUG )
-      
       # Send backtrace to debug logging, formatted almost identically to how Ruby does it.
       # Don't log the exception message itself in the first `log()` call as it will already be logged elsewhere
-      log( "#{exception.backtrace.first}: (#{exception.class})", Verbosity::DEBUG )
-      log( exception.backtrace.drop(1).map{|s| "\t#{s}"}.join("\n"),                  Verbosity::DEBUG )
+    lazy( Verbosity::DEBUG ) do
+      "\nDebug Backtrace ==>\n#{exception.backtrace.first}: (#{exception.class})" +
+      exception.backtrace.drop(1).map{|s| "\t#{s}"}.join("\n")
+    end
+  end
+
+
+  # Write directly to $stdout, bypassing the queue and all verbosity filtering.
+  # Applies emoji decorators (if enabled) but never text labels (INFO:, WARNING:, etc.).
+  # Applies the same character stripping as log() when decorators are disabled.
+  def console(message="\n", label=LogLabels::AUTO)
+    # Flatten if needed
+    message = message.flatten.join("\n") if (message.class == Array)
+
+    # Ensure at least one newline but no more than two newlines at the end
+    message = message.rstrip + (message.rstrip != message.chomp ? "\n\n" : "\n")
+
+    # Add emoji decorator if enabled; skip AUTO (no verbosity context) and NONE
+    prepend = ''
+    prepend = decorate( '', label ) if @decorators && label != LogLabels::AUTO && label != LogLabels::NONE
+
+    # Write directly to stdout — no queue, no verbosity check, no text labels
+    $stdout.print( sanitize( insert_prepend(prepend, message), @decorators ) )
+
+    # Flush immediately.
+    # Required on Windows where $stdout connected to a pipe is fully buffered
+    $stdout.flush()
   end
 
 
@@ -197,6 +288,12 @@ class Loginator
       prepend = '❌ '
     when LogLabels::TITLE
       prepend = '🌱 '
+    when LogLabels::DOCUMENTATION
+      prepend = '📝 '
+    when LogLabels::COMMERCIAL
+      prepend = '💼 '
+    when LogLabels::REQUEST
+      prepend = '🙏 '
     end
 
     return prepend + str
@@ -217,6 +314,12 @@ class Loginator
 
   private
 
+  def insert_prepend(prepend, string)
+    leading, rest = string.match(/\A(\n*)(.*)\z/m).captures
+    return leading + prepend + rest
+  end
+
+
   def get_stream(verbosity, stream)
     # If no stream has been specified, choose one based on the verbosity level of the prompt
     if stream.nil?
@@ -275,7 +378,7 @@ class Loginator
     # Otherwise no headings for decorator-only messages
     end
 
-    return prepend + string
+    return insert_prepend( prepend, string )
   end
 
 

data/lib/ceedling/makefile.rb

@@ -1,7 +1,7 @@
 # =========================================================================
 #   Ceedling - Test-Centered Build System for C
 #   ThrowTheSwitch.org
-#   Copyright (c) 2010-25 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
 #   SPDX-License-Identifier: MIT
 # =========================================================================