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

# 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 constant is set by reading the result of calling pm_version.

### Public Class Methods

dump (source, **options)
Source

    # File lib/prism/ffi.rb, line 238
    def dump(source, **options)
      LibRubyParser::PrismString.with_string(source) { |string| dump_common(string, options) }
    end

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

dump_file (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 243
    def dump_file(filepath, **options)
      options[:filepath] = filepath
      LibRubyParser::PrismString.with_file(filepath) { |string| dump_common(string, options) }
    end

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

lex (code, **options)
Source

    # File lib/prism/ffi.rb, line 249
    def lex(code, **options)
      LibRubyParser::PrismString.with_string(code) { |string| lex_common(string, code, options) }
    end

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

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

    # File lib/prism.rb, line 48
    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`. The main difference is that the `:on_sp` token is not emitted.

For supported options, see `Prism::parse`.

lex_file (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 254
    def lex_file(filepath, **options)
      options[:filepath] = filepath
      LibRubyParser::PrismString.with_file(filepath) { |string| lex_common(string, string.read, options) }
    end

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

Prism::lex_ripper(source) → Array
Source

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

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.

Prism::load(source, serialized, freeze) → ParseResult
Source

    # File lib/prism.rb, line 66
    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 (code, **options)
Source

    # File lib/prism/ffi.rb, line 260
    def parse(code, **options)
      LibRubyParser::PrismString.with_string(code) { |string| parse_common(string, code, options) }
    end

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

parse_comments (code, **options)
Source

    # File lib/prism/ffi.rb, line 298
    def parse_comments(code, **options)
      LibRubyParser::PrismString.with_string(code) { |string| parse_comments_common(string, code, options) }
    end

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

parse_failure? (code, **options)
Source

    # File lib/prism/ffi.rb, line 327
    def parse_failure?(code, **options)
      !parse_success?(code, **options)
    end

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

parse_file (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 267
    def parse_file(filepath, **options)
      options[:filepath] = filepath
      LibRubyParser::PrismString.with_file(filepath) { |string| parse_common(string, string.read, options) }
    end

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.

parse_file_comments (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 305
    def parse_file_comments(filepath, **options)
      options[:filepath] = filepath
      LibRubyParser::PrismString.with_file(filepath) { |string| parse_comments_common(string, string.read, options) }
    end

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.

parse_file_failure? (filepath, **options)
Source

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

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

parse_file_success? (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 332
    def parse_file_success?(filepath, **options)
      options[:filepath] = filepath
      LibRubyParser::PrismString.with_file(filepath) { |string| parse_file_success_common(string, options) }
    end

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

parse_lex (code, **options)
Source

    # File lib/prism/ffi.rb, line 311
    def parse_lex(code, **options)
      LibRubyParser::PrismString.with_string(code) { |string| parse_lex_common(string, code, options) }
    end

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

parse_lex_file (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 316
    def parse_lex_file(filepath, **options)
      options[:filepath] = filepath
      LibRubyParser::PrismString.with_file(filepath) { |string| parse_lex_common(string, string.read, options) }
    end

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

parse_stream (stream, **options)
Source

    # File lib/prism/ffi.rb, line 273
    def parse_stream(stream, **options)
      LibRubyParser::PrismBuffer.with do |buffer|
        source = +""
        callback = -> (string, size, _) {
          raise "Expected size to be >= 0, got: #{size}" if size <= 0

          if !(line = stream.gets(size - 1)).nil?
            source << line
            string.write_string("#{line}\x00", line.bytesize + 1)
          end
        }

        eof_callback = -> (_) { stream.eof?  }

        # In the pm_serialize_parse_stream function it accepts a pointer to the
        # IO object as a void* and then passes it through to the callback as the
        # third argument, but it never touches it itself. As such, since we have
        # access to the IO object already through the closure of the lambda, we
        # can pass a null pointer here and not worry.
        LibRubyParser.pm_serialize_parse_stream(buffer.pointer, nil, callback, eof_callback, dump_options(options))
        Prism.load(source, buffer.read, options.fetch(:freeze, false))
      end
    end

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

parse_success? (code, **options)
Source

    # File lib/prism/ffi.rb, line 322
    def parse_success?(code, **options)
      LibRubyParser::PrismString.with_string(code) { |string| parse_file_success_common(string, options) }
    end

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

profile (source, **options)
Source

    # File lib/prism/ffi.rb, line 343
    def profile(source, **options)
      LibRubyParser::PrismString.with_string(source) do |string|
        LibRubyParser::PrismBuffer.with do |buffer|
          LibRubyParser.pm_serialize_parse(buffer.pointer, string.pointer, string.length, dump_options(options))
          nil
        end
      end
    end

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

profile_file (filepath, **options)
Source

    # File lib/prism/ffi.rb, line 353
    def profile_file(filepath, **options)
      LibRubyParser::PrismString.with_file(filepath) do |string|
        LibRubyParser::PrismBuffer.with do |buffer|
          options[:filepath] = filepath
          LibRubyParser.pm_serialize_parse(buffer.pointer, string.pointer, string.length, dump_options(options))
          nil
        end
      end
    end

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

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

    # File lib/prism/parse_result.rb, line 908
    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.

### Private Class Methods

dump_options (options)
Source

    # File lib/prism/ffi.rb, line 441
    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.is_a?(Encoding) ? encoding.name : encoding
        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 << dump_options_version(options[:version])

      template << "C"
      values << (options[:encoding] == false ? 1 : 0)

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

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

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

      template << "L"
      if (scopes = options[:scopes])
        values << scopes.length

        scopes.each do |scope|
          locals = nil
          forwarding = 0

          case scope
          when Array
            locals = scope
          when Scope
            locals = scope.locals

            scope.forwarding.each do |forward|
              case forward
              when :*     then forwarding |= 0x1
              when :**    then forwarding |= 0x2
              when :&     then forwarding |= 0x4
              when :"..." then forwarding |= 0x8
              else raise ArgumentError, "invalid forwarding value: #{forward}"
              end
            end
          else
            raise TypeError, "wrong argument type #{scope.class.inspect} (expected Array or Prism::Scope)"
          end

          template << "L"
          values << locals.length

          template << "C"
          values << forwarding

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

Convert the given options into a serialized options string.

dump_options_command_line (options)
Source

    # File lib/prism/ffi.rb, line 407
    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

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

dump_options_version (version)
Source

    # File lib/prism/ffi.rb, line 425
    def dump_options_version(version)
      case version
      when nil, "latest"
        0 # Handled in pm_parser_init
      when /\A3\.3(\.\d+)?\z/
        1
      when /\A3\.4(\.\d+)?\z/
        2
      when /\A3\.5(\.\d+)?\z/
        3
      else
        raise ArgumentError, "invalid version: #{version}"
      end
    end

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