kicad-source-mirror/qa/tests/common/text_eval

Text Evaluation Parser Tests

This directory contains test suites for the KiCad text evaluation parser functionality.

Test Files

test_text_eval_parser.cpp

High-level integration tests using the EXPRESSION_EVALUATOR wrapper class.

• Basic Arithmetic: Addition, subtraction, multiplication, division, modulo, power operations
• Variable Substitution: Testing variable storage and retrieval in expressions
• String Operations: String concatenation, mixed string/number operations
• Mathematical Functions: abs, sqrt, pow, floor, ceil, round, min, max, sum, avg
• String Functions: upper, lower, concat, beforefirst, beforelast, afterfirst, afterlast
• Formatting Functions: format, fixed, currency
• Date/Time Functions: today, now, dateformat, weekdayname
• Conditional Functions: if statements with boolean logic
• Random Functions: random() number generation
• Error Handling: Syntax errors, runtime errors, undefined variables
• Complex Expressions: Nested functions, multi-step calculations
• Performance Testing: Large expressions and timing validation

test_text_eval_parser_core.cpp

Low-level unit tests for the core parser components. Tests the internal API including:

• ValueUtils: Type conversion, arithmetic operations, string handling
• Node Creation: AST node factory methods and structure validation
• EvaluationVisitor: Direct AST evaluation with custom variable resolvers
• Function Evaluation: Individual function implementations and error cases
• DocumentProcessor: Document parsing and processing workflows
• Error Collection: Error reporting and message formatting
• TokenType Utilities: Token creation and manipulation

test_text_eval_parser_datetime.cpp

Specialized tests for date and time functionality:

• Date Formatting: Various output formats (ISO, US, EU, Chinese, Japanese, Korean, long, short)
• Current Date/Time: today() and now() function validation
• Date Arithmetic: Adding/subtracting days, date calculations
• Edge Cases: Leap years, month boundaries, negative dates
• Weekday Calculations: Day-of-week determination and cycling
• Performance: Date operation timing validation

test_text_eval_parser_vcs.cpp

Specialized tests for version control system (VCS) functionality:

• Identifier Formatting: Commit identifiers with various lengths (4-40 chars), hex validation
• Branch and Author Info: Branch names, author/committer names and emails (repository and file-specific)
• Dirty Status: Repository dirty state detection, untracked file handling
• Labels and Distance: Nearest label/tag finding, commit distance calculations, pattern matching, annotated vs lightweight tags
• Commit Dates: Date formatting (ISO, US, EU, etc.), timestamp validation (repository and file-specific)
• Performance: VCS operation timing validation (100 operations < 2000ms)
• Mixed Expressions: VCS functions combined with variables and text

test_text_eval_parser_integration.cpp

Integration tests simulating real-world KiCad usage scenarios:

• Real-World Scenarios: PCB documentation, title blocks, component summaries
• Callback Variable Resolution: Dynamic variable lookup from external sources
• Thread Safety: Multi-evaluator state isolation
• Memory Management: Large expression handling, resource cleanup
• Parsing Edge Cases: Whitespace, special characters, error recovery
• Performance Testing: Realistic workload simulation

Tested Functions

Mathematical Functions

• abs(x) - Absolute value
• sqrt(x) - Square root (with negative input validation)
• pow(x, y) - Power/exponentiation
• floor(x) - Round down to integer
• ceil(x) - Round up to integer
• round(x, [precision]) - Round to specified decimal places
• min(...) - Minimum of multiple values
• max(...) - Maximum of multiple values
• sum(...) - Sum of multiple values
• avg(...) - Average of multiple values
• shunt(r1, r2) - Parallel resistance calculation: (r1×r2)/(r1+r2)
• db(ratio) - Power ratio to decibels: 10×log₁₀(ratio)
• dbv(ratio) - Voltage/current ratio to decibels: 20×log₁₀(ratio)
• fromdb(db) - Decibels to power ratio: 10^(dB/10)
• fromdbv(db) - Decibels to voltage/current ratio: 10^(dB/20)
• enearest(value, [series]) - Nearest E-series standard value (default: E24)
• eup(value, [series]) - Next higher E-series standard value (default: E24)
• edown(value, [series]) - Next lower E-series standard value (default: E24)
  • Series options: "E3", "E6", "E12", "E24", "E48", "E96", "E192"

String Functions

• upper(str) - Convert to uppercase
• lower(str) - Convert to lowercase
• concat(...) - Concatenate multiple values
• beforefirst(str, c) - Substring
• beforelast(str, c) - Substring
• afterfirst(str, c) - Substring
• afterlast(str, c) - Substring
• format(num, [decimals]) - Format number with specified precision
• fixed(num, [decimals]) - Fixed decimal formatting
• currency(amount, [symbol]) - Currency formatting

Date/Time Functions

• today() - Current date as days since epoch
• now() - Current timestamp as seconds since epoch
• dateformat(days, [format]) - Format date string
  • Formats: "ISO", "US", "EU", "Chinese", "Japanese", "Korean", "long", "short"
• weekdayname(days) - Get weekday name for date

VCS Functions

• vcsidentifier([length]) - Current HEAD commit identifier (default: 40 chars, min: 4)
• vcsbranch() - Current branch name
• vcsauthor() - HEAD commit author name
• vcsauthoremail() - HEAD commit author email
• vcscommitter() - HEAD commit committer name
• vcscommitteremail() - HEAD commit committer email
• vcscommitdate([format]) - HEAD commit date (formats: "ISO", "US", "EU", "Chinese", "Japanese", "Korean", "long", "short")
• vcsnearestlabel([match], [anyTags]) - Nearest label from HEAD (match pattern, anyTags: 0=annotated only, 1=all tags)
• vcslabeldistance([match], [anyTags]) - Number of commits since nearest label
• vcsdirty([includeUntracked]) - Repository dirty status: "1" if dirty, "0" if clean
• vcsdirtysuffix([suffix], [includeUntracked]) - Custom suffix if dirty (default: "-dirty"), empty if clean
• vcsfileidentifier(file, [length]) - Last commit identifier that modified file
• vcsfileauthor(file) - Author of last commit that modified file
• vcsfileauthoremail(file) - Author email of last commit that modified file
• vcsfilecommitter(file) - Committer of last commit that modified file
• vcsfilecommitteremail(file) - Committer email of last commit that modified file
• vcsfilecommitdate(file, [format]) - Date of last commit that modified file

Note: All VCS functions return empty strings when not in a VCS repository. File paths are relative to repository root.

Conditional Functions

• if(condition, true_value, false_value) - Conditional evaluation

Utility Functions

• random() - Random number between 0 and 1

Arithmetic Operators

• + - Addition (also string concatenation)
• - - Subtraction (also unary minus)
• * - Multiplication
• / - Division (with zero-division error handling)
• % - Modulo (with zero-modulo error handling)
• ^ - Exponentiation (right-associative)

Variable Syntax

Variables are referenced using ${variable_name} syntax and can be:

• Set statically using evaluator.SetVariable()
• Resolved dynamically using callback functions

Expression Syntax

Calculations are embedded in text using @{expression} syntax:

• "Result: @{2 + 3}" → "Result: 5"
• "Hello ${name}!" → "Hello World!" (with variable substitution)
• "Area: @{${width} * ${height}} mm²" → "Area: 100 mm²"

Error Handling

The parser collects errors for later diagnostics. However, a string with multiple expressions may be partially evaluated. It will return an error for every expression that was not fully evaluated.