{"id":19564365,"url":"https://github.com/antlr/antlr4-tools","last_synced_at":"2025-04-06T01:06:58.314Z","repository":{"id":64777599,"uuid":"497429938","full_name":"antlr/antlr4-tools","owner":"antlr","description":"Tools to run antlr4 w/o needing to install java or antlr4!","archived":false,"fork":false,"pushed_at":"2024-12-07T21:02:37.000Z","size":483,"stargazers_count":89,"open_issues_count":5,"forks_count":23,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-30T00:06:56.306Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/antlr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-05-28T21:20:08.000Z","updated_at":"2025-03-16T18:41:38.000Z","dependencies_parsed_at":"2023-02-12T17:30:42.243Z","dependency_job_id":"f9f3dafe-8000-48a5-9b27-c1a979bdf7c1","html_url":"https://github.com/antlr/antlr4-tools","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antlr%2Fantlr4-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antlr%2Fantlr4-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antlr%2Fantlr4-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/antlr%2Fantlr4-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/antlr","download_url":"https://codeload.github.com/antlr/antlr4-tools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247419860,"owners_count":20936012,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T05:21:39.998Z","updated_at":"2025-04-06T01:06:58.296Z","avatar_url":"https://github.com/antlr.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# antlr4-tools\n\nTools to run antlr4 w/o needing to install java or antlr4! The only requirement is Python3, which is typically installed on all developer machines on all operating systems. \n \n## Install\n\n```bash\n$ pip install antlr4-tools\n```\n\nThat creates `antlr4` and `antlr4-parse` executables. On Windows, of course, this doesn't just work. You need to add the `...\\local-packages\\python38\\scripts` dir to your `PATH`, which itself might require a fun reboot or perhaps reinstall of the OS. haha.\n\n### Windows-specific issues\n\nOn Windows, the `pip` command doesn't just work---you need to add the `...\\local-packages\\python38\\scripts` dir to your `PATH`, which itself might require a fun reboot.  If you use WSL on Windows, then the pip install will also properly at the scripts directly (if you run from bash shell).\n\n\n1. Go to the Microsoft Store\n2. Search in Microsoft Store for Python\n3. Select the newest version of Python (3.10).\n4. Click the \"Get\" button. Store installs python and pip at \"c:\\Users...\\AppData\\Local\\Microsoft\\WindowsApps\\python.exe\" and \"c:\\Users...\\AppData\\Local\\Microsoft\\WindowsApps\\pip.exe\", respectively. And, it updates the search path immediately with the install.\n5. Open a \"cmd\" terminal.\n6. You can now type \"python\" and \"pip\", and \"pip install antlr4-tools\". 7. Unfortunately, it does not add that to the search path.\n7. Update the search path to contain `c:\\Users...\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.10_qbz5n2kfra8p8\\LocalCache\\local-packages\\Python310\\Scripts`. You may need to install MSYS2, then do a `find /c/ -name antlr4.exe 2\u003e /dev/null` and enter that path.\n8. Or, you can set up an alias to antlr4.exe on that path.\n\nThe good news is that the ANTLR4 Python tool downloads the ANTLR jar in a standard location, and you don't need to do that manually. It's also possible to go in a browser, go to python.org, and download the python package. But, it's likely you will need to update the path for antlr4.exe as before.\n\n## First run will install Java and ANTLR\n\nIf needed, `antlr4` will download and install Java 11 and the latest ANTLR jar:\n\n```bash\n$ antlr4 \nDownloading antlr4-4.11.1-complete.jar\nANTLR tool needs Java to run; install Java JRE 11 yes/no (default yes)? y\nInstalled Java in /Users/parrt/.jre/jdk-11.0.15+10-jre; remove that dir to uninstall\nANTLR Parser Generator  Version 4.11.1\n -o ___              specify output directory where all output is generated\n -lib ___            specify location of grammars, tokens files\n...\n```\n\nTo override the version of ANTLR jar used, you can pass a `-v \u003cversion\u003e` argument or set `ANTLR4_TOOLS_ANTLR_VERSION` environment variable:\n\n```bash\n$ antlr4 -v 4.9.3\nANTLR Parser Generator  Version 4.9.3\n -o ___              specify output directory where all output is generated\n -lib ___            specify location of grammars, tokens files\n...\n$ ANTLR4_TOOLS_ANTLR_VERSION=4.10.1 antlr4\nANTLR Parser Generator  Version 4.10.1\n -o ___              specify output directory where all output is generated\n -lib ___            specify location of grammars, tokens files\n...\n```\n\n## Running ANTLR tool on grammars\n\nThe `antlr4` command forwards all arguments (besides `-v` mentioned above) to the actual ANTLR tool command:\n\n```bash\n$ antlr4 JSON.g4 \n$ ls JSON*.java\nJSONBaseListener.java  JSONLexer.java         JSONListener.java      JSONParser.java\n$ antlr4 -Dlanguage=Python3 -visitor JSON.g4\n$ ls JSON*.py\nJSONLexer.py     JSONListener.py  JSONParser.py    JSONVisitor.py\n```\n\n## Parsing using interpreter\n\nThe `antlr4-parse` command requires ANTLR 4.11 and above (but any version of ANTLR works for the plain `antlr4` command).  It accepts the same `-v` argument or environment variable to override the ANTLR jar version used.  (Note: `^D` means control-D and indicates \"end of input\" on Unix but use `^Z` on Windows.)\n\nLet's play with a simple grammar:\n\n```\ngrammar Expr;\nprog:\texpr EOF ;\nexpr:\texpr ('*'|'/') expr\n    |\texpr ('+'|'-') expr\n    |\tINT\n    |\t'(' expr ')'\n    ;\nNEWLINE : [\\r\\n]+ -\u003e skip;\nINT     : [0-9]+ ;\n```\n\nTo parse and get the parse tree in text form, use:\n\n```bash\n$ antlr4-parse Expr.g4 prog -tree\n10+20*30\n^D\n(prog:1 (expr:2 (expr:3 10) + (expr:1 (expr:3 20) * (expr:3 30))) \u003cEOF\u003e)\n```\n\nHere's how to get the tokens and trace through the parse:\n\n```bash\n$ antlr4-parse Expr.g4 prog -tokens -trace\n10+20*30\n[@0,0:1='10',\u003cINT\u003e,1:0]\n[@1,2:2='+',\u003c'+'\u003e,1:2]\n[@2,3:4='20',\u003cINT\u003e,1:3]\n[@3,5:5='*',\u003c'*'\u003e,1:5]\n[@4,6:7='30',\u003cINT\u003e,1:6]\n[@5,9:8='\u003cEOF\u003e',\u003cEOF\u003e,2:0]\nenter   prog, LT(1)=10\nenter   expr, LT(1)=10\nconsume [@0,0:1='10',\u003c8\u003e,1:0] rule expr\nenter   expr, LT(1)=+\nconsume [@1,2:2='+',\u003c3\u003e,1:2] rule expr\nenter   expr, LT(1)=20\nconsume [@2,3:4='20',\u003c8\u003e,1:3] rule expr\nenter   expr, LT(1)=*\nconsume [@3,5:5='*',\u003c1\u003e,1:5] rule expr\nenter   expr, LT(1)=30\nconsume [@4,6:7='30',\u003c8\u003e,1:6] rule expr\nexit    expr, LT(1)=\u003cEOF\u003e\nexit    expr, LT(1)=\u003cEOF\u003e\nexit    expr, LT(1)=\u003cEOF\u003e\nconsume [@5,9:8='\u003cEOF\u003e',\u003c-1\u003e,2:0] rule prog\nexit    prog, LT(1)=\u003cEOF\u003e\n```\n\nHere's how to get a visual tree view:\n\n```bash\n$ antlr4-parse Expr.g4 prog -gui\n10+20*30\n```\n\nThe following will pop up in a Java-based GUI window:\n\n\u003cimg src=\"images/parse-tree.png\" width=\"300\"\u003e\n\nOn real grammars, it can be useful to get decision-making profiling info:\n\n```bash\n$ antlr4-parse JavaLexer.g4 JavaParser.g4 compilationUnit -profile dump.csv T.java\n$ open /tmp/dump.csv \n$ head -5 /tmp/dump.csv \nRule,Invocations,Time (ms),Total k,Max k,Ambiguities,DFA cache miss\ncompilationUnit:0,1,0.164791,1,1,0,1\ncompilationUnit:1,42,1.106583,42,1,0,2\ncompilationUnit:2,2,1.73675,2,1,0,2\ncompilationUnit:3,1,3.969,1,1,0,1\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantlr%2Fantlr4-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fantlr%2Fantlr4-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fantlr%2Fantlr4-tools/lists"}