module Prism

The Prism Ruby parser.

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

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/compiler.rb.erb if you are looking to modify the template

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/dispatcher.rb.erb if you are looking to modify the template

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/dsl.rb.erb if you are looking to modify the template

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/inspect_visitor.rb.erb if you are looking to modify the template

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/mutation_compiler.rb.erb if you are looking to modify the template

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/node.rb.erb if you are looking to modify the template

Here we are reopening the prism module to provide methods on nodes that aren’t templated and are meant as convenience methods.

typed: ignore

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/reflection.rb.erb if you are looking to modify the template

This file is generated by the templates/template.rb script and should not be modified manually. See templates/lib/prism/visitor.rb.erb if you are looking to modify the template

Constants

BACKEND: The C extension is the default backend on CRuby.
VERSION: The version of the prism library.

Public Class Methods

Prism::dump(source, **options) → String click to toggle source

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

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_BUILD_DEBUG
    size_t length = pm_string_length(&input);
    char* dup = xmalloc(length);
    memcpy(dup, pm_string_source(&input), length);
    pm_string_constant_init(&input, dup, length);
#endif

    VALUE value = dump_input(&input, &options);

#ifdef PRISM_BUILD_DEBUG
    xfree(dup);
#endif

    pm_string_free(&input);
    pm_options_free(&options);

    return value;
}

Prism::dump_file(filepath, **options) → String click to toggle source

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

static VALUE
dump_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };

    file_options(argc, argv, &input, &options);

    VALUE value = dump_input(&input, &options);
    pm_string_free(&input);
    pm_options_free(&options);

    return value;
}

Prism::lex(source, **options) → Array click to toggle source

Return an array of Token instances corresponding to the given string. For supported options, see Prism::parse.

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

Prism::lex_compat(source, **options) → LexCompat::Result click to toggle source

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 Prism::parse.

# File lib/prism.rb, line 47
def self.lex_compat(source, **options)
  LexCompat.new(source, **options).result # steep:ignore
end

Prism::lex_file(filepath, **options) → Array click to toggle source

Return an array of Token instances corresponding to the given file. For supported options, see Prism::parse.

static VALUE
lex_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };

    file_options(argc, argv, &input, &options);

    VALUE value = parse_lex_input(&input, &options, false);
    pm_string_free(&input);
    pm_options_free(&options);

    return value;
}

Prism::lex_ripper(source) → Array click to toggle source

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.

# File lib/prism.rb, line 57
def self.lex_ripper(source)
  LexRipper.new(source).result # steep:ignore
end

Prism::load(source, serialized) → ParseResult click to toggle source

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

Prism::parse(source, **options) → ParseResult click to toggle source

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.
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.
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. The supported values are "3.3.0" and "3.4.0".

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_BUILD_DEBUG
    size_t length = pm_string_length(&input);
    char* dup = xmalloc(length);
    memcpy(dup, pm_string_source(&input), length);
    pm_string_constant_init(&input, dup, length);
#endif

    VALUE value = parse_input(&input, &options);

#ifdef PRISM_BUILD_DEBUG
    xfree(dup);
#endif

    pm_string_free(&input);
    pm_options_free(&options);
    return value;
}

Prism::parse_comments(source, **options) → Array click to toggle source

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

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

Prism::parse_failure?(source, **options) → bool click to toggle source

Parse the given string and return true if it parses with errors. 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;
}

Prism::parse_file(filepath, **options) → ParseResult click to toggle source

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

static VALUE
parse_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };

    file_options(argc, argv, &input, &options);

    VALUE value = parse_input(&input, &options);
    pm_string_free(&input);
    pm_options_free(&options);

    return value;
}

Prism::parse_file_comments(filepath, **options) → Array click to toggle source

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

static VALUE
parse_file_comments(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };

    file_options(argc, argv, &input, &options);

    VALUE value = parse_input_comments(&input, &options);
    pm_string_free(&input);
    pm_options_free(&options);

    return value;
}

Prism::parse_file_failure?(filepath, **options) → bool click to toggle source

Parse the given file and return true if it parses with errors. 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;
}

Prism::parse_file_success?(filepath, **options) → bool click to toggle source

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

static VALUE
parse_file_success_p(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };

    file_options(argc, argv, &input, &options);

    VALUE result = parse_input_success_p(&input, &options);
    pm_string_free(&input);
    pm_options_free(&options);

    return result;
}

Prism::parse_lex(source, **options) → ParseResult click to toggle source

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 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(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;
}

Prism::parse_lex_file(filepath, **options) → ParseResult click to toggle source

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 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_lex_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };

    file_options(argc, argv, &input, &options);

    VALUE value = parse_lex_input(&input, &options, true);
    pm_string_free(&input);
    pm_options_free(&options);

    return value;
}

Prism::parse_stream(stream, **options) → ParseResult click to toggle source

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_stream(int argc, VALUE *argv, VALUE self) {
    VALUE stream;
    VALUE keywords;
    rb_scan_args(argc, argv, "1:", &stream, &keywords);

    pm_options_t options = { 0 };
    extract_options(&options, Qnil, keywords);

    pm_parser_t parser;
    pm_buffer_t buffer;

    pm_node_t *node = pm_parse_stream(&parser, &buffer, (void *) stream, parse_stream_fgets, &options);
    rb_encoding *encoding = rb_enc_find(parser.encoding->name);

    VALUE source = pm_source_new(&parser, encoding);
    VALUE value = pm_ast_new(&parser, node, encoding, source);
    VALUE result = parse_result_create(rb_cPrismParseResult, &parser, value, encoding, source);

    pm_node_destroy(&parser, node);
    pm_buffer_free(&buffer);
    pm_parser_free(&parser);

    return result;
}

Prism::parse_success?(source, **options) → bool click to toggle source

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

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

Private Class Methods

dump_options(options) click to toggle source

Convert the given options into a serialized options string.

# File lib/prism/ffi.rb, line 380
def dump_options(options)
  template = +""
  values = []

  template << "L"
  if (filepath = options[:filepath])
    values.push(filepath.bytesize, filepath.b)
    template << "A*"
  else
    values << 0
  end

  template << "l"
  values << options.fetch(:line, 1)

  template << "L"
  if (encoding = options[:encoding])
    name = encoding.name
    values.push(name.bytesize, name.b)
    template << "A*"
  else
    values << 0
  end

  template << "C"
  values << (options.fetch(:frozen_string_literal, false) ? 1 : 0)

  template << "C"
  values << dump_options_command_line(options)

  template << "C"
  values << { nil => 0, "3.3.0" => 1, "3.3.1" => 1, "3.4.0" => 0, "latest" => 0 }.fetch(options[:version])

  template << "L"
  if (scopes = options[: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) click to toggle source

Return the value that should be dumped for the command_line option.

# File lib/prism/ffi.rb, line 362
def dump_options_command_line(options)
  command_line = options.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