antlr4-native 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51499ca3096bdcbe0ce2e2231e9574b170a96acedeebc813f0e2c69134aa04f1
-  data.tar.gz: 485568b468bbaf64646344e239d58191e7025238c824e21b639e8641d953b118
+  metadata.gz: 21633b380c20483273937e10a72b1b415e2b24b93e3b5fb3ed92b54cb31a9bf9
+  data.tar.gz: 0ce8f5470722e38fcbd90997b5bcbc914f39bb58976ac528d5a7a9a0a99cc41c
 SHA512:
-  metadata.gz: 65ccf82166ff334ac080850448093501c6a371a04f2084a820e3a8298af061af50330fda845815173011c66c08a0ad3e8b2b1026b201d5b419c21d82db8d2b4c
-  data.tar.gz: fb9a2983e52969af587ccb1e6a401825fade06ed13f437a86f5cb8b6289848ee13c7c9284c13c558e17a5e24a60b7eaecf24854de4465ca7d4ef4bbddd10e0c7
+  metadata.gz: 4e92035c90ca04a7ad191446234226237100209d69b1261e7f2944a4b7c54f5bda1e08e10861d967dd455afda3e2b6c3485ae6fe3829857783678eb2043859f3
+  data.tar.gz: b5456c0caf77ff17f5581c4ac3f39060f38f558c5f4fe009fd7f90db2448a15e9ff37f2a4e9419522dae5418684586bf7ded5240ed8c8e886e94b20ed920a9bf

data/README.md

