module Prism - Documentation for Ruby 3.3

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

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
VERSION

  The version constant is set by reading the result of calling pm_version.

### Public Class Methods

dump(code, **options) click to toggle source

Mirror the `Prism.dump` API by using the serialization API.

    # File lib/prism/ffi.rb, line 182
    def dump(code, **options)
      LibRubyParser::PrismBuffer.with do |buffer|
        LibRubyParser.pm_serialize_parse(buffer.pointer, code, code.bytesize, dump_options(options))
        buffer.read
      end
    end

dump_file(filepath, **options) click to toggle source

Mirror the `Prism.dump_file` API by using the serialization API.

    # File lib/prism/ffi.rb, line 190
    def dump_file(filepath, **options)
      LibRubyParser::PrismString.with(filepath) do |string|
        dump(string.read, **options, filepath: filepath)
      end
    end

lex(code, **options) click to toggle source

Mirror the `Prism.lex` API by using the serialization API.

    # File lib/prism/ffi.rb, line 197
    def lex(code, **options)
      LibRubyParser::PrismBuffer.with do |buffer|
        LibRubyParser.pm_serialize_lex(buffer.pointer, code, code.bytesize, dump_options(options))
        Serialize.load_tokens(Source.new(code), buffer.read)
      end
    end

Prism::lex_compat(source, **options) → ParseResult 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 46
    def self.lex_compat(source, **options)
      LexCompat.new(source, **options).result
    end

lex_file(filepath, **options) click to toggle source

Mirror the `Prism.lex_file` API by using the serialization API.

    # File lib/prism/ffi.rb, line 205
    def lex_file(filepath, **options)
      LibRubyParser::PrismString.with(filepath) do |string|
        lex(string.read, **options, filepath: filepath)
      end
    end

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 56
    def self.lex_ripper(source)
      LexRipper.new(source).result
    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 64
    def self.load(source, serialized)
      Serialize.load(source, serialized)
    end

parse(code, **options) click to toggle source

Mirror the `Prism.parse` API by using the serialization API.

    # File lib/prism/ffi.rb, line 212
    def parse(code, **options)
      Prism.load(code, dump(code, **options))
    end

parse_comments(code, **options) click to toggle source

Mirror the `Prism.parse_comments` API by using the serialization API.

    # File lib/prism/ffi.rb, line 226
    def parse_comments(code, **options)
      LibRubyParser::PrismBuffer.with do |buffer|
        LibRubyParser.pm_serialize_parse_comments(buffer.pointer, code, code.bytesize, dump_options(options))

        source = Source.new(code)
        loader = Serialize::Loader.new(source, buffer.read)

        loader.load_header
        loader.load_encoding
        loader.load_start_line
        loader.load_comments
      end
    end

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

Returns true if the source parses with errors.

    # File lib/prism.rb, line 72
    def self.parse_failure?(source, **options)
      !parse_success?(source, **options)
    end

parse_file(filepath, **options) click to toggle source

Mirror the `Prism.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 219
    def parse_file(filepath, **options)
      LibRubyParser::PrismString.with(filepath) do |string|
        parse(string.read, **options, filepath: filepath)
      end
    end

parse_file_comments(filepath, **options) click to toggle source

Mirror the `Prism.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 243
    def parse_file_comments(filepath, **options)
      LibRubyParser::PrismString.with(filepath) do |string|
        parse_comments(string.read, **options, filepath: filepath)
      end
    end

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

Returns true if the file at filepath parses with errors.

    # File lib/prism.rb, line 80
    def self.parse_file_failure?(filepath, **options)
      !parse_file_success?(filepath, **options)
    end

parse_file_success?(filepath, **options) click to toggle source

Mirror the `Prism.parse_file_success?` API by using the serialization API.

    # File lib/prism/ffi.rb, line 278
    def parse_file_success?(filepath, **options)
      LibRubyParser::PrismString.with(filepath) do |string|
        parse_success?(string.read, **options, filepath: filepath)
      end
    end

parse_lex(code, **options) click to toggle source

Mirror the `Prism.parse_lex` API by using the serialization API.

    # File lib/prism/ffi.rb, line 250
    def parse_lex(code, **options)
      LibRubyParser::PrismBuffer.with do |buffer|
        LibRubyParser.pm_serialize_parse_lex(buffer.pointer, code, code.bytesize, dump_options(options))

        source = Source.new(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) }

        ParseResult.new([node, tokens], comments, magic_comments, data_loc, errors, warnings, source)
      end
    end

parse_lex_file(filepath, **options) click to toggle source

Mirror the `Prism.parse_lex_file` API by using the serialization API.

    # File lib/prism/ffi.rb, line 266
    def parse_lex_file(filepath, **options)
      LibRubyParser::PrismString.with(filepath) do |string|
        parse_lex(string.read, **options, filepath: filepath)
      end
    end

parse_success?(code, **options) click to toggle source

Mirror the `Prism.parse_success?` API by using the serialization API.

    # File lib/prism/ffi.rb, line 273
    def parse_success?(code, **options)
      LibRubyParser.pm_parse_success_p(code, code.bytesize, dump_options(options))
    end

### 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 287
    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 << (options.fetch(:verbose, true) ? 0 : 1)

      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