Module: Prism

Defined in:
lib/prism.rb,
lib/prism/dsl.rb,
lib/prism/ffi.rb,
lib/prism/node.rb,
lib/prism/pack.rb,
lib/prism/pattern.rb,
lib/prism/visitor.rb,
lib/prism/compiler.rb,
lib/prism/node_ext.rb,
lib/prism/serialize.rb,
lib/prism/dispatcher.rb,
lib/prism/lex_compat.rb,
lib/prism/reflection.rb,
lib/prism/relocation.rb,
lib/prism/dot_visitor.rb,
lib/prism/translation.rb,
lib/prism/parse_result.rb,
lib/prism/string_query.rb,
lib/prism/inspect_visitor.rb,
lib/prism/desugar_compiler.rb,
lib/prism/mutation_compiler.rb,
lib/prism/translation/parser.rb,
lib/prism/translation/ripper.rb,
lib/prism/parse_result/errors.rb,
lib/prism/translation/parser33.rb,
lib/prism/translation/parser34.rb,
lib/prism/parse_result/comments.rb,
lib/prism/parse_result/newlines.rb,
lib/prism/translation/ripper/sexp.rb,
lib/prism/translation/ruby_parser.rb,
lib/prism/translation/parser/lexer.rb,
lib/prism/translation/parser/compiler.rb,
ext/prism/api_pack.c,
ext/prism/extension.c

Overview

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

Defined Under Namespace

Modules: ArgumentsNodeFlags, ArrayNodeFlags, CallNodeFlags, DSL, EncodingFlags, IntegerBaseFlags, InterpolatedStringNodeFlags, KeywordHashNodeFlags, LoopFlags, NodeFlags, Pack, ParameterFlags, RangeFlags, Reflection, RegularExpressionFlags, Relocation, Serialize, ShareableConstantNodeFlags, StringFlags, SymbolFlags, Translation Classes: ASCIISource, AliasGlobalVariableNode, AliasMethodNode, AlternationPatternNode, AndNode, ArgumentsNode, ArrayNode, ArrayPatternNode, AssocNode, AssocSplatNode, BackReferenceReadNode, BasicVisitor, BeginNode, BlockArgumentNode, BlockLocalVariableNode, BlockNode, BlockParameterNode, BlockParametersNode, BreakNode, CallAndWriteNode, CallNode, CallOperatorWriteNode, CallOrWriteNode, CallTargetNode, CapturePatternNode, CaseMatchNode, CaseNode, ClassNode, ClassVariableAndWriteNode, ClassVariableOperatorWriteNode, ClassVariableOrWriteNode, ClassVariableReadNode, ClassVariableTargetNode, ClassVariableWriteNode, CodeUnitsCache, Comment, ConstantAndWriteNode, ConstantOperatorWriteNode, ConstantOrWriteNode, ConstantPathAndWriteNode, ConstantPathNode, ConstantPathOperatorWriteNode, ConstantPathOrWriteNode, ConstantPathTargetNode, ConstantPathWriteNode, ConstantReadNode, ConstantTargetNode, ConstantWriteNode, DefNode, DefinedNode, DesugarCompiler, Dispatcher, DotVisitor, ElseNode, EmbDocComment, EmbeddedStatementsNode, EmbeddedVariableNode, EnsureNode, FalseNode, FindPatternNode, FlipFlopNode, FloatNode, ForNode, ForwardingArgumentsNode, ForwardingParameterNode, ForwardingSuperNode, GlobalVariableAndWriteNode, GlobalVariableOperatorWriteNode, GlobalVariableOrWriteNode, GlobalVariableReadNode, GlobalVariableTargetNode, GlobalVariableWriteNode, HashNode, HashPatternNode, IfNode, ImaginaryNode, ImplicitNode, ImplicitRestNode, InNode, IndexAndWriteNode, IndexOperatorWriteNode, IndexOrWriteNode, IndexTargetNode, InlineComment, InspectVisitor, InstanceVariableAndWriteNode, InstanceVariableOperatorWriteNode, InstanceVariableOrWriteNode, InstanceVariableReadNode, InstanceVariableTargetNode, InstanceVariableWriteNode, IntegerNode, InterpolatedMatchLastLineNode, InterpolatedRegularExpressionNode, InterpolatedStringNode, InterpolatedSymbolNode, InterpolatedXStringNode, ItLocalVariableReadNode, ItParametersNode, KeywordHashNode, KeywordRestParameterNode, LambdaNode, LexResult, LocalVariableAndWriteNode, LocalVariableOperatorWriteNode, LocalVariableOrWriteNode, LocalVariableReadNode, LocalVariableTargetNode, LocalVariableWriteNode, Location, MagicComment, MatchLastLineNode, MatchPredicateNode, MatchRequiredNode, MatchWriteNode, MissingNode, ModuleNode, MultiTargetNode, MultiWriteNode, MutationCompiler, NextNode, NilNode, NoKeywordsParameterNode, Node, NumberedParametersNode, NumberedReferenceReadNode, OptionalKeywordParameterNode, OptionalParameterNode, OrNode, ParametersNode, ParenthesesNode, ParseError, ParseLexResult, ParseResult, ParseWarning, Pattern, PinnedExpressionNode, PinnedVariableNode, PostExecutionNode, PreExecutionNode, ProgramNode, RangeNode, RationalNode, RedoNode, RegularExpressionNode, RequiredKeywordParameterNode, RequiredParameterNode, RescueModifierNode, RescueNode, RestParameterNode, Result, RetryNode, ReturnNode, SelfNode, ShareableConstantNode, SingletonClassNode, Source, SourceEncodingNode, SourceFileNode, SourceLineNode, SplatNode, StatementsNode, StringNode, StringQuery, SuperNode, SymbolNode, Token, TrueNode, UndefNode, UnlessNode, UntilNode, Visitor, WhenNode, WhileNode, XStringNode, YieldNode

