CalcExpr

A zero-dependency, cross-platform C11 math expression evaluator built on a recursive-descent parser.

跨平台 C11 数学表达式计算器，使用递归下降解析器完成表达式求值。

v0.1.0（2026-10-23）· MIT · Linux / macOS / Windows CI 通过

Release v0.1.0 · 文档 · 贡献指南 · 变更日志

$ ./build/ninja-debug/bin/calcexpr.exe --version
calcexpr 0.1.0

$ ./build/ninja-debug/bin/calcexpr.exe --help
用法: calcexpr [选项]

选项:
  --version           显示版本号并退出
  --help, -h          显示本帮助并退出
  ...

$ printf '2+3*4\n1e-3*5\n1/0\n' | ./build/ninja-debug/bin/calcexpr.exe
[2026-11-02 09:35:35] [INFO] 请输入表达式> [2026-11-02 09:35:35] [INFO] 表达式: 2+3*4
[2026-11-02 09:35:35] [INFO] 结果:   14
...
[2026-11-02 09:35:35] [INFO] 结果:   0.005
...
[2026-11-02 09:35:35] [ERROR] 错误: 除数为零 (位置: 1, 附近: '/0')

（以上为 2026-11-02 在本机 Windows 11 + MSYS2 UCRT64 GCC 16.2.0 + CMake 4.3.3 + Ninja 1.13.2 的真实输出；为简洁省略了启动横幅与重复提示行。程序正常输出带有 [YYYY-MM-DD HH:MM:SS] [INFO] 前缀。）

项目简介

CalcExpr 是一个零依赖的 C11 命令行计算器，采用递归下降算法处理运算符优先级、括号、一元运算符、小数与科学计数法。计算内核以 calcexpr_core 库提供，命令行程序 calcexpr 负责交互与命令处理。

项目目标是保持模块边界清晰、构建可复现，并用 CTest 与质量门禁持续验证。

功能特性

• 支持加法、减法、乘法、除法与括号
• 正确的运算符优先级（乘除高于加减）
• 支持小数、科学计数法与一元正负号
• 中文交互界面与命令系统
• 编译期可裁剪、运行时可控的调试系统
• 安装与 find_package 消费支持
• 跨平台 CI、静态分析与质量门禁

项目结构

include/calcexpr/       公共头文件（calculator.h、export.h、compiler.h）
src/calcexpr/           实现与内部头文件
src/main.c              CLI 入口
tests/                  CTest 测试与 vendored Unity
tests/package_smoke     安装包消费冒烟
tests/subproject_smoke  子项目消费冒烟
cmake/                  构建、安装与打包模块
scripts/                引导、检查与质量门禁脚本
docs/guides/            中文主题指南
docs/adr/               架构决策记录

快速开始

需要 CMake 3.21+、支持 C11 的编译器、Ninja 预设所需的 Ninja，以及 Python 3（CTest 门禁脚本需要）。Windows 环境配置见环境配置。

首次设置：

Windows PowerShell

./scripts/bootstrap.ps1

Linux/macOS

./scripts/bootstrap.sh

配置、构建与测试：

cmake --preset ninja-debug
cmake --build --preset ninja-debug
ctest --preset ninja-debug --output-on-failure

运行：

# Windows
./build/ninja-debug/bin/calcexpr.exe

# Linux/macOS
./build/ninja-debug/bin/calcexpr

使用方式

以下为交互输入/输出示意；程序的真实输出带有 [YYYY-MM-DD HH:MM:SS] [INFO] 前缀（完整真实记录见首屏）。

请输入表达式> 2+3*4
表达式: 2+3*4
结果:   14

请输入表达式> (2+3)*4
表达式: (2+3)*4
结果:   20

请输入表达式> (3-5)*6
表达式: (3-5)*6
结果:   -12

命令行选项

选项	说明
--version	显示版本号并退出
--help、-h	显示帮助并退出
--debug、-d	开启调试输出
--debug-level=N	设置调试级别（0-5）
--debug-module=NAME	设置调试模块（lexer/parser/calc/main/all）

交互命令

命令	说明
/quit、/exit、/q	退出程序
/help、/show help	显示帮助
/show process	交互选择调试级别并开启计算过程输出
/hide process	关闭计算过程输出

调试级别、编译开关与输出示例见调试系统。

测试与质量门禁

测试使用 CTest 与 vendored Unity：

ctest --preset ninja-debug --output-on-failure

# 只运行计算器用例
ctest --preset ninja-debug -R calcexpr_calculator_tests --output-on-failure

# 只运行命令模块用例
ctest --preset ninja-debug -R calcexpr_command_tests --output-on-failure

本地完整检查：

Windows PowerShell

./scripts/check.ps1

Linux/macOS

./scripts/check.sh

门禁覆盖公共声明与定义一致性、版本一致性、文档链接与索引、门禁自身可失败性，以及安装与子项目冒烟。详细说明见测试与质量门禁。

安装与包消费

cmake --preset ninja-release
cmake --build --preset ninja-release
cmake --install build/ninja-release --prefix install

find_package(CalcExpr CONFIG REQUIRED)
target_link_libraries(app PRIVATE CalcExpr::calcexpr_core)

公共 API 位于 include/calcexpr/calculator.h，内部头文件不会安装。

持续集成

项目包含 GitHub Actions 的构建、测试、共享库、sanitizer、覆盖率、包消费、子项目消费与静态分析工作流。依赖更新由 Dependabot 覆盖。

文档

文档	说明
环境配置	Windows 开发环境与工具安装
CMake 与构建	预设、构建、安装与故障排除
编码风格	命名、头文件、格式与 API 文档约定
测试与质量门禁	测试分层、静态分析与门禁说明
调试系统	编译开关、级别、参数与输出示例
递归下降解析器原理详解	解析算法与代码结构
架构决策记录	ADR 索引与说明
C11 与 CMake 工具链策略	语言标准与工具链决策
C 项目工程标准	本项目遵循的工程基线
贡献指南	分支、提交与 PR 流程
安全策略	漏洞报告与依赖处理

贡献

欢迎提交 Issue 与 Pull Request。提交前请阅读贡献指南，并运行完整本地检查。

许可证

本项目采用 MIT 许可证，详见 LICENSE。