ceedling 1.0.1 → 1.1.0

data/examples/wondrous_forest/test/TestTemperatureSensor.c

@@ -0,0 +1,100 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+/* Partials pattern: TEST_PARTIAL_ALL_MODULE
+ * Tests both public functions AND the private static helpers
+ * TemperatureSensor__RawToMilliCelsius() and TemperatureSensor__IsInRange().
+ * Also accesses the file-scoped static s_calibration_offset directly.
+ * SensorHal is mocked traditionally since it has no private statics. */
+
+#include "unity.h"
+#include "ceedling.h"
+#include "MockSensorHal.h"
+
+#include TEST_PARTIAL_ALL_MODULE(TemperatureSensor)
+
+#include "Types.h"
+
+void setUp(void)
+{
+    SensorHal_StartConversion_Expect(SENSOR_CHANNEL_TEMP);
+    TemperatureSensor_Init(0.0f);
+}
+
+void tearDown(void)
+{
+}
+
+void test_RawToMilliCelsius_ZeroCountsGivesZero(void)
+{
+    TEST_ASSERT_EQUAL_INT32(0, TemperatureSensor__RawToMilliCelsius(0u));
+}
+
+void test_RawToMilliCelsius_FullScaleGives85000(void)
+{
+    TEST_ASSERT_EQUAL_INT32(85000, TemperatureSensor__RawToMilliCelsius(4095u));
+}
+
+void test_RawToMilliCelsius_MidScaleGivesApproximately42500(void)
+{
+    /* (2048 * 85000) / 4095 = 42502 */
+    TEST_ASSERT_INT32_WITHIN(100, 42500, TemperatureSensor__RawToMilliCelsius(2048u));
+}
+
+void test_IsInRange_ValidTemperaturesReturnTrue(void)
+{
+    TEST_ASSERT_TRUE(TemperatureSensor__IsInRange(25000));
+    TEST_ASSERT_TRUE(TemperatureSensor__IsInRange(0));
+    TEST_ASSERT_TRUE(TemperatureSensor__IsInRange(85000));
+    TEST_ASSERT_TRUE(TemperatureSensor__IsInRange(-40000));
+}
+
+void test_IsInRange_OutOfRangeReturnsFalse(void)
+{
+    TEST_ASSERT_FALSE(TemperatureSensor__IsInRange(85001));
+    TEST_ASSERT_FALSE(TemperatureSensor__IsInRange(-40001));
+}
+
+void test_CalibrationOffsetIsStoredOnInit(void)
+{
+    SensorHal_StartConversion_Expect(SENSOR_CHANNEL_TEMP);
+    TemperatureSensor_Init(2.5f);
+    /* s_calibration_offset is a file-scoped static exposed as extern by Partials */
+    TEST_ASSERT_FLOAT_WITHIN(0.001f, 2.5f, s_calibration_offset);
+}
+
+void test_Sample_ReturnsFalseWhenChannelNotReady(void)
+{
+    SensorHal_IsChannelReady_ExpectAndReturn(SENSOR_CHANNEL_TEMP, false);
+    TEST_ASSERT_FALSE(TemperatureSensor_Sample());
+}
+
+void test_Sample_ReturnsTrueAndStoresReadingWhenReady(void)
+{
+    /* 1638 counts: (1638 * 85000) / 4095 ~= 34000 milli-C (34 C), in range */
+    SensorHal_IsChannelReady_ExpectAndReturn(SENSOR_CHANNEL_TEMP, true);
+    SensorHal_ReadChannel_ExpectAndReturn(SENSOR_CHANNEL_TEMP, 1638u);
+    SensorHal_StartConversion_Expect(SENSOR_CHANNEL_TEMP);
+
+    TEST_ASSERT_TRUE(TemperatureSensor_Sample());
+    TEST_ASSERT_TRUE(TemperatureSensor_IsValid());
+    TEST_ASSERT_INT32_WITHIN(100, 34000, TemperatureSensor_GetMilliCelsius());
+}
+
+void test_CalibrationOffsetShiftsReading(void)
+{
+    SensorHal_StartConversion_Expect(SENSOR_CHANNEL_TEMP);
+    TemperatureSensor_Init(1.0f);
+
+    /* 2048 counts ~= 42502 milli-C; with +1.0 C offset -> ~= 43502 */
+    SensorHal_IsChannelReady_ExpectAndReturn(SENSOR_CHANNEL_TEMP, true);
+    SensorHal_ReadChannel_ExpectAndReturn(SENSOR_CHANNEL_TEMP, 2048u);
+    SensorHal_StartConversion_Expect(SENSOR_CHANNEL_TEMP);
+
+    TemperatureSensor_Sample();
+    TEST_ASSERT_INT32_WITHIN(200, 43502, TemperatureSensor_GetMilliCelsius());
+}

