123456789_123456789_123456789_123456789_123456789_

Module: Prism

Overview

The Prism Ruby parser.

“Parsing Ruby is suddenly manageable!”

- You, hopefully

Constant Summary

Class Method Summary

Class Method Details

.dump(source, **options) ⇒ String

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

[ GitHub ] 

  


# File 'prism/extension.c', line 260



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

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

#ifdef PRISM_DEBUG_MODE_BUILD
    free(dup);
#endif

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

    return value;
}


  








  

    .dump_file(filepath, **options)  ⇒ String   



  

    

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


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 292



static VALUE
dump_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };
    if (!file_options(argc, argv, &input, &options)) return Qnil;

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

    return value;
}


  








  

    .dump_options(options)   (private)
  



  

    

Convert the given options into a serialized options string.


  



  [ GitHub ]


  

  


# 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


  








  

    .lex(source, **options)  ⇒ Array   



  

    

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


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 556



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


  








  

    .lex_compat(source, **options)  ⇒ ParseResult   



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/prism.rb', line 46



def self.lex_compat(source, **options)
  LexCompat.new(source, **options).result
end


  








  

    .lex_file(filepath, **options)  ⇒ Array   



  

    

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


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 576



static VALUE
lex_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };
    if (!file_options(argc, argv, &input, &options)) return Qnil;

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

    return value;
}


  








  

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


  



  [ GitHub ]


  

  


# File 'lib/prism.rb', line 56



def self.lex_ripper(source)
  LexRipper.new(source).result
end


  








  

    .load(source, serialized)  ⇒ ParseResult   



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/prism.rb', line 64



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


  








  

    .parse(source, **options)  ⇒ ParseResult   



  

    

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


  • 

    filepath - the filepath of the source being parsed. This should be a
    


    string or nil
    

  • 

    encoding - the encoding of the source being parsed. This should be an
    


    encoding or nil
    

  • 

    line - the line number that the parse starts on. This should be an
    


    integer or nil. Note that this is 1-indexed.
    

  • 

    frozen_string_literal - whether or not the frozen string literal pragma
    


    has been set. This should be a boolean or nil.
    

  • 

    verbose - the current level of verbosity. This controls whether or not
    


    the parser emits warnings. This should be a boolean or nil.
    

  • 

    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.
    



  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 643



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

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

#ifdef PRISM_DEBUG_MODE_BUILD
    free(dup);
#endif

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


  








  

    .parse_comments(source, **options)  ⇒ Array   



  

    

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


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 714



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


  








  

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



  

    

Returns true if the source parses with errors.


  



  [ GitHub ]


  

  


# File 'lib/prism.rb', line 72



def self.parse_failure?(source, **options)
  !parse_success?(source, **options)
end


  








  

    .parse_file(filepath, **options)  
  



  

    

Mirror the 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.


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 674



static VALUE
parse_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };
    if (!file_options(argc, argv, &input, &options)) return Qnil;

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

    return value;
}


  








  

    .parse_file_comments(filepath, **options)  
  



  

    

Mirror the 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.


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 734



static VALUE
parse_file_comments(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };
    if (!file_options(argc, argv, &input, &options)) return Qnil;

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

    return value;
}


  








  

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



  

    

Returns true if the file at filepath parses with errors.


  



  [ GitHub ]


  

  


# File 'lib/prism.rb', line 80



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


  








  

    .parse_file_success?(filepath, **options)  ⇒ Array   



  

    

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


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 845



static VALUE
parse_file_success_p(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };
    if (!file_options(argc, argv, &input, &options)) return Qnil;

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

    return result;
}


  








  

    .parse_lex(source, **options)  ⇒ ParseResult   



  

    

Parse the given string and return a ::Prism::ParseResult instance that contains a 2-element array, where the first element is the AST and the second element is an array of ::Prism::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 .parse or .lex.



For supported options, see .parse.


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 761



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


  








  

    .parse_lex_file(filepath, **options)  ⇒ ParseResult   



  

    

Parse the given file and return a ::Prism::ParseResult instance that contains a 2-element array, where the first element is the AST and the second element is an array of ::Prism::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 .parse_file or .lex_file.



For supported options, see .parse.


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 788



static VALUE
parse_lex_file(int argc, VALUE *argv, VALUE self) {
    pm_string_t input;
    pm_options_t options = { 0 };
    if (!file_options(argc, argv, &input, &options)) return Qnil;

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

    return value;
}


  








  

    .parse_success?(source, **options)  ⇒ Array   



  

    

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


  



  [ GitHub ]


  

  


# File 'prism/extension.c', line 825



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