Module: Prism
Overview
The Prism Ruby parser.
“Parsing Ruby is suddenly manageable!”
- You, hopefully
Constant Summary
-
BACKEND =
The backend of the parser that prism is using to parse Ruby code. This can be either
:CEXT
or:FFI
. On runtimes that support C extensions, we default to:CEXT
. Otherwise we use:FFI
.: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) ⇒ String
Dump the AST corresponding to the given string to a string.
-
.dump_file(filepath, **options) ⇒ String
Dump the AST corresponding to the given file to a string.
-
.lex(source, **options) ⇒ Array
Return an array of
Token
instances corresponding to the given string. -
.lex_compat(source, **options) ⇒ ParseResult
Returns a parse result whose value is an array of tokens that closely resembles the return value of
Ripper.lex
. -
.lex_file(filepath, **options) ⇒ Array
Return an array of
Token
instances corresponding to the given file. -
.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(source, **options) ⇒ ParseResult
Parse the given string and return a
ParseResult
instance. -
.parse_comments(source, **options) ⇒ Array
Parse the given string and return an array of
Comment
objects. -
.parse_failure?(source, **options) ⇒ Boolean
Returns true if the source parses with errors.
-
.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
Returns true if the file at filepath parses with errors.
-
.parse_file_success?(filepath, **options) ⇒ Array
Parse the given file and return true if it parses without errors.
-
.parse_lex(source, **options) ⇒ ParseResult
Parse the given string and return a
ParseResult
instance that contains a 2-element array, where the first element is the AST and the second element is an array ofToken
instances. -
.parse_lex_file(filepath, **options) ⇒ ParseResult
Parse the given file and return a
ParseResult
instance that contains a 2-element array, where the first element is the AST and the second element is an array ofToken
instances. -
.parse_success?(source, **options) ⇒ Array
Parse the given string and return true if it parses without errors.
-
.dump_options(options)
private
Convert the given options into a serialized options string.
Class Method Details
.dump(source, **options) ⇒ String
Dump the AST corresponding to the given string to a string. For supported options, see .parse.
# File 'prism/extension.c', line 260
static VALUE dump(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; string_options(argc, argv, &input, &options); #ifdef PRISM_DEBUG_MODE_BUILD size_t length = pm_string_length(&input); char* dup = malloc(length); memcpy(dup, pm_string_source(&input), length); pm_string_constant_init(&input, dup, length); #endif VALUE value = dump_input(&input, &options); #ifdef PRISM_DEBUG_MODE_BUILD free(dup); #endif pm_string_free(&input); pm_options_free(&options); return value; }
.dump_file(filepath, **options) ⇒ String
Dump the AST corresponding to the given file to a string. For supported options, see .parse.
# File 'prism/extension.c', line 292
static VALUE dump_file(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; if (!file_options(argc, argv, &input, &options)) return Qnil; VALUE value = dump_input(&input, &options); pm_string_free(&input); pm_options_free(&options); return value; }
.dump_options(options) (private)
Convert the given options into a serialized options string.
# File 'lib/prism/ffi.rb', line 287
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.name 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 << ( .fetch(:verbose, true) ? 0 : 1) 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
.lex(source, **options) ⇒ Array
Return an array of ::Prism::Token
instances corresponding to the given string. For supported options, see .parse.
# File 'prism/extension.c', line 556
static VALUE lex(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; string_options(argc, argv, &input, &options); VALUE result = parse_lex_input(&input, &options, false); pm_string_free(&input); pm_options_free(&options); return result; }
.lex_compat(source, **options) ⇒ ParseResult
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) ⇒ Array
Return an array of ::Prism::Token
instances corresponding to the given file. For supported options, see .parse.
# File 'prism/extension.c', line 576
static VALUE lex_file(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; if (!file_options(argc, argv, &input, &options)) return Qnil; VALUE value = parse_lex_input(&input, &options, false); pm_string_free(&input); pm_options_free(&options); return value; }
.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 64
def self.load(source, serialized) Serialize.load(source, serialized) end
.parse(source, **options) ⇒ ParseResult
Parse the given string and return a ::Prism::ParseResult
instance. The options that are supported are:
-
filepath
- the filepath of the source being parsed. This should be astring or nil
-
encoding
- the encoding of the source being parsed. This should be anencoding or nil
-
line
- the line number that the parse starts on. This should be aninteger or nil. Note that this is 1-indexed.
-
frozen_string_literal
- whether or not the frozen string literal pragmahas been set. This should be a boolean or nil.
-
verbose
- the current level of verbosity. This controls whether or notthe parser emits warnings. This should be a boolean or nil.
-
scopes
- the locals that are in scope surrounding the code that is beingparsed. This should be an array of arrays of symbols or nil.
# File 'prism/extension.c', line 643
static VALUE parse(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; string_options(argc, argv, &input, &options); #ifdef PRISM_DEBUG_MODE_BUILD size_t length = pm_string_length(&input); char* dup = malloc(length); memcpy(dup, pm_string_source(&input), length); pm_string_constant_init(&input, dup, length); #endif VALUE value = parse_input(&input, &options); #ifdef PRISM_DEBUG_MODE_BUILD free(dup); #endif pm_string_free(&input); pm_options_free(&options); return value; }
.parse_comments(source, **options) ⇒ Array
Parse the given string and return an array of ::Prism::Comment
objects. For supported options, see .parse.
# File 'prism/extension.c', line 714
static VALUE parse_comments(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; string_options(argc, argv, &input, &options); VALUE result = parse_input_comments(&input, &options); pm_string_free(&input); pm_options_free(&options); return result; }
.parse_failure?(source, **options) ⇒ Boolean
Returns true if the source parses with errors.
# File 'lib/prism.rb', line 72
def self.parse_failure?(source, ** ) !parse_success?(source, ** ) 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 'prism/extension.c', line 674
static VALUE parse_file(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; if (!file_options(argc, argv, &input, &options)) return Qnil; VALUE value = parse_input(&input, &options); pm_string_free(&input); pm_options_free(&options); return value; }
.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 'prism/extension.c', line 734
static VALUE parse_file_comments(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; if (!file_options(argc, argv, &input, &options)) return Qnil; VALUE value = parse_input_comments(&input, &options); pm_string_free(&input); pm_options_free(&options); return value; }
.parse_file_failure?(filepath, **options) ⇒ Boolean
Returns true if the file at filepath parses with errors.
# File 'lib/prism.rb', line 80
def self.parse_file_failure?(filepath, ** ) !parse_file_success?(filepath, ** ) end
.parse_file_success?(filepath, **options) ⇒ Array
Parse the given file and return true if it parses without errors. For supported options, see .parse.
# File 'prism/extension.c', line 845
static VALUE parse_file_success_p(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; if (!file_options(argc, argv, &input, &options)) return Qnil; VALUE result = parse_input_success_p(&input, &options); pm_string_free(&input); pm_options_free(&options); return result; }
.parse_lex(source, **options) ⇒ ParseResult
Parse the given string and return a ::Prism::ParseResult
instance that contains a 2-element array, where the first element is the AST and the second element is an array of ::Prism::Token
instances.
This API is only meant to be used in the case where you need both the AST and the tokens. If you only need one or the other, use either .parse or .lex.
For supported options, see .parse.
# File 'prism/extension.c', line 761
static VALUE parse_lex(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; string_options(argc, argv, &input, &options); VALUE value = parse_lex_input(&input, &options, true); pm_string_free(&input); pm_options_free(&options); return value; }
.parse_lex_file(filepath, **options) ⇒ ParseResult
Parse the given file and return a ::Prism::ParseResult
instance that contains a 2-element array, where the first element is the AST and the second element is an array of ::Prism::Token
instances.
This API is only meant to be used in the case where you need both the AST and the tokens. If you only need one or the other, use either .parse_file or .lex_file.
For supported options, see .parse.
# File 'prism/extension.c', line 788
static VALUE parse_lex_file(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; if (!file_options(argc, argv, &input, &options)) return Qnil; VALUE value = parse_lex_input(&input, &options, true); pm_string_free(&input); pm_options_free(&options); return value; }
.parse_success?(source, **options) ⇒ Array
Parse the given string and return true if it parses without errors. For supported options, see .parse.
# File 'prism/extension.c', line 825
static VALUE parse_success_p(int argc, VALUE *argv, VALUE self) { pm_string_t input; pm_options_t options = { 0 }; string_options(argc, argv, &input, &options); VALUE result = parse_input_success_p(&input, &options); pm_string_free(&input); pm_options_free(&options); return result; }