antlr4 README

The project's README from github.com/antlr/antlr4. As one markdown file: README.md.

ANTLR v4

Java 11+ License

ANTLR (ANother Tool for Language Recognition) is a powerful parser generator for reading, processing, executing, or translating structured text or binary files. It's widely used to build languages, tools, and frameworks. From a grammar, ANTLR generates a parser that can build parse trees and also generates a listener interface (or visitor) that makes it easy to respond to the recognition of phrases of interest.

Dev branch build status

MacOSX, Windows, Linux (github actions)

Versioning

ANTLR 4 supports 10 target languages (Cpp, CSharp, Dart, Java, JavaScript, PHP, Python3, Swift, TypeScript, Go), and ensuring consistency across these targets is a unique and highly valuable feature. To ensure proper support of this feature, each release of ANTLR is a complete release of the tool and the 10 runtimes, all with the same version. As such, ANTLR versioning does not strictly follow semver semantics:

If you use a semver verifier in your CI, you probably want to apply special rules for ANTLR, such as treating minor change as a major change.

Repo branch structure

The default branch for this repo is master, which is the latest stable release and has tags for the various releases; e.g., see release tag 4.9.3. Branch dev is where development occurs between releases and all pull requests should be derived from that branch. The dev branch is merged back into master to cut a release and the release state is tagged (e.g., with 4.10-rc1 or 4.10.) Visually our process looks roughly like this:

The Go target now has its own dedicated repo:

$ go get github.com/antlr4-go/antlr

Note The dedicated Go repo is for go get and import only. Go runtime development is still performed in the main antlr/antlr4 repo.

Authors and major contributors

Useful information

You might also find the following pages useful, particularly if you want to mess around with the various target languages.

The Definitive ANTLR 4 Reference

Programmers run into parsing problems all the time. Whether it’s a data format like JSON, a network protocol like SMTP, a server configuration file for Apache, a PostScript/PDF file, or a simple spreadsheet macro language—ANTLR v4 and this book will demystify the process. ANTLR v4 has been rewritten from scratch to make it easier than ever to build parsers and the language applications built on top. This completely rewritten new edition of the bestselling Definitive ANTLR Reference shows you how to take advantage of these new features.

You can buy the book The Definitive ANTLR 4 Reference at amazon or an electronic version at the publisher's site.

You will find the Book source code useful.

Additional grammars

This repository is a collection of grammars without actions where the root directory name is the all-lowercase name of the language parsed by the grammar. For example, java, cpp, csharp, c, etc...

antlr4 (antlr/antlr4)

Searching Database…

19K ·GitHub
这是干什么的?它是一个解析器生成器:你为你的语言或文件格式写一份文法,ANTLR 就会生成一个解析器来构建解析树,还附带 listener/visitor 接口,方便你对识别出的内容做出处理。它被广泛用于开发各种语言、工具和框架。
它是一个我直接运行的工具,还是我在代码里调用的库?两部分都有:生成器是一个 Java 命令行工具,你用它来处理文法文件,它会输出解析器源代码。这些生成的代码要和你目标语言的运行时库配合使用,你需要把这个库引入到你的项目里。
我怎么从一份文法得到一个能用的解析器?先写一个 .g4 文法文件,用 Java 运行 ANTLR 的 jar 包处理它,它就会按你选的目标语言生成解析器以及 listener/visitor 代码;然后把配套的 ANTLR 运行时库加到你的项目里。《Getting started with v4》指南会带你走一遍第一个例子。
它能为哪些语言生成解析器?共十个目标:Java、C#、Python 3、JavaScript、TypeScript、Go、C++、Swift、Dart 和 PHP。你选定一个目标,生成代码,再把配套的 ANTLR 运行时库引入你的项目即可。
升级到更新的 ANTLR 版本总是安全的吗?不能想当然:ANTLR 并不严格遵守 semver 规则。次版本更新也可能包含破坏性改动,向后兼容只在补丁版本升级时才有保证,官方的做法是每次发新版都重新生成你的解析器。
它能在哪些地方运行?生成器在所有能跑 Java 的地方都能运行——Windows、macOS、Linux;生成的解析器则能在你的目标语言能跑的任何地方运行,从 JVM 服务器,到浏览器(JavaScript、TypeScript),再到手机(Swift、Dart)。
为不同语言生成的解析器,行为是一样的吗?是的——让全部 10 个目标保持一致,是团队明确的设计目标,他们称之为独一无二且非常有价值。每次发布都是工具和所有运行时在同一个统一版本号下的完整发布。
它还支持 Python 2 吗?不支持。从 4.14 版本起,Python 2 的支持已被移除,因为 Python 2 在 2020 年就正式停止维护了,各个目标之间的一致性质量也无法继续保证。请使用 Python 3 目标。
每份文法我都得自己从零写吗?不用——有一个配套的现成文法合集,里面都是不含动作代码的文法,每个根目录就是它所解析的语言的小写名字,比如 java、cpp、csharp 或 c。
学它最好的办法是什么?读《The Definitive ANTLR 4 Reference》,也就是 README 推荐的那本书:它把解析 JSON 这类数据格式、SMTP 这类网络协议以及服务器配置文件讲得清清楚楚。这本书的源码也可以在网上获取。
Creator
antlr
Size
69 MB
Stars
19K
Age
16y
Commits · 90 Days