data/examples/wondrous_forest/test/TestUartDriver.c

@@ -0,0 +1,55 @@
+/* =========================================================================
+    Ceedling - Test-Centered Build System for C
+    ThrowTheSwitch.org
+    Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+    SPDX-License-Identifier: MIT
+========================================================================= */
+
+/* Traditional test - no Partials needed.
+ * UartDriver has no private static functions; it is a thin hardware wrapper.
+ * The #ifdef TEST guard in UartDriver.c pre-sets the TX-ready status bit,
+ * so UartDriver_SendByte() does not spin waiting for hardware. */
+
+#include "unity.h"
+#include "Types.h"
+#include "UartDriver.h"
+
+void setUp(void)
+{
+    UartDriver_Init(115200u);
+}
+
+void tearDown(void)
+{
+}
+
+void test_IsTxReady_ReturnsTrueAfterInit(void)
+{
+    /* UartDriver_Init sets UART_STATUS_REG = UART_STATUS_TX_READY. */
+    TEST_ASSERT_TRUE(UartDriver_IsTxReady());
+}
+
+void test_SendByte_DoesNotHangWhenTxReady(void)
+{
+    /* TX-ready status ensures no spin; call must return without blocking. */
+    UartDriver_SendByte((uint8)'H');
+    TEST_PASS();
+}
+
+void test_SendString_TransmitsEachCharacter(void)
+{
+    UartDriver_SendString("Hi");
+    TEST_PASS();
+}
+
+void test_SendString_DoesNotCrashOnEmptyString(void)
+{
+    UartDriver_SendString("");
+    TEST_PASS();
+}
+
+void test_SendString_GuardsAgainstNullPointer(void)
+{
+    UartDriver_SendString(NULL);
+    TEST_PASS();
+}

data/lib/ceedling/application.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
 # =========================================================================
 

data/lib/ceedling/array_patches.rb

@@ -0,0 +1,28 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+module ArrayPatches
+  # Add Array#intersect? for Ruby 3.0 but use built-in provided by 3.1+
+  # Query if any elements are in common.
+  unless Array.method_defined?(:intersect?)
+    Array.class_eval do
+      def intersect?(other)
+        !(self & other).empty?
+      end
+    end
+  end
+
+  Array.class_eval do
+    # Query if all elements are in common.
+    def overlap?(other)
+      return (self & other).size() == other.size()
+    end
+  end
+end
+
+# Auto-load patches
+ArrayPatches

data/lib/ceedling/batchinator.rb

@@ -0,0 +1,76 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'benchmark'
+require 'parallel'
+
+class Batchinator
+
+  constructor :configurator, :loginator, :reportinator
+
+  def setup
+    @queue = Queue.new
+  end
+
+  # Neaten up a build step with progress message and some scope encapsulation
+  def build_step(msg, heading: true, &block)
+    if heading
+      msg = @reportinator.generate_heading( @loginator.decorate( msg, LogLabels::RUN ) )
+    else # Progress message
+      msg = "\n" + @reportinator.generate_progress( @loginator.decorate( msg, LogLabels::RUN ) )
+    end
+
+    @loginator.log( msg )
+
+    yield # Execute build step block
+  end
+
+  # Parallelize work to be done:
+  #  - Enqueue things (thread-safe)
+  #  - Spin up a number of worker threads within constraints of project file config and amount of work
+  #  - Each worker thread consumes one item from queue and runs the block against its details
+  #  - When the queue is empty, the worker threads wind down
+  def exec(workload:, things:, &job_block)
+
+    batch_results = []
+    sum_elapsed = 0.0
+
+    all_elapsed = Benchmark.realtime do
+      # Determine number of worker threads to run
+      workers = 1
+      case workload
+      when :compile
+        workers = @configurator.project_compile_threads
+      when :test
+        workers = @configurator.project_test_threads
+      else
+        raise NameError.new("Unrecognized batch workload type: #{workload}")
+      end
+
+      # Perform the actual parallelized work and collect the results and timing
+      batch_results = Parallel.map(things, in_threads: workers) do |key, value| 
+        this_results = ''
+        this_elapsed = Benchmark.realtime { this_results = job_block.call(key, value) }
+        [this_results, this_elapsed]
+      end
+
+      # Separate the elapsed time and results
+      if batch_results.size > 0
+        batch_results, batch_elapsed = batch_results.transpose
+        sum_elapsed = batch_elapsed.sum()
+      end
+    end
+
+    # Report the timing if requested
+    @loginator.lazy(Verbosity::OBNOXIOUS) do 
+      "\nBatch Elapsed: (All: %.3fsec Sum: %.3fsec)\n" % [all_elapsed, sum_elapsed]
+    end
+
+    batch_results
+  end
+end
+