@@ -0,0 +1,97 @@
+# antlr4-native
+
+Create a Ruby native extension from (almost) any ANTLR4 grammar.
+
+## What is this thing?
+
+This gem generates native Ruby extensions from ANTLR grammars, enabling Ruby developers to generate parsers for numerous programming languages, file formats, etc.
+
+## Who needs this?
+
+If you're a Ruby programmer who wants to parse and traverse source code written in a plethora of programming languages, antlr4-native might be able to help you. A number of community-developed ANTLR grammars are available in ANTLR's [grammars-v4](https://github.com/antlr/grammars-v4) repo. Grab one, then use antlr4-native to generate a bunch of Ruby-compatible C++ code from it. The C++ code can be compiled and used as a native extension.
+
+Rather than use antlr4-native directly, consider using its sister project, the [antlr-gemerator](https://github.com/camertron/antlr-gemerator), which can generate a complete rubygem from an ANTLR grammar.
+
+## Code Generation
+
+Here's how to generate a native extension for a given lexer and parser (Python in this case), defined in two .g4 files:
+
+```ruby
+require 'antlr4-native'
+
+generator = Antlr4Native::Generator.new(
+  grammar_files:      ['Python3Lexer.g4', 'Python3Parser.g4'],
+  output_dir:         'ext',
+  parser_root_method: 'file_input'
+)
+
+generator.generate
+```
+
+In the example above, the output directory is set to the standard Ruby native extensions directory, 'ext'. Antlr4-native will generate code into ext/<name>, where <name> is the name of the parser as defined in the grammar file(s). In this case, PythonParser.g4 contains:
+
+```antlr
+parser grammar Python3Parser;
+```
+
+so antlr4-native will generate code into the ext/python3-parser directory.
+
+Finally, the `parser_root_method` option tells antlr4-native which context represents the root of the parse tree. This context functions as the starting point for visitors.
+
+## Using extensions in Ruby
+
+Parsers contain several methods for parsing source code. Use `#parse` to parse a string and `#parse_file` to parse the contents of a file:
+
+
+```ruby
+parser = Python3Parser::Parser.parse(File.read('path/to/file.py'))
+
+# equivalent to:
+parser = Python3Parser::Parser.parse_file('path/to/file.py')
+```
+
+Use the `#visit` method on an instance of `Parser` to make use of a visitor:
+
+```ruby
+visitor = MyVisitor.new
+parser.visit(visitor)
+```
+
+See the next section for more info regarding creating and using visitors.
+
+## Visitors
+
+A visitor class is automatically created during code generation. Visitors are just classes with a bunch of special methods, each corresponding to a specific part of the source language's syntax. The methods are essentially callbacks that are triggered in-order as the parser walks over the parse tree. For example, here's a visitor with a method that will be called whenever the parser walks over a Python function definition:
+
+
+```ruby
+class FuncDefVisitor < Python3Parser::Visitor
+  def visit_func_def(ctx)
+    puts ctx.NAME.text  # print the name of the method
+    visit_children(ctx)
+  end
+end
+```
+
+Make sure to always call `#visit_children` at some point in your `visit_*` methods. If you don't, the subtree under the current context won't get visited.
+
+Finally, if you override `#initialize` in your visitor subclasses, don't forget to call `super`. If you don't, you'll get a nice big segfault.
+
+## Caveats
+
+1. Avoid retaining references to contexts, tokens, etc anywhere in your Ruby code. Contexts (i.e. the `ctx` variables in the examples above) and other objects that are created by ANTLR's C++ runtime are automatically cleaned up without the Ruby interpreter's knowledge. You'll almost surely see a segfault if you retain a reference to one of these objects and try to use it after the call to `Parser#visit`.
+2. Due to an ANTLR limitation, parsers cannot be used in a multi-threaded environment, even if each parser instance is used entirely in the context of a single thread (i.e. parsers are not shared between threads). According to the ANTLR C++ developers, parsers should be threadsafe. Unfortunately firsthand experience has proven otherwise. Your mileage may vary.
+3. The description of this gem says "(almost) any ANTLR4 grammar" because many grammars contain target-specific code. For example, the Python3 grammar referenced in the examples above contains inline Java code that the C++ compiler won't understand. You'll need to port any such code to C++ before you'll be able to compile and use the native extension.
+
+## System Requirements
+
+* A Java runtime (version 1.6 or higher) is required to generate parsers, since ANTLR is a Java tool. The ANTLR .jar file is distributed inside the antlr4-native gem, so there's no need to download it separately.
+* Ruby >= 2.3.
+
+## License
+
+Licensed under the MIT license. See LICENSE for details.
+
+## Authors
+
+* Cameron C. Dutro: http://github.com/camertron

data/antlr4-native.gemspec

@@ -14,5 +14,5 @@ Gem::Specification.new do |s|
   s.has_rdoc = true
 
   s.require_path = 'lib'
-  s.files = Dir['{lib,spec}/**/*', 'Gemfile', 'README.md', 'Rakefile', 'antlr4-native.gemspec']
+  s.files = Dir['{lib,spec,vendor}/**/*', 'Gemfile', 'README.md', 'Rakefile', 'antlr4-native.gemspec']
 end

data/lib/antlr4-native/version.rb

@@ -1,3 +1,3 @@
 module Antlr4Native
-  VERSION = '1.0.0'
+  VERSION = '1.0.1'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: antlr4-native
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Cameron Dutro
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-01 00:00:00.000000000 Z
+date: 2020-05-02 00:00:00.000000000 Z
 dependencies: []
 description: Create a Ruby native extension from any ANTLR4 grammar.
 email:
@@ -18,6 +18,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - Gemfile
+- README.md
 - Rakefile
 - antlr4-native.gemspec
 - lib/antlr4-native.rb
@@ -28,6 +29,7 @@ files:
 - lib/antlr4-native/string_helpers.rb
 - lib/antlr4-native/version.rb
 - lib/antlr4-native/visitor_generator.rb
+- vendor/antlr4-4.8-1-complete.jar
 homepage: http://github.com/camertron/antlr4-native-rb
 licenses: []
 metadata: {}
@@ -46,8 +48,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6.2
+rubygems_version: 3.0.6
 signing_key: 
 specification_version: 4
 summary: Create a Ruby native extension from any ANTLR4 grammar.