Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# GitHub configuration / GitHub 配置

[`workflows/ci.yml`](workflows/ci.yml) builds and tests `modern-cpp` on every push
and pull request. It defines two Ubuntu 24.04 jobs: Make and CMake. Both run the
same 12 calculator regression cases. The workflow has read-only repository
permissions and a ten-minute timeout per job.

[`workflows/ci.yml`](workflows/ci.yml) 在 push 和 PR 时构建并测试 `modern-cpp`,
包含 Ubuntu 24.04 上的 Make、CMake 两组任务,分别执行同样的 12 组计算器回归检查。
workflow 使用只读仓库权限,每个任务限时十分钟。

It installs Flex, Bison, G++, Make, CMake, and Python 3 using apt. To run locally,
follow the [modern-cpp README](../modern-cpp/README.md). The older examples and
the documentation site are not covered by this workflow. Manual dispatch is
available once GitHub exposes the workflow on the default branch.

任务通过 apt 安装 Flex、Bison、G++、Make、CMake 和 Python 3。本地执行方法见
[modern-cpp README](../modern-cpp/README.md)。当前 CI 不覆盖旧示例或文档网站。
当默认分支包含此 workflow 后,可在 GitHub Actions 界面手动触发。
14 changes: 14 additions & 0 deletions .github/workflows/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Workflows / 自动化工作流

[`ci.yml`](ci.yml) is the calculator CI workflow: two Ubuntu 24.04 jobs build
`modern-cpp` with Make and CMake, then run its Python regression tests. It runs
on pushes and pull requests and declares a manual dispatch trigger.

[`ci.yml`](ci.yml) 是计算器 CI:在 Ubuntu 24.04 上用 Make 和 CMake 分别构建
`modern-cpp`,随后执行 Python 回归测试。由 push、PR 触发,也声明了手动触发入口。

See [GitHub configuration](../README.md) for permissions and scope, and
[the example README](../../modern-cpp/README.md) for local commands.

权限及覆盖范围见 [GitHub 配置](../README.md),本地命令见
[示例说明](../../modern-cpp/README.md)。
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,24 @@
# Flex/Bison Examples


## Directory guides / 目录说明

Each source directory has English and Chinese instructions. / 各源码目录均提供中英文说明。

- [simple-c](simple-c/README.md)
- [simple-cpp](simple-cpp/README.md)
- [reentrant-c](reentrant-c/README.md)
- [reentrant-variant-cpp](reentrant-variant-cpp/README.md)
- [modern-cpp](modern-cpp/README.md)
- [optional-semicolon](optional-semicolon/README.md)
- [python-like-indentation](python-like-indentation/README.md)
- [elite2](elite2/README.md)
- [utf8](utf8/README.md)
- [error-recovery](error-recovery/README.md)
- [error-handling](error-handling/README.md)
- [docs](docs/README.md)
- [.github](.github/README.md)

## Tool versions and modern example

Upstream NEWS checked on 2026-10-16 still lists **Flex 2.6.4** (2017-05-06)
Expand Down
25 changes: 25 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
# Documentation site / 文档网站

This directory contains the GitHub Pages documentation source. It does not build
a parser executable.

本目录存放 GitHub Pages 文档网站的源文件,不生成解析器程序。

## Files / 文件

- [`index.md`](index.md): site homepage and historical example overview. / 网站首页及原有示例概览。
- [`_config.yml`](_config.yml): selects the Jekyll `jekyll-theme-slate` theme. / 配置 Jekyll 网站主题。

## Editing / 编辑

Edit Markdown directly. The [root README](../README.md) lists the examples,
including [modern-cpp](../modern-cpp/); each example directory has bilingual build
and usage instructions. `index.md` is a separate file and is not automatically
synchronized with the root README. No local Jekyll dependency manifest or site
publishing workflow is included; hosting is configured separately in repository
settings.