data/lib/ceedling/c_extractor/c_extractor.rb

@@ -0,0 +1,340 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'strscan'
+require 'stringio'
+require 'ceedling/exceptions'
+require 'ceedling/c_extractor/c_extractor_constants'
+require 'ceedling/c_extractor/c_extractor_preprocessing'
+require 'ceedling/c_extractor/c_extractor_definitions'
+require 'ceedling/c_extractor/c_extractor_types'
+
+class CExtractor
+
+  include CExtractorConstants
+  include CExtractorTypes
+
+  constructor :c_extractor_code_text, :c_extractor_functions, :c_extractor_declarations, :c_extractor_preprocessing, :c_extractor_definitions
+
+  attr_writer :chunk_size, :max_buffer_length
+
+  def setup()
+    # Aliases
+    @code_text     = @c_extractor_code_text
+    @functions     = @c_extractor_functions
+    @declarations  = @c_extractor_declarations
+    @preprocessing = @c_extractor_preprocessing
+    @definitions   = @c_extractor_definitions
+
+    @chunk_size        = DEFAULT_CHUNK_SIZE
+    @max_buffer_length = DEFAULT_MAX_FUNCTION_LENGTH
+  end
+
+  # Extract C module contents from a source file on disk.
+  #
+  # Parameters:
+  #   filepath: String path to the C source file to extract from
+  #
+  # Returns: CModule struct containing all features extracted.
+  #
+  # Raises:
+  #   CeedlingException: If file cannot be opened (permissions, doesn't exist, etc.)
+  def from_file(filepath)
+    begin
+      File.open(filepath, 'r') do |file|
+        return extract_contents( file, filepath )
+      end
+    rescue => ex
+      raise CeedlingException.new("Error opening file for C contents extraction `#{filepath}` ⏩️ #{ex.message}")
+    end
+  end
+
+  # Extract C module contents from an in-memory string.
+  #
+  # Parameters:
+  #   content:           String containing C source code to extract from
+  #   chunk_size:        (Optional) Size of chunks to read at a time (default: 16 KB)
+  #   max_buffer_length: (Optional) Maximum allowed function size (default: 5 MB)
+  #   max_line_length:   (Optional) Maximum allowed line length (default: 1000 chars)
+  #
+  # Returns: CModule struct containing all features extracted.
+  def from_string(
+    content:,
+    chunk_size:        DEFAULT_CHUNK_SIZE,
+    max_buffer_length: DEFAULT_MAX_FUNCTION_LENGTH,
+    max_line_length:   DEFAULT_MAX_LINE_LENGTH
+  )
+    @chunk_size        = chunk_size
+    @max_buffer_length = max_buffer_length
+    @functions.max_line_length    = max_line_length
+    @declarations.max_line_length = max_line_length
+
+    return extract_contents( StringIO.new( content ), nil )
+  end
+
+  private
+
+  # Extracts all C code features from the given IO source.
+  #
+  # Parameters:
+  #   io:       Ruby IO object (File or StringIO) to read C source from
+  #   filepath: String path to the original source file (may be nil for string input)
+  #
+  # Returns: CModule struct containing all features extracted.
+  #
+  # Raises:
+  #   CeedlingException: If a feature exceeds max_buffer_length during extraction
+  def extract_contents(io, filepath)
+    function_definitions  = []
+    function_declarations = []
+    variable_declarations = []
+    macro_definitions     = []
+    type_definitions      = []
+    aggregate_definitions = []
+    sequence              = []
+    cumulative_newlines   = 0
+
+    # Ensure we're at the start of buffer
+    io.rewind
+
+    until io.eof?
+      # Record IO position once per outer iteration.
+      # All extractors that fail rewind IO back to this position.
+      call_start = io.pos
+
+      # First: preprocessing directives — '#' is the most syntactically unique leading character.
+      # All directives are consumed; filter_directive selects only those collected for storage.
+      directive, dir_start = extract_next_feature(
+        io: io,
+        max_length: @max_buffer_length,
+        extractor: @preprocessing.method(:try_extract_directive)
+      )
+      if directive
+        line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, dir_start, cumulative_newlines)
+        macro_def = @preprocessing.filter_directive(directive, CExtractorPreprocessing::MACRO_DEFINITION)
+        if macro_def
+          stmt = CStatement.new(text: macro_def, line_num: line_num)
+          macro_definitions << stmt
+          sequence << stmt
+        end
+        next
+      end
+
+      # Second: typedef declarations — 'typedef' is as syntactically unique as '#',
+      # so handle it early before any heuristic-based feature detectors.
+      typedef_def, td_start = extract_next_feature(
+        io:         io,
+        max_length: @max_buffer_length,
+        extractor:  @definitions.method(:try_extract_typedef)
+      )
+      if typedef_def
+        line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, td_start, cumulative_newlines)
+        stmt = CStatement.new(text: typedef_def, line_num: line_num)
+        type_definitions << stmt
+        sequence << stmt
+        next
+      end
+
+      # Third: static assertions — C11 _Static_assert / C23 static_assert.
+      # Keyword-led and syntactically unambiguous; consumed but not collected.
+      static_assert, sa_start = extract_next_feature(
+        io:         io,
+        max_length: @max_buffer_length,
+        extractor:  @preprocessing.method(:try_extract_static_assert)
+      )
+      if static_assert
+        _line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, sa_start, cumulative_newlines)
+        next
+      end
+
+      # Fourth: non-typedef struct/enum/union type definitions.
+      # Keyword-led and syntactically unambiguous at the brace level;
+      # collected into aggregate_definitions.
+      agg_def, agg_start = extract_next_feature(
+        io:         io,
+        max_length: @max_buffer_length,
+        extractor:  @definitions.method(:try_extract_aggregate_definition)
+      )
+      if agg_def
+        line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, agg_start, cumulative_newlines)
+        stmt = CStatement.new(text: agg_def, line_num: line_num)
+        aggregate_definitions << stmt
+        sequence << stmt
+        next
+      end
+
+      # Extract a function definition (most unique non-preprocessor feature)
+      func, func_start = extract_next_feature(
+        io: io,
+        max_length: @max_buffer_length,
+        extractor: @functions.method(:try_extract_function_definition),
+        params: [filepath]
+      )
+      if func
+        line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, func_start, cumulative_newlines)
+        func.line_num = line_num
+        function_definitions << func
+        sequence << func
+        next
+      end
+
+      # Extract a function forward declaration (next most unique feature)
+      func, func_start = extract_next_feature(
+        io: io,
+        max_length: @max_buffer_length,
+        extractor: @functions.method(:try_extract_function_declaration)
+      )
+      if func
+        line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, func_start, cumulative_newlines)
+        func.line_num = line_num
+        function_declarations << func
+        sequence << func
+        next
+      end
+
+      # Extract variable declarations as array
+      # NOTE: A compound variable declaration (e.g. `int x, y`) yields multiple declarations
+      vars, vars_start = extract_next_feature(
+        io: io,
+        max_length: @max_buffer_length,
+        extractor: @declarations.method(:try_extract_variable)
+      )
+      if vars
+        line_num, cumulative_newlines =
+          _compute_line_info(io, call_start, vars_start, cumulative_newlines)
+        vars.each { |v| v.line_num = line_num }
+        variable_declarations.concat(vars)
+        sequence.concat(vars)
+        next
+      end
+
+      # If no features found, we are either at EOF or stuck on unrecognized text.
+      # In either case, break out of the loop to avoid infinite looping and return the accumulated results.
+      break
+    end
+
+    return CModule.new(
+      function_definitions:  function_definitions,
+      function_declarations: function_declarations,
+      variable_declarations: variable_declarations,
+      macro_definitions:     macro_definitions,
+      type_definitions:      type_definitions,
+      aggregate_definitions: aggregate_definitions,
+      element_sequence:      sequence
+    )
+  ensure
+    io.close
+  end
+
+  # Generic chunked buffer extraction routine
+  # Reads IO in chunks, building a buffer until the provided extractor successfully extracts a feature
+  #
+  # Parameters:
+  #   io: IO object to read from
+  #   max_length: Maximum buffer size before raising an error
+  #   extractor: Method/Proc that takes a StringScanner and returns [success, extracted_data]
+  #              The extractor should advance the scanner position past the extracted feature on success
+  #
+  # Returns: The extracted data on success, nil if EOF reached without finding a complete feature
+  #
+  # Side effects:
+  #  On success: Advance IO position to immediately after the extracted feature.
+  #  On failure: Rewind IO position to the start of the current buffer.
+  def extract_next_feature(io:, max_length:, extractor:, params: [])
+    buffer = ""
+    chunk_start_pos = io.pos
+
+    # Incrementally attempt feature extraction with repeated attempts and a growing buffer.
+    #
+    # Return on successful finding of a complete feature.
+    # Exit the method with failure ([nil, nil]) and rewind IO:
+    #  1. If we reach end of IO.
+    #  2. Exceed maximum buffer length.
+    #  3. Find no feature.
+    #
+    # Loop:
+    #  1. Advance in attempting to extract a feature in the current buffer.
+    #  2. If we find nothing, expand the buffer with another chunk.
+    #  3. Go back to (1).
+    loop do
+      # Read next chunk
+      chunk = io.read(@chunk_size)
+
+      # Break out of the loop if we've reached the end of IO
+      break unless chunk # EOF
+
+      # Expand the buffer with the new chunk
+      buffer << chunk
+
+      # Safety check -- don't let buffer grow indefinitely
+      if buffer.length > max_length
+        raise CeedlingException.new("Feature extraction exceeded maximum length of #{max_length} characters")
+      end
+
+      # Create a new scanner for the current buffer
+      scanner = StringScanner.new(buffer)
+
+      # Skip any deadspace
+      @code_text.skip_deadspace(scanner)
+
+      # If reached end of string having found no feature -- restart loop to containing loop to grow buffer
+      next if scanner.eos?
+
+      # Capture absolute IO position of feature start (after deadspace) before calling extractor
+      feature_start_pos = chunk_start_pos + scanner.pos
+
+      # Try extract complete feature using provided extractor
+      success, feature = extractor.call(scanner, *params)
+
+      if success
+        # Consume any trailing semicolons that may follow the extracted feature.
+        # This handles cases like "int a;;" or "void foo() {};" where legal but
+        # unnecessary semicolons could break subsequent feature extraction.
+        @code_text.skip_semicolons(scanner)
+
+        # Rewind IO buffer to position after this feature for next extraction attempt
+        io.seek(chunk_start_pos + scanner.pos)
+        return [feature, feature_start_pos]
+      end
+    end
+
+    # Reached IO EOF without finding complete feature -- rewind IO buffer for next extraction attempt
+    io.seek(chunk_start_pos)
+    return [nil, nil]
+  end
+
+  # Compute the 1-based line number of a feature in the source file and advance the
+  # cumulative newline counter past all bytes consumed in this extraction cycle.
+  #
+  # Parameters:
+  #   io:                   IO object (File or StringIO), currently positioned at end_pos
+  #   call_start:           IO byte position at the start of the extract_next_feature call
+  #   feature_start:        IO byte position where the feature begins (after leading deadspace)
+  #   cumulative_newlines:  Running count of newlines consumed before call_start
+  #
+  # Returns: [feature_line, new_cumulative_newlines]
+  #   feature_line:          1-based line number in source file where the feature starts
+  #   new_cumulative_newlines: Updated counter including all bytes consumed this cycle
+  def _compute_line_info(io, call_start, feature_start, cumulative_newlines)
+    end_pos = io.pos
+    io.seek(call_start)
+    consumed = io.read(end_pos - call_start)
+    io.seek(end_pos)
+
+    gap_len        = feature_start - call_start
+    feature_line   = 1 + cumulative_newlines + consumed[0...gap_len].count("\n")
+    new_cumulative = cumulative_newlines + consumed.count("\n")
+
+    [feature_line, new_cumulative]
+  end
+end