Module: Prism
Overview
The Prism Ruby parser.
“Parsing Ruby is suddenly manageable!”
- You, hopefully
Constant Summary
-
BACKEND =
The FFI backend is used on other Ruby implementations.
:FFI
-
VERSION =
The version constant is set by reading the result of calling pm_version.
LibRubyParser.pm_version.read_string
Class Method Summary
-
.dump(source, **options)
Mirror the
dump
API by using the serialization API. -
.dump_file(filepath, **options)
Mirror the
dump_file
API by using the serialization API. -
.lex(code, **options)
Mirror the
lex
API by using the serialization API. -
.lex_compat(source, **options) ⇒ LexCompat::Result
Returns a parse result whose value is an array of tokens that closely resembles the return value of
Ripper.lex
. -
.lex_file(filepath, **options)
Mirror the
lex_file
API by using the serialization API. -
.lex_ripper(source) ⇒ Array
This lexes with the Ripper lex.
-
.load(source, serialized) ⇒ ParseResult
Load the serialized AST using the source as a reference into a tree.
-
.parse(code, **options)
Mirror the
parse
API by using the serialization API. -
.parse_comments(code, **options)
Mirror the
parse_comments
API by using the serialization API. -
.parse_failure?(code, **options) ⇒ Boolean
Mirror the
parse_failure?
API by using the serialization API. -
.parse_file(filepath, **options)
Mirror the
parse_file
API by using the serialization API. -
.parse_file_comments(filepath, **options)
Mirror the
parse_file_comments
API by using the serialization API. -
.parse_file_failure?(filepath, **options) ⇒ Boolean
Mirror the
parse_file_failure?
API by using the serialization API. -
.parse_file_success?(filepath, **options) ⇒ Boolean
Mirror the
parse_file_success?
API by using the serialization API. -
.parse_lex(code, **options)
Mirror the
parse_lex
API by using the serialization API. -
.parse_lex_file(filepath, **options)
Mirror the
parse_lex_file
API by using the serialization API. -
.parse_stream(stream, **options)
Mirror the
parse_stream
API by using the serialization API. -
.parse_success?(code, **options) ⇒ Boolean
Mirror the
parse_success?
API by using the serialization API. -
.profile(source, **options)
Mirror the
profile
API by using the serialization API. -
.profile_file(filepath, **options)
Mirror the
profile_file
API by using the serialization API. -
.dump_options(options)
private
Convert the given options into a serialized options string.
-
.dump_options_command_line(options)
private
Return the value that should be dumped for the command_line option.
-
.dump_options_version(version)
private
Return the value that should be dumped for the version option.
- .dump_common(string, options) private Internal use only
- .lex_common(string, code, options) private Internal use only
- .parse_comments_common(string, code, options) private Internal use only
- .parse_common(string, code, options) private Internal use only
- .parse_file_success_common(string, options) private Internal use only
- .parse_lex_common(string, code, options) private Internal use only
Class Method Details
.dump(source, **options)
Mirror the dump
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 229
def dump(source, ** ) LibRubyParser::PrismString.with_string(source) { |string| dump_common(string, ) } end
.dump_common(string, options) (private)
# File 'lib/prism/ffi.rb', line 354
def dump_common(string, ) # :nodoc: LibRubyParser::PrismBuffer.with do |buffer| LibRubyParser.pm_serialize_parse(buffer.pointer, string.pointer, string.length, ( )) buffer.read end end
.dump_file(filepath, **options)
Mirror the dump_file
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 234
def dump_file(filepath, ** ) [:filepath] = filepath LibRubyParser::PrismString.with_file(filepath) { |string| dump_common(string, ) } end
.dump_options(options) (private)
Convert the given options into a serialized options string.
# File 'lib/prism/ffi.rb', line 441
def ( ) template = +"" values = [] template << "L" if (filepath = [:filepath]) values.push(filepath.bytesize, filepath.b) template << "A*" else values << 0 end template << "l" values << .fetch(:line, 1) template << "L" if (encoding = [:encoding]) name = encoding.is_a?(Encoding) ? encoding.name : encoding values.push(name.bytesize, name.b) template << "A*" else values << 0 end template << "C" values << ( .fetch(:frozen_string_literal, false) ? 1 : 0) template << "C" values << ( ) template << "C" values << ( [:version]) template << "C" values << ( [:encoding] == false ? 1 : 0) template << "C" values << ( .fetch(:main_script, false) ? 1 : 0) template << "C" values << ( .fetch(:partial_script, false) ? 1 : 0) template << "L" if (scopes = [:scopes]) values << scopes.length scopes.each do |scope| template << "L" values << scope.length scope.each do |local| name = local.name template << "L" values << name.bytesize template << "A*" values << name.b end end else values << 0 end values.pack(template) end
.dump_options_command_line(options) (private)
Return the value that should be dumped for the command_line option.
# File 'lib/prism/ffi.rb', line 409
def ( ) command_line = .fetch(:command_line, "") raise ArgumentError, "command_line must be a string" unless command_line.is_a?(String) command_line.each_char.inject(0) do |value, char| case char when "a" then value | 0b000001 when "e" then value | 0b000010 when "l" then value | 0b000100 when "n" then value | 0b001000 when "p" then value | 0b010000 when "x" then value | 0b100000 else raise ArgumentError, "invalid command_line option: #{char}" end end end
.dump_options_version(version) (private)
Return the value that should be dumped for the version option.
# File 'lib/prism/ffi.rb', line 427
def (version) case version when nil, "latest" 0 when /\A3\.3(\.\d+)?\z/ 1 when /\A3\.4(\.\d+)?\z/ 0 else raise ArgumentError, "invalid version: #{version}" end end
.lex(code, **options)
Mirror the lex
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 240
def lex(code, ** ) LibRubyParser::PrismString.with_string(code) { |string| lex_common(string, code, ) } end
.lex_common(string, code, options) (private)
# File 'lib/prism/ffi.rb', line 361
def lex_common(string, code, ) # :nodoc: serialized = LibRubyParser::PrismBuffer.with do |buffer| LibRubyParser.pm_serialize_lex(buffer.pointer, string.pointer, string.length, ( )) buffer.read end Serialize.load_tokens(Source.for(code), serialized) end
.lex_compat(source, **options) ⇒ LexCompat::Result
Returns a parse result whose value is an array of tokens that closely resembles the return value of Ripper.lex
. The main difference is that the :on_sp
token is not emitted.
For supported options, see .parse.
.lex_file(filepath, **options)
Mirror the lex_file
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 245
def lex_file(filepath, ** ) [:filepath] = filepath LibRubyParser::PrismString.with_file(filepath) { |string| lex_common(string, string.read, ) } end
.lex_ripper(source) ⇒ Array
This lexes with the Ripper lex. It drops any space events but otherwise returns the same tokens. Raises SyntaxError if the syntax in source is invalid.
.load(source, serialized) ⇒ ParseResult
Load the serialized AST using the source as a reference into a tree.
# File 'lib/prism.rb', line 65
def self.load(source, serialized) Serialize.load(source, serialized) end
.parse(code, **options)
Mirror the parse
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 251
def parse(code, ** ) LibRubyParser::PrismString.with_string(code) { |string| parse_common(string, code, ) } end
.parse_comments(code, **options)
Mirror the parse_comments
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 287
def parse_comments(code, ** ) LibRubyParser::PrismString.with_string(code) { |string| parse_comments_common(string, code, ) } end
.parse_comments_common(string, code, options) (private)
# File 'lib/prism/ffi.rb', line 375
def parse_comments_common(string, code, ) # :nodoc: LibRubyParser::PrismBuffer.with do |buffer| LibRubyParser.pm_serialize_parse_comments(buffer.pointer, string.pointer, string.length, ( )) source = Source.for(code) loader = Serialize::Loader.new(source, buffer.read) loader.load_header loader.load_encoding loader.load_start_line loader.load_comments end end
.parse_common(string, code, options) (private)
# File 'lib/prism/ffi.rb', line 370
def parse_common(string, code, ) # :nodoc: serialized = dump_common(string, ) Prism.load(code, serialized) end
.parse_failure?(code, **options) ⇒ Boolean
Mirror the parse_failure?
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 316
def parse_failure?(code, ** ) !parse_success?(code, ** ) end
.parse_file(filepath, **options)
Mirror the parse_file
API by using the serialization API. This uses native strings instead of Ruby strings because it allows us to use mmap when it is available.
# File 'lib/prism/ffi.rb', line 258
def parse_file(filepath, ** ) [:filepath] = filepath LibRubyParser::PrismString.with_file(filepath) { |string| parse_common(string, string.read, ) } end
.parse_file_comments(filepath, **options)
Mirror the parse_file_comments
API by using the serialization API. This uses native strings instead of Ruby strings because it allows us to use mmap when it is available.
# File 'lib/prism/ffi.rb', line 294
def parse_file_comments(filepath, ** ) [:filepath] = filepath LibRubyParser::PrismString.with_file(filepath) { |string| parse_comments_common(string, string.read, ) } end
.parse_file_failure?(filepath, **options) ⇒ Boolean
Mirror the parse_file_failure?
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 327
def parse_file_failure?(filepath, ** ) !parse_file_success?(filepath, ** ) end
.parse_file_success?(filepath, **options) ⇒ Boolean
Mirror the parse_file_success?
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 321
def parse_file_success?(filepath, ** ) [:filepath] = filepath LibRubyParser::PrismString.with_file(filepath) { |string| parse_file_success_common(string, ) } end
.parse_file_success_common(string, options) (private)
# File 'lib/prism/ffi.rb', line 404
def parse_file_success_common(string, ) # :nodoc: LibRubyParser.pm_parse_success_p(string.pointer, string.length, ( )) end
.parse_lex(code, **options)
Mirror the parse_lex
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 300
def parse_lex(code, ** ) LibRubyParser::PrismString.with_string(code) { |string| parse_lex_common(string, code, ) } end
.parse_lex_common(string, code, options) (private)
# File 'lib/prism/ffi.rb', line 389
def parse_lex_common(string, code, ) # :nodoc: LibRubyParser::PrismBuffer.with do |buffer| LibRubyParser.pm_serialize_parse_lex(buffer.pointer, string.pointer, string.length, ( )) source = Source.for(code) loader = Serialize::Loader.new(source, buffer.read) tokens = loader.load_tokens node, comments, magic_comments, data_loc, errors, warnings = loader.load_nodes tokens.each { |token,| token.value.force_encoding(loader.encoding) } ParseLexResult.new([node, tokens], comments, magic_comments, data_loc, errors, warnings, source) end end
.parse_lex_file(filepath, **options)
Mirror the parse_lex_file
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 305
def parse_lex_file(filepath, ** ) [:filepath] = filepath LibRubyParser::PrismString.with_file(filepath) { |string| parse_lex_common(string, string.read, ) } end
.parse_stream(stream, **options)
Mirror the parse_stream
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 264
def parse_stream(stream, ** ) LibRubyParser::PrismBuffer.with do |buffer| source = +"" callback = -> (string, size, _) { raise "Expected size to be >= 0, got: #{size}" if size <= 0 if !(line = stream.gets(size - 1)).nil? source << line string.write_string("#{line}\x00", line.bytesize + 1) end } # In the pm_serialize_parse_stream function it accepts a pointer to the # IO object as a void* and then passes it through to the callback as the # third argument, but it never touches it itself. As such, since we have # access to the IO object already through the closure of the lambda, we # can pass a null pointer here and not worry. LibRubyParser.pm_serialize_parse_stream(buffer.pointer, nil, callback, ( )) Prism.load(source, buffer.read) end end
.parse_success?(code, **options) ⇒ Boolean
Mirror the parse_success?
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 311
def parse_success?(code, ** ) LibRubyParser::PrismString.with_string(code) { |string| parse_file_success_common(string, ) } end
.profile(source, **options)
Mirror the profile
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 332
def profile(source, ** ) LibRubyParser::PrismString.with_string(source) do |string| LibRubyParser::PrismBuffer.with do |buffer| LibRubyParser.pm_serialize_parse(buffer.pointer, string.pointer, string.length, ( )) nil end end end
.profile_file(filepath, **options)
Mirror the profile_file
API by using the serialization API.
# File 'lib/prism/ffi.rb', line 342
def profile_file(filepath, ** ) LibRubyParser::PrismString.with_file(filepath) do |string| LibRubyParser::PrismBuffer.with do |buffer| [:filepath] = filepath LibRubyParser.pm_serialize_parse(buffer.pointer, string.pointer, string.length, ( )) nil end end end