module Prism - Documentation for Ruby 4.1
Description: module Prism: The Prism Ruby parser.
Keywords: ruby,module,Prism

🔍

No recent searches

# module Prism

The `Prism` Ruby parser.

“Parsing Ruby is suddenly manageable!” - You, hopefully

### Constants

BACKEND

  The C extension is the default backend on CRuby.

VERSION

  The version of the prism library.

### Public Class Methods

dump(source, **options) → String
Source

    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

        VALUE value = dump_input(source, length, options);
        if (pm_options_freeze(options)) rb_obj_freeze(value);

    #ifdef PRISM_BUILD_DEBUG
    #ifdef xfree_sized
        xfree_sized(dup, length);
    #else
        xfree(dup);
    #endif
    #endif

        pm_options_free(options);

        return value;
    }

Dump the AST corresponding to the given string to a string. For supported options, see `Prism.parse`.

dump_file(filepath, **options) → String
Source

    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);

        VALUE value = dump_input(pm_source_source(src), pm_source_length(src), options);
        pm_source_free(src);
        pm_options_free(options);

        return value;
    }

Dump the AST corresponding to the given file to a string. For supported options, see `Prism.parse`.

find (callable, rubyvm: !!defined?(RubyVM))
Source

    # File lib/prism.rb, line 94
    def self.find(callable, rubyvm: !!defined?(RubyVM))
      NodeFind.find(callable, rubyvm)
    end

Given a Method, `UnboundMethod`, `Proc`, or `Thread::Backtrace::Location`, returns the `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.

lex(source, **options) → LexResult
Source

    static VALUE
    lex(int argc, VALUE *argv, VALUE self) {
        pm_options_t *options = pm_options_new();
        VALUE string = string_options(argc, argv, options);

        VALUE result = parse_lex_input((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, false);
        pm_options_free(options);

        return result;
    }

Return a `LexResult` instance that contains an array of `Token` instances corresponding to the given string. For supported options, see `Prism.parse`.

lex_compat(source, **options) → LexCompat::Result
Source

    # File lib/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 `Prism.parse`.

lex_file(filepath, **options) → LexResult
Source

    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);

        VALUE value = parse_lex_input(pm_source_source(src), pm_source_length(src), options, false);
        pm_source_free(src);
        pm_options_free(options);

        return value;
    }

Return a `LexResult` instance that contains an array of `Token` instances corresponding to the given file. For supported options, see `Prism.parse`.

load(source, serialized, freeze) → ParseResult
Source

    # File lib/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.

parse(source, **options) → ParseResult
Source

    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

        VALUE value = parse_input(source, length, options);

    #ifdef PRISM_BUILD_DEBUG
    #ifdef xfree_sized
        xfree_sized(dup, length);
    #else
        xfree(dup);
    #endif
    #endif

        pm_options_free(options);
        return value;
    }

Parse the given string and return a `ParseResult` instance. The options that are supported are:

- `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 an `ERB` template that will be evaluated inside another script.

- `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 assumes you want to parse with the latest version of Ruby syntax (which you can trigger with `nil` or `"latest"`). You may also restrict the syntax to a specific version of Ruby, e.g., with `"3.3.0"`. To parse with the same syntax version that the current Ruby is running use `version: "current"`. To parse with the nearest version to the current Ruby that is running, use `version: "nearest"`. Raises `ArgumentError` if the version is not currently supported by `Prism`.

parse_comments(source, **options) → Array
Source

    static VALUE
    parse_comments(int argc, VALUE *argv, VALUE self) {
        pm_options_t *options = pm_options_new();
        VALUE string = string_options(argc, argv, options);

        VALUE result = parse_input_comments((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options);
        pm_options_free(options);

        return result;
    }

Parse the given string and return an array of `Comment` objects. For supported options, see `Prism.parse`.

parse_failure?(source, **options) → bool
Source

    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`.

parse_file(filepath, **options) → ParseResult
Source

    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);

        VALUE value = parse_input(pm_source_source(src), pm_source_length(src), options);
        pm_source_free(src);
        pm_options_free(options);

        return value;
    }

Parse the given file and return a `ParseResult` instance. For supported options, see `Prism.parse`.

parse_file_comments(filepath, **options) → Array
Source

    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);

        VALUE value = parse_input_comments(pm_source_source(src), pm_source_length(src), options);
        pm_source_free(src);
        pm_options_free(options);

        return value;
    }

Parse the given file and return an array of `Comment` objects. For supported options, see `Prism.parse`.

parse_file_failure?(filepath, **options) → bool
Source

    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`.

parse_file_success?(filepath, **options) → bool
Source

    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);

        VALUE result = parse_input_success_p(pm_source_source(src), pm_source_length(src), options);
        pm_source_free(src);
        pm_options_free(options);

        return result;
    }

Parse the given file and return true if it parses without errors. For supported options, see `Prism.parse`.

parse_lex(source, **options) → ParseLexResult
Source

    static VALUE
    parse_lex(int argc, VALUE *argv, VALUE self) {
        pm_options_t *options = pm_options_new();
        VALUE string = string_options(argc, argv, options);

        VALUE value = parse_lex_input((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options, true);
        pm_options_free(options);

        return value;
    }

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`.

parse_lex_file(filepath, **options) → ParseLexResult
Source

    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);

        VALUE value = parse_lex_input(pm_source_source(src), pm_source_length(src), options, true);
        pm_source_free(src);
        pm_options_free(options);

        return value;
    }

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`.

parse_stream(stream, **options) → ParseResult
Source

    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);
        rb_encoding *encoding = rb_enc_find(pm_parser_encoding_name(parser));

        VALUE source = pm_source_new(parser, encoding, pm_options_freeze(options));
        VALUE value = pm_ast_new(parser, node, encoding, source, pm_options_freeze(options));
        VALUE result = 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;
    }

Parse the given object that responds to `gets` and return a `ParseResult` instance. The options that are supported are the same as `Prism.parse`.

parse_success?(source, **options) → bool
Source

    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);

        VALUE result = parse_input_success_p((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options);
        pm_options_free(options);

        return result;
    }

Parse the given string and return true if it parses without errors. For supported options, see `Prism.parse`.

profile(source, **options) → nil
Source

    static VALUE
    profile(int argc, VALUE *argv, VALUE self) {
        pm_options_t *options = pm_options_new();
        VALUE string = string_options(argc, argv, options);

        profile_input((const uint8_t *) RSTRING_PTR(string), RSTRING_LEN(string), options);
        pm_options_free(options);

        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`.

profile_file(filepath, **options) → nil
Source

    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);

        profile_input(pm_source_source(src), pm_source_length(src), options);
        pm_source_free(src);
        pm_options_free(options);

        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`.

scope (locals: [], forwarding: [])
Source

    # File lib/prism/parse_result.rb, line 1208
    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 Prism.* methods that accepts the `scopes` option.