直接编辑 Markdown 即可。[根目录 README](../README.md) 提供示例导航,包括
[modern-cpp](../modern-cpp/);各示例目录提供双语构建和使用说明。`index.md` 与根目录
README 是独立文件,不会自动同步。仓库未提供本地 Jekyll 依赖清单或网站发布 workflow,
网站托管需在仓库设置中单独配置。
55 changes: 55 additions & 0 deletions elite2/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# elite2 — Language grammar / 语言语法

## Overview / 简介

A larger grammar based on the author's second Elite language design. It uses
Bison's C++ parser, variant values, token constructors, locations, and a reentrant
Flex scanner. It recognizes syntax without implementing a full evaluator or compiler.

基于作者第二版 Elite 语言设计的较完整语法,使用 Bison C++ 解析器、variant、
token constructor、位置信息和 Flex 可重入扫描器;主要用于语法识别,未实现完整求值器或编译器。

## Requirements / 依赖

Flex, Bison >= 3.0.4, a C++11 compiler, and CMake 3.5+.
There is no handwritten Makefile in this directory.

需要 Flex、Bison 3.0.4+、C++11 编译器及 CMake 3.5+,本目录没有手写 Makefile。

## Build and run / 构建与运行

Run from the repository root / 从仓库根目录执行:

```sh
cmake -S elite2 -B build/elite2 -DCMAKE_CXX_STANDARD=11
cmake --build build/elite2
printf '1 + 2\n' | ./build/elite2/elite
```

The executable is named `elite`, not `elite2`. Input comes from stdin; successful
parsing does not print the value of the expression. With CMake 4, add
`-DCMAKE_POLICY_VERSION_MINIMUM=3.5` to the configure command.

可执行文件名为 `elite`,输入来自标准输入,解析成功不会输出表达式的计算结果。
使用 CMake 4 时,配置命令需加 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`。

## Code guide / 代码导读

`lexer.l` defines literals, identifiers, and operators. `parser.y` defines types,
expressions, calls, and allocation syntax. `ParserCtx.hpp/.cpp` manage the scanner,
location, and parser instances.

`lexer.l` 定义字面量、标识符及运算符;`parser.y` 定义类型、表达式、调用和分配语法;
`ParserCtx.hpp/.cpp` 管理扫描器、位置和解析器实例。

## Notes / 注意事项

Bison reports shift/reduce and reduce/reduce conflicts and unused rules. This is
an exploratory grammar, so acceptance alone does not establish an unambiguous
language design. It also uses deprecated Bison configuration. For a smaller,
current C++ starting point see [modern-cpp](../modern-cpp/).

Bison 会报告移进/归约、归约/归约冲突以及未使用规则。这是探索性语法,接受输入不代表
语法无歧义;也使用了旧版 Bison 配置。较小的现代 C++ 入门示例见 [modern-cpp](../modern-cpp/)。

[All examples / 所有示例](../README.md)
33 changes: 33 additions & 0 deletions error-handling/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# error-handling — Source-aware diagnostics / 带源码位置的错误提示

## Overview / 简介

Christian Hagen’s IBM developerWorks calculator example, with variables, custom input buffering, source-line display, token markers, and formatted diagnostics.

Christian Hagen 的 IBM developerWorks 计算器示例,展示变量、自定义输入缓冲、源码行显示、token 标记及格式化错误提示。

## Requirements / 依赖

Flex, Bison, a C compiler, and Make. This directory has no CMake target and is not in the root CMake build. / 需要 Flex、Bison、C 编译器及 Make;本目录没有 CMake 目标,也未加入根目录 CMake 构建。

## Build and run / 构建与运行

Run from this directory / 在本目录执行:

```sh
make
./ccalc defs.txt
./ccalc -debug defs.txt
```

Without an argument, `ccalc` reads `defs.txt`. The bundled file intentionally contains errors; expect source markers and a final variable dump. Statements end with semicolons. / 不传参数时读取 `defs.txt`;自带文件故意包含错误,输出位置标记及最终变量表;语句用分号结束。

## Code guide / 代码导读

`ccalc.c/.h` handle source input and diagnostics; `cmath.c` manages variables and evaluation; `lex.l` and `parse.y` define the language; `defs.txt` exercises errors. / `ccalc.c/.h` 处理源码和错误,`cmath.c` 管理变量和计算,其余文件定义语言及测试输入。

## Notes / 注意事项

This is a historical reference with global state, not a reentrant implementation. Preserve the author attribution in source files. See the [original article](https://developer.ibm.com/tutorials/l-flexbison/). / 此历史示例使用全局状态,不可重入;请保留源文件作者署名,参阅[原文](https://developer.ibm.com/tutorials/l-flexbison/)。

[All examples / 所有示例](../README.md)
41 changes: 41 additions & 0 deletions error-recovery/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# error-recovery — Recover at statement boundaries / 在语句边界恢复

## Overview / 简介

A calculator demonstrating Bison’s `error` token and `yyerrok`. A malformed expression is skipped through `=` plus newline, so later expressions can still be parsed.

通过 Bison 的 `error` token 和 `yyerrok` 展示恢复:错误表达式跳过至 `=` 加换行,随后继续解析后面的表达式。

## Requirements / 依赖

Flex, Bison, a C++ compiler, and Make or CMake 3.5+. / 需要 Flex、Bison、C++ 编译器及 Make 或 CMake 3.5+。

## Build and run / 构建与运行

Run from this directory / 在本目录执行:

```sh
make
./error-recovery test.txt
```

The bundled file mixes valid and invalid expressions. Expect numeric results interleaved with syntax diagnostics. You can also pipe stdin. / 自带文件混合合法和错误表达式,输出包含计算结果和语法错误;也可从标准输入读取。

Alternative standalone CMake build, from the repository root / 也可从仓库根目录独立构建:

```sh
cmake -S error-recovery -B build/error-recovery
cmake --build build/error-recovery
```

The executable is `build/error-recovery/error-recovery`; pass the same input as above. With CMake 4, add `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` when configuring these legacy projects. / 可执行文件为 `build/error-recovery/error-recovery`,输入方式同上;CMake 4 配置旧项目时需加 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`。