Constant Summary collapse

VERSION =

The version of the prism library.

rb_str_new2(EXPECTED_PRISM_VERSION)
BACKEND =

The FFI backend is used on other Ruby implementations.

:FFI

Class Method Summary collapse

Class Method Details

.Prism::dump(source, **options) ⇒ String

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

Returns:

  • (String) 


229
230
231
 
# File 'lib/prism/ffi.rb', line 229

def dump(source, **options)
  LibRubyParser::PrismString.with_string(source) { |string| dump_common(string, options) }
end

.Prism::dump_file(filepath, **options) ⇒ String

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

Returns:

  • (String) 


234
235
236
237
 
# File 'lib/prism/ffi.rb', line 234

def dump_file(filepath, **options)
  options[:filepath] = filepath
  LibRubyParser::PrismString.with_file(filepath) { |string| dump_common(string, options) }
end

.Prism::lex(source, **options) ⇒ LexResult

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

Returns:



240
241
242
 
# File 'lib/prism/ffi.rb', line 240

def lex(code, **options)
  LibRubyParser::PrismString.with_string(code) { |string| lex_common(string, code, options) }
end

.lex_compat(source, **options) ⇒ Object

:call-seq:

Prism::lex_compat(source, **options) -> LexCompat::Result

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.



47
48
49
 
# 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) ⇒ LexResult

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

Returns:



245
246
247
248
 
# File 'lib/prism/ffi.rb', line 245

def lex_file(filepath, **options)
  options[:filepath] = filepath
  LibRubyParser::PrismString.with_file(filepath) { |string| lex_common(string, string.read, options) }
end

.lex_ripper(source) ⇒ Object

:call-seq:

Prism::lex_ripper(source) -> Array

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.



57
58
59
 
# File 'lib/prism.rb', line 57

def self.lex_ripper(source)
  LexRipper.new(source).result # steep:ignore
end

.load(source, serialized) ⇒ Object

:call-seq:

Prism::load(source, serialized) -> ParseResult

Load the serialized AST using the source as a reference into a tree.



65
66
67
 
# File 'lib/prism.rb', line 65

def self.load(source, serialized)
  Serialize.load(source, serialized)
