ceedling 1.0.1 → 1.1.0

data/lib/ceedling/c_extractor/c_extractor_functions.rb

@@ -0,0 +1,402 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'ceedling/c_extractor/c_extractor_constants'
+require 'ceedling/c_extractor/c_extractor_types'
+
+class CExtractorFunctions
+
+  include CExtractorConstants
+  include CExtractorTypes
+
+  constructor :c_extractor_code_text
+
+  attr_writer :max_line_length
+
+  def setup()
+    # Aliases
+    @code_text = @c_extractor_code_text
+
+    @max_line_length = DEFAULT_MAX_LINE_LENGTH
+  end
+
+  def try_extract_function_declaration(scanner)
+    # Look for function signature
+    signature = extract_function_signature(scanner, :declaration)
+    return [false, nil] unless signature
+
+    name = extract_function_name(signature)
+    decorators, signature_stripped = parse_decorators_and_strip(signature, name)
+    return [true, CFunctionDeclaration.new(name: name, signature: signature, decorators: decorators, signature_stripped: signature_stripped)]
+  end
+
+  # Try to extract a complete function from the scanner
+  # Returns [success, function_data] where:
+  #  - success: boolean indicating if extraction was successful
+  #  - function_data: CFunctionDefinition with as much info as available (may be partial on failure)
+  def try_extract_function_definition(scanner, filepath)
+    start_pos = scanner.pos
+
+    # Look for function signature
+    signature = extract_function_signature(scanner, :definition)
+    return [false, CFunctionDefinition.new] unless signature
+    
+    @code_text.skip_deadspace(scanner)
+
+    unless scanner.peek(1) == '{'
+      return [false, CFunctionDefinition.new(
+        name: extract_function_name(signature),
+        signature: signature,
+        filepath: filepath
+      )]
+    end
+    
+    # Extract function body
+    success, braced_body = @code_text.extract_balanced_braces(scanner)
+    unless success
+      return [false, CFunctionDefinition.new(
+        name: extract_function_name(signature),
+        signature: signature,
+        source_filepath: filepath,
+        code_block: scanner.string[start_pos...scanner.pos]
+      )]
+    end
+    
+    # Extract full function definition
+    code_block = scanner.string[start_pos...scanner.pos]
+    
+    # Fill out function data class
+    name = extract_function_name(signature)
+    decorators, signature_stripped = parse_decorators_and_strip(signature, name)
+
+    func = CFunctionDefinition.new(
+      name: name,
+      signature: signature,
+      source_filepath: filepath,
+      body: braced_body,
+      code_block: code_block,
+      line_count: code_block.count("\n") + 1,
+      decorators: decorators,
+      signature_stripped: signature_stripped
+    )
+
+    return [true, func]
+  end
+
+  private
+
+  # Extract a function signature from the scanner
+  #
+  # This method attempts to extract either a function declaration or definition signature
+  # from the current scanner position. It distinguishes between functions and variables by
+  # analyzing the structure of the extracted code.
+  #
+  # @param scanner [StringScanner] The scanner positioned at potential function start
+  # @param type [Symbol] Either :declaration or :definition
+  #   - :declaration expects pattern: type name(...);
+  #   - :definition expects pattern: type name(...) { ... }
+  #
+  # @return The extracted and cleaned signature string, or nil if:
+  #   - No valid signature found
+  #   - Unbalanced parentheses detected
+  #   - Variable declaration detected (not a function)
+  #   - Type mismatch (e.g., semicolon found when expecting definition)
+  #
+  # Variable declarations are rejected based on these patterns:
+  #   - Simple variables: int x;
+  #   - Arrays: int arr[10];
+  #   - Function pointers: int (*ptr)(int);
+  #   - Initialized variables: int x = 42;
+  #
+  # The method handles:
+  #   - String literals (both single and double quoted)
+  #   - C-style comments (// and /* */)
+  #   - Nested parentheses in function parameters
+  #   - Whitespace and newlines
+  #
+  # On failure, the scanner position is reset to the starting position.
+  # On success, the scanner is positioned after the signature:
+  #  - After ';' for declarations
+  #  - Before '{' for definitions)
+  #
+  # Safety:
+  #   Enforces max_line_length limit to prevent infinite loops on malformed input
+  def extract_function_signature(scanner, type)
+    start_pos = scanner.pos
+    # Tracks paren depth while accumulating candidate end-positions — not suitable for collect_balanced()
+    paren_depth = 0
+    in_string = false
+    string_char = nil
+    signature_candidates = []  # Track positions where paren_depth returns to 0
+    found_opening_paren = false  # Track if we've seen an opening paren
+    
+    until scanner.eos?
+      char = scanner.peek(1)
+
+      # Safety check
+      if (scanner.pos - start_pos) > @max_line_length
+        scanner.pos = start_pos
+        return nil
+      end
+
+      # Handle string literals
+      if in_string
+        if char == '\\'
+          scanner.getch
+          scanner.getch unless scanner.eos?
+          next
+        elsif char == string_char
+          scanner.getch
+          in_string = false
+          string_char = nil
+          next
+        else
+          scanner.getch
+          next
+        end
+      end
+      
+      case char
+      when '"', "'"
+        in_string = true
+        string_char = char
+        scanner.getch
+      when '/'
+        if scanner.peek(2) =~ %r{^(/[/*])}
+          @code_text.skip_comment(scanner)
+        else
+          scanner.getch
+        end
+      when '('
+        paren_depth += 1
+        found_opening_paren = true
+        scanner.getch
+      when ')'
+        paren_depth -= 1
+        scanner.getch
+        
+        # When we return to depth 0, this could be the end of the function's parameter list
+        if paren_depth == 0
+          signature_candidates << scanner.pos
+        elsif paren_depth < 0
+          # Unbalanced parentheses - not a valid function signature
+          scanner.pos = start_pos
+          return nil
+        end
+      when '{'
+        # Found opening brace
+        if type == :declaration
+          scanner.pos = start_pos
+          return nil
+        else # :definition
+          # Check if any of our candidates is valid
+          if signature_candidates.empty?
+            # No balanced parens found before brace - not a function
+            scanner.pos = start_pos
+            return nil
+          end
+
+          # The last candidate (outermost closing paren) should be the function parameter list
+          signature_end_pos = signature_candidates.last
+          
+          # Extract and clean the signature
+          signature = scanner.string[start_pos...signature_end_pos]
+          return clean_signature(signature)
+        end
+      when ';'
+        # Found semicolon - this is a declaration, not a definition
+
+        if type == :declaration
+          # Before accepting this as a function declaration, verify it has parentheses
+          # and doesn't look like a variable declaration
+          unless found_opening_paren
+            # No parentheses found - this is a variable declaration
+            scanner.pos = start_pos
+            return nil
+          end
+          
+          scanner.getch
+          signature = scanner.string[start_pos...scanner.pos]
+
+          # Validate this looks like a function declaration, not a variable
+          # Function declarations should have: type name(...) ;
+          # NOT: type (*name)(...) ; (function pointer variable)
+          # NOT: type name[...] ; (array variable)
+          # NOT: type name = ... ; (variable with initializer)
+          cleaned = clean_declaration(signature)
+          
+          # Check if this looks like a function declaration
+          # Pattern: ends with identifier followed by (...) and semicolon
+          # NOT: contains (*identifier) pattern (function pointer variable)
+          if cleaned =~ /\(\s*\*\s*[a-zA-Z_][a-zA-Z0-9_]*\s*\)/
+            # This is a function pointer variable, not a function declaration
+            scanner.pos = start_pos
+            return nil
+          end
+          
+          # Additional check: ensure the pattern is identifier(...); not identifier[...]; or identifier;
+          # Strip compiler extensions (e.g. trailing __attribute__((...)) or __declspec(...)) before
+          # checking the closing paren — otherwise a trailing attribute's ')' fools the check into
+          # accepting a variable declaration like `int x __attribute__((aligned(16)));` as a function.
+          content_before_semicolon = @code_text.strip_compiler_extensions(cleaned.gsub(/\s*;$/, ''))
+          unless content_before_semicolon.end_with?(')')
+            # Doesn't end with closing paren - likely a variable declaration
+            scanner.pos = start_pos
+            return nil
+          end
+          
+          return cleaned
+        else # :definition
+          scanner.pos = start_pos
+          return nil
+        end
+      when '['
+        # Found opening bracket - this could be an array declaration
+        # If we haven't found any opening parenthesis yet, this is likely a variable
+        unless found_opening_paren
+          scanner.pos = start_pos
+          return nil
+        end
+        scanner.getch
+      when '='
+        # Found assignment operator - this is a variable with initializer
+        # Only reject if we're at depth 0 (not inside function parameters)
+        if paren_depth == 0
+          scanner.pos = start_pos
+          return nil
+        end
+        scanner.getch
+      else
+        scanner.getch
+      end      
+    end
+    
+    # Reached end without finding complete signature
+    scanner.pos = start_pos
+    return nil
+  end
+
+  def clean_signature(signature)
+    # Remove C-style line comments (in multiline signatures)
+    _signature = signature.gsub(/\/\/.*$/, '')
+    # Remove newlines and tabs
+    _signature.gsub!(/\r\n|\r|\n|\t/, ' ')
+    # Remove C-style block comments
+    _signature.gsub!(/\/\*.*?\*\//m, '')
+    # Collapse consecutive whitespace
+    _signature.gsub!(/\s+/, ' ')
+    # Tidy up leadinga and trailing whitespace
+    _signature.strip!()
+    return _signature
+  end
+
+  def clean_declaration(declaration)
+    _declaration = clean_signature(declaration)
+    # Removes any whitespace before final semicolon
+    _declaration.gsub!(/\s*;$/, ';')
+    return _declaration
+  end
+
+  # Extracts decorator keywords from a C function signature and returns the shortened signature
+  # Migrated from PartializerParser#parse_signature_decorators
+  #
+  # Parameters:
+  #   signature: Complete function signature string
+  #   name:      Function name string (used to split the signature)
+  #
+  # Returns: [decorators_array, shortened_signature_string]
+  # Example: "static inline int foo(void)" with name "foo"
+  #   => [["static", "inline"], "int foo(void)"]
+  def parse_decorators_and_strip(signature, name)
+    return [[], signature] if name.nil?
+
+    # Find the function name in the signature
+    name_index = signature.index(name)
+    return [[], signature] if name_index.nil?
+
+    # Extract everything before the function name
+    prefix = signature[0...name_index]
+
+    # Extract everything from the function name onwards
+    remainder = signature[name_index..-1]
+
+    # Split prefix by whitespace to get tokens
+    tokens = prefix.split(/\s+/).reject(&:empty?)
+
+    return [[], signature] if tokens.empty?
+
+    # Find where decorators end and return type begins
+    decorator_end_index = 0
+    tokens.each_with_index do |token, idx|
+      if TYPE_KEYWORDS.include?(token) ||
+        !PRIVATE_KEYWORDS.any? { |kw| token == kw.downcase } &&
+        !MODIFIER_KEYWORDS.include?(token)
+        decorator_end_index = idx
+        break
+      end
+    end
+
+    # If all tokens are decorators (shouldn't happen in valid C), treat last as return type
+    decorator_end_index = tokens.length - 1 if decorator_end_index == 0 && tokens.length > 1
+
+    decorators = tokens[0...decorator_end_index]
+    return_type_tokens = tokens[decorator_end_index..-1]
+
+    return [[], signature] if decorators.empty?
+
+    # Find where the first return type token appears in the prefix
+    first_return_type_token = return_type_tokens.first
+    return_type_start_index = prefix.index(first_return_type_token)
+
+    # Everything from first return type token onwards is the return type portion
+    return_type_portion = prefix[return_type_start_index..-1]
+
+    # Build shortened signature: return_type_portion + remainder
+    shortened_signature = "#{return_type_portion}#{remainder}"
+
+    return decorators, shortened_signature
+  end
+
+  def extract_function_name(signature)
+    # Paren depth for balance validation only, no text collection — not suitable for collect_balanced()
+    paren_depth = 0
+    signature.each_char do |char|
+      case char
+      when '('
+        paren_depth += 1
+      when ')'
+        paren_depth -= 1
+        return nil if paren_depth < 0  # Unbalanced - closing before opening
+      end
+    end
+    
+    # If parentheses aren't balanced, return nil
+    return nil unless paren_depth == 0
+    
+    # Strategy: Find the main parameter list by looking for the pattern:
+    # identifier followed by '(' that represents the function's parameter list
+    
+    # First, handle function pointer return types: int (*name(params))(params)
+    # Pattern: (*identifier(...))
+    if signature =~ /\(\s*\*\s*([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/
+      return $1
+    end
+    
+    cleaned = @code_text.strip_compiler_extensions(signature.dup)
+    
+    # Now find the function name in the cleaned signature
+    # Look for: identifier followed by '('
+    # The identifier should be preceded by whitespace or * (for pointer returns)
+    if cleaned =~ /(?:^|[\s*])([a-zA-Z_][a-zA-Z0-9_]*)\s*\(/
+      return $1
+    end
+    
+    # Fallback: no valid function name found
+    nil
+  end
+  
+end

data/lib/ceedling/c_extractor/c_extractor_preprocessing.rb

@@ -0,0 +1,262 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+class CExtractorPreprocessing
+
+  # Directive type symbols for use with filter_directive()
+  MACRO_DEFINITION = :macro_definition unless defined?(MACRO_DEFINITION)
+
+  constructor :c_extractor_code_text
+
+  # Scan `scanner` for calls to any macro in `macro_names` and return them as a
+  # flat Array of cleaned strings in order of appearance. Each string is the full
+  # macro call with its argument list on a single line, runs of whitespace
+  # (including embedded newlines) collapsed to a single space.
+  #
+  # - Macro calls inside C line or block comments are skipped.
+  # - String literals (including those containing commas, parens, or a macro name)
+  #   are collected verbatim and do not cause false positives or broken extraction.
+  #
+  # @param scanner [StringScanner] positioned anywhere in the source text
+  # @param macro_names [Array<String>] macro names to search for
+  # @return [Array<String>] cleaned macro call strings
+  def try_extract_macro_calls(scanner, macro_names)
+    results = []
+    pattern = _build_pattern(macro_names)
+
+    until scanner.eos?
+      # Skip comments — macro names inside are not extracted
+      if scanner.check( %r{/[/*]} )
+        @c_extractor_code_text.skip_comment(scanner)
+
+      # Skip string/char literals — macro names inside are not extracted
+      elsif (ch = scanner.peek(1)) == '"' || ch == "'"
+        @c_extractor_code_text.skip_c_string(scanner, ch)
+
+      # Found a macro name followed by '(' — collect its argument list.
+      # Guard against matching a suffix of a longer identifier (e.g., FOO inside NOTFOO).
+      # Note: `\b` and lookbehinds are unreliable in StringScanner because the engine
+      # only sees the remaining suffix; we inspect the original string manually instead.
+      elsif scanner.scan(pattern)
+        macro_name  = scanner[1]
+        match_start = scanner.pos - scanner.matched.length
+        if match_start > 0 && scanner.string[match_start - 1] =~ /\w/
+          _collect_balanced_args(scanner)  # consume and discard — part of a longer identifier
+        else
+          args = _collect_balanced_args(scanner)
+          results << _clean_whitespace("#{macro_name}(#{args})") if args
+        end
+
+      else
+        scanner.getch
+      end
+    end
+
+    return results
+  end
+
+  # Parse a single macro call string (as returned by `try_extract_macro_calls`) into its
+  # macro name and an array of individual parameter strings.
+  #
+  # Top-level commas (not nested inside `()`, `[]`, `{}`, or string literals) are
+  # treated as argument separators. Each returned parameter is trimmed of leading
+  # and trailing whitespace.
+  #
+  # @param call_str [String] a cleaned macro call string, e.g. "FOO(a, b, [c, d])"
+  # @return [Array(String, Array<String>)] two-element array of [macro_name, params]
+  #   where macro_name is nil and params is [] if the string is malformed
+  def parse_macro_call(call_str)
+    scanner = StringScanner.new( call_str )
+
+    # Extract macro name — everything before the opening '('
+    macro_name = scanner.scan( /[^(]+/ )&.strip
+    return [nil, []] if macro_name.nil? || !scanner.scan( /\(/ )
+
+    return [macro_name, _split_params(scanner)]
+  end
+
+  # Try to extract a C preprocessing directive from the scanner.
+  # Called as a feature extractor by CExtractor#extract_next_feature.
+  # Returns every directive found as raw text — callers filter by type as needed.
+  #
+  # @param scanner [StringScanner] positioned at the start of potential directive
+  # @return [Array(Boolean, String)]
+  #   [true,  '#define FOO 42\n'] — directive text (any directive type)
+  #   [false, nil               ] — no # at current position; nothing consumed
+  def try_extract_directive(scanner)
+    text = _collect_directive(scanner)
+    return [false, nil] if text.nil?
+
+    [true, text]
+  end
+
+  # Filter a directive string by type, returning the text only if it matches the requested type.
+  # This allows callers to selectively collect specific directive types while still ensuring
+  # all directives are consumed from the input.
+  #
+  # @param directive [String] raw directive text (as returned by try_extract_directive)
+  # @param type [Symbol] the directive type to match; see MACRO_DEFINITION and other constants
+  # @return [String, nil] the directive text if it matches the requested type, nil otherwise
+  def filter_directive(directive, type)
+    case type
+    when MACRO_DEFINITION
+      directive.match?(/\A#\s*define\b/) ? directive : nil
+    end
+  end
+
+  # Try to extract a C11 _Static_assert or C23 static_assert statement from the scanner.
+  # Called as a feature extractor by CExtractor#extract_next_feature.
+  # The statement is consumed and the full text returned, but callers discard it —
+  # static asserts are not collected into CModule.
+  #
+  # Handles all three forms:
+  #   _Static_assert(expr, "message");   # C11 — message required
+  #   static_assert(expr);               # C23 — message optional
+  #   static_assert(expr, "message");    # C23 — with message
+  #
+  # The expression argument may contain arbitrarily nested parentheses
+  # (e.g. sizeof(struct S) == 8) which are handled by collect_balanced().
+  #
+  # @param scanner [StringScanner] positioned at potential static assert
+  # @return [Array(Boolean, String|nil)]
+  #   [true,  '_Static_assert(sizeof(S) == 4, "msg");\n'] — full statement text
+  #   [false, nil                                        ] — not a static assert; scanner unchanged
+  def try_extract_static_assert(scanner)
+    return [false, nil] unless scanner.check(/(?:_Static_assert|static_assert)\b/)
+
+    text = +''
+
+    # Consume keyword
+    # Pattern (?:_Static_assert|static_assert) ensures that a longer identifier (e.g. `not_static_assert`) does not match
+    text << scanner.scan(/(?:_Static_assert|static_assert)/)
+
+    # Consume optional whitespace between keyword and '('
+    text << (scanner.scan(/[ \t]*/) || '')
+
+    # Consume the balanced argument list — handles all nested parens, strings, comments
+    success, args = @c_extractor_code_text.collect_balanced(scanner, '(', ')')
+    return [false, nil] unless success
+    text << args
+
+    # Consume optional whitespace before ';'
+    text << (scanner.scan(/[ \t]*/) || '')
+
+    # Consume the required terminating ';'
+    return [false, nil] unless scanner.scan(/;/)
+    text << ';'
+
+    # Absorb optional trailing newline (mirrors try_extract_typedef convention)
+    text << (scanner.scan(/[ \t]*\n/) || '')
+
+    [true, text]
+  end
+
+  ### Private ###
+
+  private
+
+  # Build a Regexp matching any of the given macro names followed by optional
+  # whitespace and '('. Capture group 1 = matched name.
+  # Whether the match starts inside a longer identifier is checked in the caller
+  # by inspecting the original string, since StringScanner lookbehinds and `\b`
+  # only see the remaining suffix and cannot inspect characters before scanner.pos.
+  def _build_pattern(macro_names)
+    escaped = macro_names.map { |n| Regexp.escape(n) }
+    Regexp.new("(#{escaped.join('|')})\\s*\\(")
+  end
+
+  # Collect argument text of a macro call whose opening '(' has already been
+  # consumed by the scan pattern in try_extract_macro_calls. Steps back one
+  # position so collect_balanced() can start at '(' and strips the outer parens
+  # from the result. Returns nil on malformed (unbalanced) input.
+  def _collect_balanced_args(scanner)
+    # The outer scan pattern consumed the opening '(' — step back one position
+    # so collect_balanced() can start at it.
+    scanner.pos -= 1
+    success, text = @c_extractor_code_text.collect_balanced(scanner, '(', ')')
+    success ? text[1..-2] : nil  # strip outer parens; nil on unbalanced input
+  end
+
+  # Tracks paren, bracket, and brace depth simultaneously for comma-splitting — not suitable for collect_balanced()
+  # Split parameter text of a macro call whose opening '(' has already been consumed.
+  # Splits on top-level commas only — commas inside `()`, `[]`, `{}`, or string
+  # literals are not treated as separators. Returns an array of trimmed parameters.
+  def _split_params(scanner)
+    params    = []
+    buffer    = +''
+    d_paren   = 0
+    d_bracket = 0
+    d_brace   = 0
+
+    until scanner.eos?
+      ch = scanner.peek(1)
+
+      # String/char literals are captured verbatim — commas and delimiters inside
+      # must not affect depth tracking or param splitting
+      if ch == '"' || ch == "'"
+        before = scanner.pos
+        @c_extractor_code_text.skip_c_string( scanner, ch )
+        buffer << scanner.string[before...scanner.pos]
+
+      elsif scanner.scan( /\(/ ) ; d_paren   += 1 ; buffer << '('
+      elsif scanner.scan( /\[/ ) ; d_bracket += 1 ; buffer << '['
+      elsif scanner.scan( /\{/ ) ; d_brace   += 1 ; buffer << '{'
+      elsif scanner.scan( /\]/ ) ; d_bracket -= 1 ; buffer << ']'
+      elsif scanner.scan( /\}/ ) ; d_brace   -= 1 ; buffer << '}'
+
+      elsif scanner.scan( /\)/ )
+        if d_paren == 0
+          # Closing outer paren — end of argument list
+          params << buffer.strip unless buffer.strip.empty?
+          break
+        end
+        d_paren -= 1
+        buffer << ')'
+
+      elsif d_paren == 0 && d_bracket == 0 && d_brace == 0 && scanner.scan( /,/ )
+        params << buffer.strip
+        buffer = +''
+
+      else
+        buffer << scanner.getch
+      end
+    end
+
+    return params
+  end
+
+  # Collect and return the full text of a preprocessing directive starting at '#'.
+  # Returns nil if not positioned at '#'. Handles backslash-newline continuations.
+  # Trailing whitespace and newlines are stripped from the returned text.
+  def _collect_directive(scanner)
+    return nil unless scanner.check(/#/)
+
+    text = scanner.scan(/#/)
+
+    loop do
+      text += scanner.scan(/[^\n\\]*/) || ''
+
+      if scanner.scan(/\\\n/)
+        text += "\\\n"
+      elsif scanner.scan(/\n/)
+        text += "\n"
+        break
+      else
+        break  # EOS — no trailing newline
+      end
+    end
+
+    text.rstrip
+  end
+
+  # Collapse any run of whitespace (spaces, tabs, newlines) to a single space
+  # and strip leading/trailing whitespace.
+  def _clean_whitespace(text)
+    text.gsub( /\s+/, ' ' ).strip
+  end
+
+end