Skip to content

Latest commit

 

History

History
44 lines (35 loc) · 3.59 KB

ruby_api.md

File metadata and controls

44 lines (35 loc) · 3.59 KB
Raw

Ruby API

The prism gem provides a Ruby API for accessing the syntax tree.

For the most part, the API for accessing the tree mirrors that found in the Syntax Tree project. This means:

  • Walking the tree involves creating a visitor and passing it to the #accept method on any node in the tree
  • Nodes in the tree respond to named methods for accessing their children as well as #child_nodes
  • Nodes respond to the pattern matching interfaces #deconstruct and #deconstruct_keys

Every entry in config.yml will generate a Ruby class as well as the code that builds the nodes themselves. Creating a syntax tree involves calling one of the class methods on the Prism module. The full API is documented below.

API

  • Prism.dump(source) - parse the syntax tree corresponding to the given source string, and serialize it to a string
  • Prism.dump_file(filepath) - parse the syntax tree corresponding to the given source file and serialize it to a string
  • Prism.lex(source) - parse the tokens corresponding to the given source string and return them as an array within a parse result
  • Prism.lex_file(filepath) - parse the tokens corresponding to the given source file and return them as an array within a parse result
  • Prism.parse(source) - parse the syntax tree corresponding to the given source string and return it within a parse result
  • Prism.parse_file(filepath) - parse the syntax tree corresponding to the given source file and return it within a parse result
  • Prism.parse_stream(io) - parse the syntax tree corresponding to the source that is read out of the given IO object using the #gets method and return it within a parse result
  • Prism.parse_lex(source) - parse the syntax tree corresponding to the given source string and return it within a parse result, along with the tokens
  • Prism.parse_lex_file(filepath) - parse the syntax tree corresponding to the given source file and return it within a parse result, along with the tokens
  • Prism.load(source, serialized) - load the serialized syntax tree using the source as a reference into a syntax tree
  • Prism.parse_comments(source) - parse the comments corresponding to the given source string and return them
  • Prism.parse_file_comments(source) - parse the comments corresponding to the given source file and return them
  • Prism.parse_success?(source) - parse the syntax tree corresponding to the given source string and return true if it was parsed without errors
  • Prism.parse_file_success?(filepath) - parse the syntax tree corresponding to the given source file and return true if it was parsed without errors

Nodes

Once you have nodes in hand coming out of a parse result, there are a number of common APIs that are available on each instance. They are:

  • #accept(visitor) - a method that will immediately call visit_* to specialize for the node type
  • #child_nodes - a positional array of the child nodes of the node, with nil values for any missing children
  • #compact_child_nodes - a positional array of the child nodes of the node with no nil values
  • #copy(**keys) - a method that allows creating a shallow copy of the node with the given keys overridden
  • #deconstruct/#deconstruct_keys(keys) - the pattern matching interface for nodes
  • #inspect - a string representation that looks like the syntax tree of the node
  • #location - a Location object that describes the location of the node in the source file
  • #to_dot - convert the node's syntax tree into graphviz dot notation
  • #type - a symbol that represents the type of the node, useful for quick comparisons