## Code guide / 代码导读

`parser.y`: compare `exp EQUAL END` with `error EQUAL END`. `lexer.l` returns the boundary tokens; `test.txt` exercises recovery. / 重点比较 `parser.y` 中两条语句规则;`lexer.l` 返回同步边界 token,`test.txt` 演示恢复。

## Notes / 注意事项

Recovery is at `=` plus newline, not at every newline. Lexical errors still exit immediately, and main returns zero after parser errors. Division by zero is reported separately by an action. / 恢复边界是 `=` 加换行,并非任意换行;词法错误仍直接退出,主函数也未返回解析错误状态。除零由语义动作单独报告。

[All examples / 所有示例](../README.md)
13 changes: 13 additions & 0 deletions modern-cpp/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,3 +56,16 @@ pull requests; it can also be triggered manually.
在仓库根目录执行上述命令;若按前面的 CMake 路径构建,则传入
`build/modern-cpp/modern-cpp`。CI 在 Ubuntu 24.04 上分别构建并测试两种构建方式,
覆盖运算优先级、小数、换行格式、错误位置、除零及不完整输入。

## Code guide / 代码导读

`parser.y` defines the C++ API and arithmetic grammar; `lexer.l` returns typed
tokens and tracks locations; `main.cpp` owns the scanner with RAII. `test.py`
checks valid results and error behavior. Both build files generate parser/scanner
sources into the build directory.

`parser.y` 定义 C++ 接口和算术语法,`lexer.l` 返回带类型的 token 并跟踪位置,
`main.cpp` 用 RAII 管理扫描器,`test.py` 检查计算结果及错误行为。
两种构建方式均将生成代码放入构建目录。

[All examples / 所有示例](../README.md)
41 changes: 41 additions & 0 deletions optional-semicolon/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# optional-semicolon — Optional semicolons / 可选分号

