Module: Docscribe::Parsing

Defined in:
lib/docscribe/parsing.rb

Overview

Parser backend selection for Docscribe.

Docscribe always works with parser-gem-compatible AST nodes (‘Parser::AST::Node`) and parser source locations (`Parser::Source::*`) because rewriting relies on `Parser::Source::TreeRewriter`.

On Ruby 3.4+, Prism can parse newer syntax before the parser gem fully supports it, so Docscribe can use Prism and translate the result into parser-gem-compatible nodes.

Backends:

  • ‘:parser` => parser gem

  • ‘:prism` => Prism + translation

  • ‘:auto` => choose based on runtime Ruby version or env override

You can force a backend with:

  • ‘DOCSCRIBE_PARSER_BACKEND=parser`

  • ‘DOCSCRIBE_PARSER_BACKEND=prism`

Class Method Summary collapse

Class Method Details

.parse(code, file: '(docscribe)', backend: :auto) ⇒ Parser::AST::Node?

Parse source code into a parser-gem-compatible AST.

Parameters:

  • code (String) —

    Ruby source

  • file (String) (defaults to: '(docscribe)') —

    source name used for parser locations

  • backend (Symbol) (defaults to: :auto) —

    :auto, :parser, or :prism

Returns:

  • (Parser::AST::Node, nil) 


32
33
34
35
 
# File 'lib/docscribe/parsing.rb', line 32

def parse(code, file: '(docscribe)', backend: :auto)
  buffer = Parser::Source::Buffer.new(file, source: code)
  parse_buffer(buffer, backend: backend)
end

.parse_buffer(buffer, backend: :auto) ⇒ Parser::AST::Node?

Parse a prepared source buffer into a parser-gem-compatible AST.

Returns nil when the source cannot be parsed (syntax errors or internal parser crashes).

Parameters:

  • buffer (Parser::Source::Buffer) —

    prepared source buffer

  • backend (Symbol) (defaults to: :auto) —

    :auto, :parser, or :prism

Returns:

  • (Parser::AST::Node, nil) —

    if NoMethodError

  • (nil) —

    if NoMethodError

Raises:

  • (NoMethodError) 


47
48
49
50
51
52
53
54
 
# File 'lib/docscribe/parsing.rb', line 47

def parse_buffer(buffer, backend: :auto)
  parser = parser_for(backend: backend)
  return nil unless parser

  parser.parse(buffer)
rescue NoMethodError
  nil
end

.parse_with_comments(code, file: '(docscribe)', backend: :auto) ⇒ (Parser::AST::Node?, Array<Parser::Source::Comment>)?

Parse source code and also return comments when supported by the backend.

Returns nil when the source cannot be parsed.

Parameters:

  • code (String) —

    Ruby source

  • file (String) (defaults to: '(docscribe)') —

    source name used for parser locations

  • backend (Symbol) (defaults to: :auto) —

    :auto, :parser, or :prism

Returns:

  • ((Parser::AST::Node?, Array<Parser::Source::Comment>), nil) 


64
65
66
67
 
# File 'lib/docscribe/parsing.rb', line 64

def parse_with_comments(code, file: '(docscribe)', backend: :auto)
  buffer = Parser::Source::Buffer.new(file, source: code)
  parse_with_comments_buffer(buffer, backend: backend)
end

.parse_with_comments_buffer(buffer, backend: :auto) ⇒ (Parser::AST::Node?, Array<Parser::Source::Comment>)?

Parse a prepared source buffer and also return comments when supported by the backend.

Returns nil when the source cannot be parsed.

Parameters:

  • buffer (Parser::Source::Buffer) —

    prepared source buffer

  • backend (Symbol) (defaults to: :auto) —

    :auto, :parser, or :prism

Returns:

  • ((Parser::AST::Node?, Array<Parser::Source::Comment>), nil) —

    if NoMethodError

  • (nil) —

    if NoMethodError

Raises:

  • (NoMethodError) 


78
79
80
81
82
83
84
85
 
# File 'lib/docscribe/parsing.rb', line 78

def parse_with_comments_buffer(buffer, backend: :auto)
  parser = parser_for(backend: backend)
  return nil unless parser

  parser.parse_with_comments(buffer)
rescue NoMethodError
  nil
end