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.

Parameters:

  • buffer (Parser::Source::Buffer)
  • backend (Symbol) (defaults to: :auto) —

    :auto, :parser, or :prism

Returns:

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


42
43
44
45
 
# File 'lib/docscribe/parsing.rb', line 42

def parse_buffer(buffer, backend: :auto)
  parser = parser_for(backend: backend)
  parser.parse(buffer)
end

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

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

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:

  • (Array<(Parser::AST::Node, Array)>) 


53
54
55
56
 
# File 'lib/docscribe/parsing.rb', line 53

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) ⇒ Array<(Parser::AST::Node, Array)>

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

Parameters:

  • buffer (Parser::Source::Buffer)
  • backend (Symbol) (defaults to: :auto) —

    :auto, :parser, or :prism

Returns:

  • (Array<(Parser::AST::Node, Array)>) 


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

def parse_with_comments_buffer(buffer, backend: :auto)
  parser = parser_for(backend: backend)
  parser.parse_with_comments(buffer)
end