## Overview / 简介

A Slip-style grammar that probes Bison parse tables to insert a semicolon when a newline can end a statement, while allowing incomplete expressions to continue.

Slip 风格语法,通过探测 Bison 解析表,在换行可结束语句时插入分号,同时允许未完成的表达式跨行。

## Requirements / 依赖

Flex, Bison with support for the bundled custom skeleton, a C11 compiler, and Make or CMake 3.5+. / 需要 Flex、兼容自带定制 skeleton 的 Bison、C11 编译器及 Make 或 CMake 3.5+。

## Build and run / 构建与运行

Run from this directory / 在本目录执行:

```sh
make
./optional-semicolon test.txt
```

Pass an input filename. The sample mixes explicit and omitted semicolons in function calls; output contains parser debugging and the resulting list-based AST, not execution of those calls. / 必须传入文件名;示例混用显式和省略的分号,输出调试信息及列表形式 AST,不会执行函数调用。

Alternative standalone CMake build, from the repository root / 也可从仓库根目录独立构建:

```sh
cmake -S optional-semicolon -B build/optional-semicolon
cmake --build build/optional-semicolon
```

The executable is `build/optional-semicolon/optional-semicolon`; pass the same input as above. With CMake 4, add `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` when configuring these legacy projects. / 可执行文件为 `build/optional-semicolon/optional-semicolon`,输入方式同上;CMake 4 配置旧项目时需加 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`。

## Code guide / 代码导读

`parser.y` contains `yyfilter`; `bison.m4` injects it into the parser. `sliplist.c/.h` and `list.h` supply AST/list helpers; `lexer.l` preserves newlines. / `parser.y` 中的 `yyfilter` 由 `bison.m4` 注入;列表文件提供 AST,词法文件保留换行。

## Notes / 注意事项

The custom skeleton accesses generated parser internals and may need changes across Bison versions. Generate from this directory so `./bison.m4` resolves. GCC 14 reports undeclared `fileno` under strict C11 and a call to `yyfilter` before its declaration. Defining `_POSIX_C_SOURCE=200809L` addresses only the former; the parser declaration still needs repair. The entry point assumes a filename argument. / 定制 skeleton 依赖生成器内部实现,跨版本可能需要适配;请在本目录生成以找到 `./bison.m4`。GCC 14 严格 C11 下会报 `fileno` 未声明以及 `yyfilter` 在声明前被调用;定义 `_POSIX_C_SOURCE=200809L` 只能解决前者,仍需修复解析器声明;入口未检查文件名参数是否缺失。

[All examples / 所有示例](../README.md)
41 changes: 41 additions & 0 deletions python-like-indentation/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# python-like-indentation — Indentation-sensitive grammar / 缩进语法

## Overview / 简介

Extends the optional-semicolon approach with Flex start conditions, indentation tracking, and `INDENT`/`DEDENT` tokens. Incomplete expressions can continue across lines.

在可选分号基础上,利用 Flex start condition、缩进跟踪和 `INDENT`/`DEDENT` 实现缩进语法,并允许未完成表达式跨行。

## Requirements / 依赖

Flex, Bison compatible with the bundled custom skeleton, a C compiler, and Make or CMake 3.5+. / 需要 Flex、兼容定制 skeleton 的 Bison、C 编译器及 Make 或 CMake 3.5+。

## Build and run / 构建与运行

Run from this directory / 在本目录执行:

```sh
make
./python-like-indentation test.txt
```

Pass the sample filename. It uses `defun` and indentation (not Python’s exact syntax); output traces scanning/parsing and prints a list-based AST. / 传入示例文件名,使用 `defun` 和缩进,并非完整 Python 语法;输出扫描/解析跟踪及列表 AST。

Alternative standalone CMake build, from the repository root / 也可从仓库根目录独立构建:

```sh
cmake -S python-like-indentation -B build/python-like-indentation
cmake --build build/python-like-indentation
```

The executable is `build/python-like-indentation/python-like-indentation`; pass the same input as above. With CMake 4, add `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` when configuring these legacy projects. / 可执行文件为 `build/python-like-indentation/python-like-indentation`,输入方式同上;CMake 4 配置旧项目时需加 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`。