end

.Prism::parse(source, **options) ⇒ ParseResult

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.

  • ‘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: RUBY_VERSION`. Raises ArgumentError if the version is not
currently supported by Prism.

Returns:



251
252
253
 
# File 'lib/prism/ffi.rb', line 251

def parse(code, **options)
  LibRubyParser::PrismString.with_string(code) { |string| parse_common(string, code, options) }
end

.Prism::parse_comments(source, **options) ⇒ Array

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

Returns:

  • (Array) 


287
288
289
 
# File 'lib/prism/ffi.rb', line 287

def parse_comments(code, **options)
  LibRubyParser::PrismString.with_string(code) { |string| parse_comments_common(string, code, options) }
end

.Prism::parse_failure?(source, **options) ⇒ Boolean

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

Returns:

  • (Boolean) 


316
317
318
 
# File 'lib/prism/ffi.rb', line 316

def parse_failure?(code, **options)
  !parse_success?(code, **options)
end

.Prism::parse_file(filepath, **options) ⇒ ParseResult

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

Returns:



258
259
260
261
 
# File 'lib/prism/ffi.rb', line 258

def parse_file(filepath, **options)
  options[:filepath] = filepath
  LibRubyParser::PrismString.with_file(filepath) { |string| parse_common(string, string.read, options) }
end

.Prism::parse_file_comments(filepath, **options) ⇒ Array

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

Returns:

  • (Array) 


294
295
296
297
 
# File 'lib/prism/ffi.rb', line 294

def parse_file_comments(filepath, **options)
  options[:filepath] = filepath
  LibRubyParser::PrismString.with_file(filepath) { |string| parse_comments_common(string, string.read, options) }
end

.Prism::parse_file_failure?(filepath, **options) ⇒ Boolean

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

Returns:

  • (Boolean) 


327
328
329
 
# File 'lib/prism/ffi.rb', line 327

def parse_file_failure?(filepath, **options)
  !parse_file_success?(filepath, **options)
end

.Prism::parse_file_success?(filepath, **options) ⇒ Boolean

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

Returns:

  • (Boolean) 


321
322
323
324
 
# File 'lib/prism/ffi.rb', line 321

def parse_file_success?(filepath, **options)
  options[:filepath] = filepath
  LibRubyParser::PrismString.with_file(filepath) { |string| parse_file_success_common(string, options) }
end

.Prism::parse_lex(source, **options) ⇒ ParseLexResult

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.

Returns:



300
301
302
 
# File 'lib/prism/ffi.rb', line 300

def parse_lex(code, **options)
  LibRubyParser::PrismString.with_string(code) { |string| parse_lex_common(string, code, options) }
end

.Prism::parse_lex_file(filepath, **options) ⇒ ParseLexResult

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.

Returns:



305
306
307
308
 
# File 'lib/prism/ffi.rb', line 305

def parse_lex_file(filepath, **options)
  options[:filepath] = filepath
  LibRubyParser::PrismString.with_file(filepath) { |string| parse_lex_common(string, string.read, options) }
end

.Prism::parse_stream(stream, **options) ⇒ ParseResult

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

Returns:



264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
 
# File 'lib/prism/ffi.rb', line 264

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
    }

    # 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, dump_options(options))
    Prism.load(source, buffer.read)
  end
end

.Prism::parse_success?(source, **options) ⇒ Boolean

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

Returns:

  • (Boolean) 


311
312
313
 
# File 'lib/prism/ffi.rb', line 311

def parse_success?(code, **options)
  LibRubyParser::PrismString.with_string(code) { |string| parse_file_success_common(string, options) }
end

.Prism::profile(source, **options) ⇒ nil

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.

Returns:

  • (nil) 


332
333
334
335
336
337
338
339
 
# File 'lib/prism/ffi.rb', line 332

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

.Prism::profile_file(filepath, **options) ⇒ nil

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.

Returns:

  • (nil) 


342
343
344
345
346
347
348
349
350
 
# File 'lib/prism/ffi.rb', line 342

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