module Ruby::Prism
The Ruby::Prism Ruby parser.
“Parsing Ruby is suddenly manageable!” - You, hopefully
Ruby::Prism is the prism parser built into the interpreter, i.e., the very parser that parsed the running program.
Its API and behavior will be identical to the version of prism bundled with this Ruby. In most cases, use the prism gem instead. Use Ruby::Prism only when you need the very parser of the running interpreter.
Ruby::Prism is autoloaded when it is first referenced. Do not require "ruby/prism" explicitly, as it does not work well with Ruby::Box for a technical reason.
Constants
- BACKEND
-
The C extension is the default backend on CRuby.
- VERSION
-
The version of the prism library.
Public Class Methods
static VALUE
dump(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
const uint8_t *source = (const uint8_t *) RSTRING_PTR(string);
size_t length = RSTRING_LEN(string);
#ifdef PRISM_BUILD_DEBUG
char* dup = xmalloc(length);
memcpy(dup, source, length);
source = (const uint8_t *) dup;
#endif
result_t result = dump_input(source, length, options, NULL);
#ifdef PRISM_BUILD_DEBUG
#ifdef xfree_sized
xfree_sized(dup, length);
#else
xfree(dup);
#endif
#endif
pm_options_free(options);
return result_get(result);
}
Dump the AST corresponding to the given string to a string. For supported options, see Prism.parse.
static VALUE
dump_file(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = dump_input(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath));
pm_source_free(src);
pm_options_free(options);
return result_get(result);
}
Dump the AST corresponding to the given file to a string. For supported options, see Prism.parse.
(Method | UnboundMethod | Proc | Thread::Backtrace::Location callable) → Node?Source
# File lib/ruby/prism.rb, line 94 def self.find(callable) NodeFind.find(callable) end
Given a Method, UnboundMethod, Proc, or Thread::Backtrace::Location, returns the Ruby::Prism node representing it. On CRuby, this uses node_id for an exact match. On other implementations, it falls back to best-effort matching by source location line number.
static VALUE
lex(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
result_t result = parse_lex_input((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, NULL, false);
pm_options_free(options);
return result_get(result);
}
Return a LexResult instance that contains an array of Token instances corresponding to the given string. For supported options, see Prism.parse.
(String source, **untyped options) → LexCompat::ResultSource
# File lib/ruby/prism.rb, line 74 def self.lex_compat(source, **options) LexCompat.new(source, **options).result # steep:ignore end
Returns a parse result whose value is an array of tokens that closely resembles the return value of Ripper.lex.
For supported options, see Ruby::Prism.parse.
static VALUE
lex_file(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = parse_lex_input(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath), false);
pm_source_free(src);
pm_options_free(options);
return result_get(result);
}
Return a LexResult instance that contains an array of Token instances corresponding to the given file. For supported options, see Prism.parse.
(String source, String serialized, ?bool freeze) → ParseResultSource
# File lib/ruby/prism.rb, line 84 def self.load(source, serialized, freeze = false) Serialize.load_parse(source, serialized, freeze) end
Load the serialized AST using the source as a reference into a tree.
static VALUE
parse(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
const uint8_t *source = (const uint8_t *) RSTRING_PTR(string);
size_t length = RSTRING_LEN(string);
#ifdef PRISM_BUILD_DEBUG
char* dup = xmalloc(length);
memcpy(dup, source, length);
source = (const uint8_t *) dup;
#endif
result_t result = parse_input(source, length, options, NULL);
#ifdef PRISM_BUILD_DEBUG
#ifdef xfree_sized
xfree_sized(dup, length);
#else
xfree(dup);
#endif
#endif
pm_options_free(options);
return result_get(result);
}
Parse the given string and return a ParseResult instance. The options that are supported are:
-
attach_comments- whether or not to attach each comment to the node that owns it. When set, the comments on the result are sorted by start offset. This should be a boolean or nil. -
command_line- either nil or a string of the various options that were set on the command line. Valid values are combinations of “a”, “l”, “n”, “p”, and “x”. -
encoding- the encoding of the source being parsed. This should be an encoding or nil. -
filepath- the filepath of the source being parsed. This should be a string or nil. -
freeze- whether or not to deeply freeze the AST. This should be a boolean or nil. -
frozen_string_literal- whether or not the frozen string literal pragma has been set. This should be a boolean or nil. -
line- the line number that the parse starts on. This should be an integer or nil. Note that this is 1-indexed. -
main_script- a boolean indicating whether or not the source being parsed is the main script being run by the interpreter. This controls whether or not shebangs are parsed for additional flags and whether or not the parser will attempt to find a matching shebang if the first one does not contain the word “ruby”. -
partial_script- when the file being parsed is considered a “partial” script, jumps will not be marked as errors if they are not contained within loops/blocks. This is used in the case that you’re parsing a script that you know will be embedded inside another script later, but you do not have that context yet. For example, when parsing anERBtemplate that will be evaluated inside another script. -
raise_error- either nil, true, or a symbol indicating that an error should be raised if the source contains any errors. The message of the error will include the source of the lines that contain errors when possible, and the value of this option controls how those lines are formatted. Valid values are:plain(no formatting),:style(bold formatting), and:color(bold and color formatting). Whentrueis given, the formatting is determined by whether or not$stderris a terminal and whether or not theNO_COLORenvironment variable is set, mirroring the behavior of CRuby itself. Syntax-level errors raiseSyntaxError, argument-level errors raiseArgumentError, and load-level errors raiseLoadError. Note that this option is honored by every API that accepts these options, including predicates likePrism.parse_success?, which will raise instead of returning a boolean when the source contains errors. -
scopes- the locals that are in scope surrounding the code that is being parsed. This should be an array of arrays of symbols or nil. Scopes are ordered from the outermost scope to the innermost one. -
version- the version of Ruby syntax that prism should used to parse Ruby code. By default prism parses with the syntax version nearest to the current Ruby that is running (which you can trigger withnilor"nearest"): the running version if prism supports it, otherwise the closest version that it does support. You may also restrict the syntax to a specific version of Ruby, e.g., with"3.3.0". To parse with exactly the same syntax version that the current Ruby is running useversion: "current", which raisesPrism::CurrentVersionErrorif prism does not support it. To parse with the latest version of Ruby syntax that prism supports, useversion: "latest". RaisesArgumentErrorif the version is not currently supported byPrism.
static VALUE
parse_comments(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
result_t result = parse_input_comments((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, NULL);
pm_options_free(options);
return result_get(result);
}
Parse the given string and return an array of Comment objects. For supported options, see Prism.parse.
static VALUE
parse_failure_p(int argc, VALUE *argv, VALUE self) {
return RTEST(parse_success_p(argc, argv, self)) ? Qfalse : Qtrue;
}
Parse the given string and return true if it parses with errors. For supported options, see Prism.parse.
static VALUE
parse_file(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = parse_input(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath));
pm_source_free(src);
pm_options_free(options);
return result_get(result);
}
Parse the given file and return a ParseResult instance. For supported options, see Prism.parse.
static VALUE
parse_file_comments(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = parse_input_comments(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath));
pm_source_free(src);
pm_options_free(options);
return result_get(result);
}
Parse the given file and return an array of Comment objects. For supported options, see Prism.parse.
static VALUE
parse_file_failure_p(int argc, VALUE *argv, VALUE self) {
return RTEST(parse_file_success_p(argc, argv, self)) ? Qfalse : Qtrue;
}
Parse the given file and return true if it parses with errors. For supported options, see Prism.parse.
static VALUE
parse_file_success_p(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = parse_input_success_p(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath));
pm_source_free(src);
pm_options_free(options);
return result_get(result);
}
Parse the given file and return true if it parses without errors. For supported options, see Prism.parse.
static VALUE
parse_lex(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
result_t result = parse_lex_input((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, NULL, true);
pm_options_free(options);
return result_get(result);
}
Parse the given string and return a ParseLexResult instance that contains a 2-element array, where the first element is the AST and the second element is an array of 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 Prism.parse or Prism.lex.
For supported options, see Prism.parse.
static VALUE
parse_lex_file(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = parse_lex_input(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath), true);
pm_source_free(src);
pm_options_free(options);
return result_get(result);
}
Parse the given file and return a ParseLexResult instance that contains a 2-element array, where the first element is the AST and the second element is an array of 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 Prism.parse_file or Prism.lex_file.
For supported options, see Prism.parse.
static VALUE
parse_stream(int argc, VALUE *argv, VALUE self) {
VALUE stream;
VALUE keywords;
rb_scan_args(argc, argv, "1:", &stream, &keywords);
pm_options_t *options = pm_options_new();
extract_options(options, Qnil, keywords);
pm_source_t *src = pm_source_stream_new((void *) stream, parse_stream_fgets, parse_stream_eof);
pm_arena_t *arena = pm_arena_new();
pm_parser_t *parser;
pm_node_t *node = pm_parse_stream(&parser, arena, src, options);
result_t result = check_raise_error_option(parser, options, NULL);
if (result.type == RESULT_OK) {
rb_encoding *encoding = rb_enc_find(pm_parser_encoding_name(parser));
VALUE comments = rb_ary_new_capa(pm_parser_comments_size(parser));
VALUE attachments, ranges;
parser_attachments_new(parser, &attachments, &ranges);
VALUE source = pm_source_new(parser, encoding, comments, attachments, ranges, pm_options_freeze(options));
parser_comments(parser, comments, source, pm_options_freeze(options));
parser_attachments(parser, comments, attachments, ranges, pm_options_freeze(options));
VALUE value = pm_ast_new(parser, node, encoding, source, pm_options_freeze(options));
result = result_ok(parse_result_create(rb_cPrismParseResult, parser, value, encoding, source, pm_options_freeze(options)));
}
pm_source_free(src);
pm_parser_free(parser);
pm_arena_free(arena);
pm_options_free(options);
return result_get(result);
}
Parse the given object that responds to gets and return a ParseResult instance. The options that are supported are the same as Prism.parse.
static VALUE
parse_success_p(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
result_t result = parse_input_success_p((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, NULL);
pm_options_free(options);
return result_get(result);
}
Parse the given string and return true if it parses without errors. For supported options, see Prism.parse.
static VALUE
profile(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE string = string_options(argc, argv, options);
result_t result = profile_input((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, NULL);
pm_options_free(options);
result_get(result);
return Qnil;
}
Parse the given string and return nothing. This method is meant to allow profilers to avoid the overhead of reifying the AST to Ruby. For supported options, see Prism.parse.
static VALUE
profile_file(int argc, VALUE *argv, VALUE self) {
pm_options_t *options = pm_options_new();
VALUE encoded_filepath;
pm_source_t *src = file_options(argc, argv, options, &encoded_filepath);
result_t result = profile_input(pm_source_source(src), pm_source_length(src), options, rb_enc_get(encoded_filepath));
pm_source_free(src);
pm_options_free(options);
result_get(result);
return Qnil;
}
Parse the given file and return nothing. This method is meant to allow profilers to avoid the overhead of reifying the AST to Ruby. For supported options, see Prism.parse.
Source
# File lib/ruby/prism/parse_result.rb, line 1233 def self.scope(locals: [], forwarding: []) Scope.new(locals, forwarding) end
Create a new scope with the given locals and forwarding options that is suitable for passing into one of the Ruby::Prism.* methods that accepts the scopes option.