## Code guide / 代码导读

`lexer.l` tracks indentation and start conditions; `parser.y` probes legal tokens; `bison.m4` calls the filter; `sliplist.c/.h` and `list.h` implement AST helpers. / 词法文件跟踪缩进及状态,语法文件探测合法 token,定制 skeleton 调用过滤器,列表文件实现 AST。

## Notes / 注意事项

This legacy example currently fails to build with GCC 14 because generated code calls `yyfilter` before it is declared. Its Makefile also uses a C++ standard flag for C. These issues are recorded here, not fixed by this documentation change. Run generation from this directory to locate `./bison.m4`. Tabs use four-column stops; this is not a Python-compatible parser. / 此旧例在 GCC 14 下因生成代码在声明前调用 `yyfilter` 而构建失败;Makefile 还将 C++ 标准参数用于 C。本次文档改动记录问题,未修改实现。请在本目录生成以找到 skeleton;制表符按四列对齐,不是兼容 Python 的解析器。

[All examples / 所有示例](../README.md)
41 changes: 41 additions & 0 deletions reentrant-c/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# reentrant-c — Scanner context in C / C 扫描器上下文

## Overview / 简介

A minimal `function` grammar showing a reentrant Flex scanner and explicit scanner/context parameters passed into Bison.

最小的 `function` 语法,展示 Flex 可重入扫描器,以及向 Bison 显式传递扫描器和解析上下文参数。

## Requirements / 依赖

Flex, Bison, a C11 compiler, and Make or CMake 3.5+. / 需要 Flex、Bison、C11 编译器及 Make 或 CMake 3.5+。

## Build and run / 构建与运行

Run from this directory / 在本目录执行:

```sh
make
printf 'function' | ./reentrant-c
```

The single `function` token is accepted without a result message. / 单个 `function` token 可被接受,不打印计算结果。

Alternative standalone CMake build, from the repository root / 也可从仓库根目录独立构建:

```sh
cmake -S reentrant-c -B build/reentrant-c
cmake --build build/reentrant-c
```

The executable is `build/reentrant-c/reentrant-c`; pass the same input as above. With CMake 4, add `-DCMAKE_POLICY_VERSION_MINIMUM=3.5` when configuring these legacy projects. / 可执行文件为 `build/reentrant-c/reentrant-c`,输入方式同上;CMake 4 配置旧项目时需加 `-DCMAKE_POLICY_VERSION_MINIMUM=3.5`。

## Code guide / 代码导读

`reentrant_parser.h` defines the context; `reentrant_parser.c` initializes the scanner and calls `yyparse`; `parser.y` passes parameters; `lexer.l` matches `function`. / 上下文定义在 `reentrant_parser.h`,初始化和调用在 `reentrant_parser.c`,其余两文件定义语法及词法。

## Notes / 注意事项

The scanner is reentrant, but the grammar does not set `api.pure`, so this is not a complete thread-safe parser. Cleanup and parse-status propagation are also incomplete. With GCC 14, strict C11 reports undeclared `fileno`, and generated parser calls also lack declarations for `yylex`/`yyerror`. Defining `_POSIX_C_SOURCE=200809L` addresses only `fileno`; declarations still need repair before this toolchain can build it. / 扫描器可重入,但语法未配置 `api.pure`,不能据此认定整个解析器线程安全;资源释放和解析状态返回也未完整实现。GCC 14 严格 C11 下会报 `fileno` 以及生成代码调用的 `yylex`/`yyerror` 未声明;定义 `_POSIX_C_SOURCE=200809L` 只能解决前者,仍需补全声明才能在此工具链构建。

[All examples / 所有示例](../README.md)
Loading
Loading