1*16467b97STreehugger Robot1) ABOUT 2*16467b97STreehugger Robot======== 3*16467b97STreehugger Robot 4*16467b97STreehugger RobotThis is the Python package 'antlr3', which is required to use parsers created 5*16467b97STreehugger Robotby the ANTLR3 tool. See <http://www.antlr.org/> for more information about 6*16467b97STreehugger RobotANTLR3. 7*16467b97STreehugger Robot 8*16467b97STreehugger Robot 9*16467b97STreehugger Robot2) STATUS 10*16467b97STreehugger Robot========= 11*16467b97STreehugger Robot 12*16467b97STreehugger RobotThe Python target for ANTLR3 is still in beta. Documentation is lacking, some 13*16467b97STreehugger Robotbits of the code is not yet done, some functionality has not been tested yet. 14*16467b97STreehugger RobotAlso the API might change a bit - it currently mimics the Java implementation, 15*16467b97STreehugger Robotbut it may be made a bit more pythonic here and there. 16*16467b97STreehugger Robot 17*16467b97STreehugger RobotWARNING: Currently the runtime library for V3.1 is not compatible with 18*16467b97STreehugger Robotrecognizers generated by ANTLR V3.0.x. If you are an application developer, 19*16467b97STreehugger Robotthen the suggested way to solve this is to package the correct runtime with 20*16467b97STreehugger Robotyour application. Installing the runtime in the global site-packages directory 21*16467b97STreehugger Robotmay not be a good idea. 22*16467b97STreehugger RobotIt is still undetermined, if a future release of the V3.1 runtime will be 23*16467b97STreehugger Robotcompatible with V3.0.x recognizers or if future runtimes V3.2+ will be 24*16467b97STreehugger Robotcompatible with V3.1 recognizers. 25*16467b97STreehugger RobotSorry for the inconvenience. 26*16467b97STreehugger Robot 27*16467b97STreehugger Robot 28*16467b97STreehugger Robot3) DOWNLOAD 29*16467b97STreehugger Robot=========== 30*16467b97STreehugger Robot 31*16467b97STreehugger RobotThis runtime is part of the ANTLR distribution. The latest version can be found 32*16467b97STreehugger Robotat <http://www.antlr.org/download.html>. 33*16467b97STreehugger Robot 34*16467b97STreehugger RobotIf you are interested in the latest, most bleeding edge version, have a look at 35*16467b97STreehugger Robotthe perforce depot at <http://fisheye2.cenqua.com/browse/antlr>. There are 36*16467b97STreehugger Robottarballs ready to download, so you don't have to install the perforce client. 37*16467b97STreehugger Robot 38*16467b97STreehugger Robot 39*16467b97STreehugger Robot4) INSTALLATION 40*16467b97STreehugger Robot=============== 41*16467b97STreehugger Robot 42*16467b97STreehugger RobotJust like any other Python package: 43*16467b97STreehugger Robot$ python setup.py install 44*16467b97STreehugger Robot 45*16467b97STreehugger RobotSee <http://docs.python.org/inst/> for more information. 46*16467b97STreehugger Robot 47*16467b97STreehugger RobotIf this fails due to an obscure setuptools error, you may need a newer bootstrap 48*16467b97STreehugger Robotscript (ez_setup.py): see <https://pypi.python.org/pypi/setuptools/> for full 49*16467b97STreehugger Robotsetuptools installation instructions, or simply download the given ez_setup.py 50*16467b97STreehugger Robotscript, place it in this folder, and run the above setup.py command. 51*16467b97STreehugger Robot 52*16467b97STreehugger Robot 53*16467b97STreehugger Robot5) DOCUMENTATION 54*16467b97STreehugger Robot================ 55*16467b97STreehugger Robot 56*16467b97STreehugger RobotDocumentation (as far as it exists) can be found in the wiki 57*16467b97STreehugger Robot<http://www.antlr.org/wiki/display/ANTLR3/Antlr3PythonTarget> 58*16467b97STreehugger Robot 59*16467b97STreehugger Robot 60*16467b97STreehugger Robot6) REPORTING BUGS 61*16467b97STreehugger Robot================= 62*16467b97STreehugger Robot 63*16467b97STreehugger RobotPlease send bug reports to the ANTLR mailing list 64*16467b97STreehugger Robot<http://www.antlr.org:8080/mailman/listinfo/antlr-interest> or 65*16467b97STreehugger Robot<[email protected]>. 66*16467b97STreehugger Robot 67*16467b97STreehugger RobotExisting bugs may appear someday in the bugtracker: 68*16467b97STreehugger Robot<http://www.antlr.org:8888/browse/ANTLR> 69*16467b97STreehugger Robot 70*16467b97STreehugger Robot 71*16467b97STreehugger Robot7) HACKING 72*16467b97STreehugger Robot========== 73*16467b97STreehugger Robot 74*16467b97STreehugger RobotOnly the runtime package can be found here. There are also some StringTemplate 75*16467b97STreehugger Robotfiles in 'src/org/antlr/codegen/templates/Python/' and some Java code in 76*16467b97STreehugger Robot'src/org/antlr/codegen/PythonTarget.java' (of the main ANTLR3 source 77*16467b97STreehugger Robotdistribution). 78*16467b97STreehugger Robot 79*16467b97STreehugger RobotIf there are no directories 'tests' and 'unittests' in 'runtime/Python', you 80*16467b97STreehugger Robotshould fetch the latest ANTLR3 version from the perforce depot. See section 81*16467b97STreehugger RobotDOWNLOAD. 82*16467b97STreehugger RobotYou'll need java and ant in order to compile and use the tool. 83*16467b97STreehugger RobotBe sure to properly setup your CLASSPATH. 84*16467b97STreehugger Robot(FIXME: is there some generic information, how to build it yourself? I should 85*16467b97STreehugger Robotpoint to it to avoid duplication.) 86*16467b97STreehugger Robot 87*16467b97STreehugger RobotYou can then use the commands 88*16467b97STreehugger Robot$ python setup.py unittest 89*16467b97STreehugger Robot$ python setup.py functest 90*16467b97STreehugger Robotto ensure that changes do not break existing behaviour. 91*16467b97STreehugger Robot 92*16467b97STreehugger RobotPlease send patches to <[email protected]>. For larger code contributions you'll 93*16467b97STreehugger Robothave to sign the "Developer's Certificate of Origin", which can be found on 94*16467b97STreehugger Robot<http://www.antlr.org/license.html> or use the feedback form at 95*16467b97STreehugger Robot<http://www.antlr.org/misc/feedback>. 96