lib-ruby-parser 4.0.3.0-arm64-darwin
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +7 -0
- data/README.md +122 -0
- data/lib/lib-ruby-parser/messages.rb +828 -0
- data/lib/lib-ruby-parser/native/aarch64-apple-darwin/lib_ruby_parser.bundle +0 -0
- data/lib/lib-ruby-parser/nodes.rb +4452 -0
- data/lib/lib-ruby-parser/version.rb +4 -0
- data/lib/lib-ruby-parser.rb +320 -0
- data/lib-ruby-parser.gemspec +34 -0
- metadata +52 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: dc794d4bcd84e7b52c04316d31c1bb107ac738c7b1f4d74cbd04882a5d7fb035
|
4
|
+
data.tar.gz: e9e4e1e41c4a2f8f6769305809f162cbc410ddbe52b9513b677f706d3c25bfee
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: dd76b3f173c4e061d069074137edf6beed8538e8b1b637e24c0e9c8712c06021a473c52ecf031247225deb935ee8aa39da7cd310cac997b4cb24684906570c2b
|
7
|
+
data.tar.gz: d5f47d13ccf6794648ba446551f769389e16682ca927de35cc60b6a35ff17ae6904dea5e01ef2eed60179ff42b7db7742d56d4ef9c39ccb69686a1684f227125
|
data/README.md
ADDED
@@ -0,0 +1,122 @@
|
|
1
|
+
# LibRubyParser
|
2
|
+
|
3
|
+
Ruby bindings for [`lib-ruby-parser`](https://github.com/lib-ruby-parser/lib-ruby-parser)
|
4
|
+
|
5
|
+
## Installation
|
6
|
+
|
7
|
+
Add this line to your application's Gemfile:
|
8
|
+
|
9
|
+
```ruby
|
10
|
+
gem 'lib-ruby-parser'
|
11
|
+
```
|
12
|
+
|
13
|
+
And then execute:
|
14
|
+
|
15
|
+
$ bundle install
|
16
|
+
|
17
|
+
Or install it yourself as:
|
18
|
+
|
19
|
+
$ gem install lib-ruby-parser
|
20
|
+
|
21
|
+
## Usage
|
22
|
+
|
23
|
+
Basic usage:
|
24
|
+
|
25
|
+
```ruby
|
26
|
+
require 'lib-ruby-parser'
|
27
|
+
|
28
|
+
input = <<~RUBY
|
29
|
+
def foo(a, b, c)
|
30
|
+
a + b + c
|
31
|
+
end
|
32
|
+
RUBY
|
33
|
+
|
34
|
+
result = LibRubyParser.parse(input, {})
|
35
|
+
pp result
|
36
|
+
```
|
37
|
+
|
38
|
+
Full documentation can be found [here](https://lib-ruby-parser.github.io/ruby-bindings/)
|
39
|
+
|
40
|
+
## Development
|
41
|
+
|
42
|
+
This repo is **mostly** based on [`c-bindings`](https://github.com/lib-ruby-parser/c-bindings) and [`lib-ruby-parser-nodes Rust crate`](https://github.com/lib-ruby-parser/nodes)
|
43
|
+
|
44
|
+
1. `c-bindings` directory contains static library and header file from the latest [c-bindings release](https://github.com/lib-ruby-parser/c-bindings/releases). Both header and static lib are under gitignore.
|
45
|
+
2. `codegen` directory is a Rust micro-library that generates:
|
46
|
+
+ `nodes.h` - header file with C -> Ruby conversion functions for all `Node` types
|
47
|
+
+ `messages.h` - header file with C -> Ruby conversion functions for all `DiagnosticMessage` types
|
48
|
+
+ `lib/lib-ruby-parser/nodes.rb` - classes and documentation for all `Node` types
|
49
|
+
+ `lib/lib-ruby-parser/messages.rb` - classes and documentation for all `DiagnosticMessage` types
|
50
|
+
3. `lib` directory contains classes and documentation for all classes except dynamic nodes and diagnostic messages
|
51
|
+
4. `main.c` is the main entrypoint to C world. It defines a single `LibRubyParser.parse` function that converts given Ruby objects, converts them to C equivalent, calls `LIB_RUBY_PARSER_parse` from `c-bindings` and converts returned C objects back to Ruby objects. 90% function names in `main.c` end with either `__from_ruby` (to convert object from Ruby to C) or `__to_ruby` (to convert C -> Ruby).
|
52
|
+
5. `scripts` directory:
|
53
|
+
1. `scripts/targets` - directory with target- (and in our case OS-) specific configurations
|
54
|
+
2. `scripts/compile.rb` - prints code to compile `main.c` to `main.o`
|
55
|
+
3. `scripts/link.rb` - prints code to link `main.o` to `lib/lib-ruby-parser/native/lib_ruby_parser.$(DYLIB_EXT)`
|
56
|
+
4. `scripts/setup.mk` - basic setup, prints debug information, auto-included by root Makefile
|
57
|
+
6. `test` directory contains a single minitest test that performs a smoke test
|
58
|
+
|
59
|
+
To run it locally:
|
60
|
+
|
61
|
+
1. make sure to have Ruby and Rust
|
62
|
+
2. `git clone` the repo
|
63
|
+
3. run `bundle install`
|
64
|
+
4. run `make test`
|
65
|
+
|
66
|
+
## Safety
|
67
|
+
|
68
|
+
`c-bindings` is tested with Address Sanitizer (ASAN) on every commit, so it's clean from memory leaks.
|
69
|
+
|
70
|
+
We do run ASAN on CI on every commit for this repo too, but enabling it is a bit tricky. Ruby executable is not linked with `libasan.so`, and so if `main.c` is compiled with `-fsanitize=address` loading `lib_ruby_parser.dylib` gives an error at runtime, `malloc` is supposed to "track itself" using `libasan.so` functionality, but it's not available. `LD_PRELOAD` (on Linux) and `DYLD_INSERT_LIBRARIES` (on MacOS) can do the trick.
|
71
|
+
|
72
|
+
1. On Linux:
|
73
|
+
+ Pass `CFLAGS="-fsanitize=address"` to `make test` to get `lib/lib-ruby-parser/native/lib_ruby_parser.so` compiled with ASAN
|
74
|
+
+ Get path to `libasan.so` by running `gcc -print-file-name=libasan.so`
|
75
|
+
+ Pass it to `make test` with `LD_PRELOAD=$(gcc -print-file-name=libasan.so) make test`
|
76
|
+
2. On MacOS:
|
77
|
+
+ Make sure to have `clang` installed with Homebrew, default `clang` that ships with MacOS doesn't have it.
|
78
|
+
+ Pass `CC=clang CFLAGS="-fsanitize=address"` to `make test` to get `lib/lib-ruby-parser/native/lib_ruby_parser.bundle` compiled with ASAN
|
79
|
+
+ Get path to `libclang_rt.asan_osx_dynamic.dylib` by running `clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib`
|
80
|
+
+ Pass it to `make test` with `DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) make test`
|
81
|
+
|
82
|
+
CI does the same thing on every commit.
|
83
|
+
|
84
|
+
Additionally, we run Leak Sanitizer (LSAN) that is a part of ASAN, it can be enabled by setting `ASAN_OPTIONS=detect_leaks=1` env var.
|
85
|
+
|
86
|
+
Unfortunately, Ruby does something that makes LSAN complain no matter what:
|
87
|
+
|
88
|
+
```
|
89
|
+
ASAN_OPTIONS=detect_leaks=1 \
|
90
|
+
DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) \
|
91
|
+
ruby -e 'p 1'
|
92
|
+
|
93
|
+
# prints a TON of leaks leaks
|
94
|
+
Direct leak of 48 byte(s) in 1 object(s) allocated from:
|
95
|
+
#0 0x108e0fb25 in wrap_calloc+0xa5 (libclang_rt.asan_osx_dynamic.dylib:x86_64+0x44b25)
|
96
|
+
#1 0x1098cfab4 in ruby_xcalloc_body+0x214 (libruby.3.0.dylib:x86_64+0xd0ab4)
|
97
|
+
#2 0x109a6dfb2 in rb_method_entry_make+0x3a2 (libruby.3.0.dylib:x86_64+0x26efb2)
|
98
|
+
#3 0x109a6cfd8 in rb_add_method+0x38 (libruby.3.0.dylib:x86_64+0x26dfd8)
|
99
|
+
#4 0x109a6cf3e in rb_add_method_cfunc+0x3e (libruby.3.0.dylib:x86_64+0x26df3e)
|
100
|
+
#5 0x1098f2efc in Init_IO+0x134c (libruby.3.0.dylib:x86_64+0xf3efc)
|
101
|
+
#6 0x1098ea7c4 in rb_call_inits+0x94 (libruby.3.0.dylib:x86_64+0xeb7c4)
|
102
|
+
#7 0x1098b61e7 in ruby_setup+0x137 (libruby.3.0.dylib:x86_64+0xb71e7)
|
103
|
+
#8 0x1098b6268 in ruby_init+0x8 (libruby.3.0.dylib:x86_64+0xb7268)
|
104
|
+
#9 0x108db7ef8 in main+0x48 (ruby:x86_64+0x100003ef8)
|
105
|
+
#10 0x7fff203baf3c in start+0x0 (libdyld.dylib:x86_64+0x15f3c)
|
106
|
+
```
|
107
|
+
|
108
|
+
It is possible to suppress specified leaks, we have `LSan.supp` file for that:
|
109
|
+
|
110
|
+
```
|
111
|
+
LSAN_OPTIONS=suppressions=LSan.supp \
|
112
|
+
ASAN_OPTIONS=detect_leaks=1 \
|
113
|
+
DYLD_INSERT_LIBRARIES=$(clang --print-file-name=libclang_rt.asan_osx_dynamic.dylib) \
|
114
|
+
ruby -e 'p 1'
|
115
|
+
# prints nothing
|
116
|
+
```
|
117
|
+
|
118
|
+
We use the same file on CI, no functions from `lib-ruby-parser` are allowed to produce leaks.
|
119
|
+
|
120
|
+
## Contributing
|
121
|
+
|
122
|
+
Bug reports and pull requests are welcome on GitHub at https://github.com/lib-ruby-parser/ruby-bindings.
|