Ruby: prism/prism.h File Reference

Ruby 3.4.4p34 (2025-05-14 revision a38531fd3f617bf734ef7d6c595325f69985ea1d)

Typedefs | Enumerations | Functions
prism.h File Reference

The main header file for the prism parser. More...

`#include "prism/defines.h"`
`#include "prism/util/pm_buffer.h"`
`#include "prism/util/pm_char.h"`
`#include "prism/util/pm_integer.h"`
`#include "prism/util/pm_memchr.h"`
`#include "prism/util/pm_strncasecmp.h"`
`#include "prism/util/pm_strpbrk.h"`
`#include "prism/ast.h"`
`#include "prism/diagnostic.h"`
`#include "prism/node.h"`
`#include "prism/options.h"`
`#include "prism/pack.h"`
`#include "prism/parser.h"`
`#include "prism/prettyprint.h"`
`#include "prism/regexp.h"`
`#include "prism/static_literals.h"`
`#include "prism/version.h"`
`#include <assert.h>`
`#include <errno.h>`
`#include <locale.h>`
`#include <math.h>`
`#include <stdarg.h>`
`#include <stdbool.h>`
`#include <stdint.h>`
`#include <stdio.h>`
`#include <stdlib.h>`
`#include <string.h>`
`#include <strings.h>`

Go to the source code of this file.

## Typedefs
typedef char * | pm_parse_stream_fgets_t(char *string, int size, void *stream)
| This function is used in pm_parse_stream to retrieve a line of input from a stream.

## Enumerations
enum | pm_string_query_t { PM_STRING_QUERY_ERROR = -1 , PM_STRING_QUERY_FALSE , PM_STRING_QUERY_TRUE }
| Represents the results of a slice query. More...

## Functions
PRISM_EXPORTED_FUNCTION const char * | pm_version (void)
| The prism version and the serialization format.
PRISM_EXPORTED_FUNCTION void | pm_parser_init (pm_parser_t *parser, const uint8_t *source, size_t size, const pm_options_t *options)
| Initialize a parser with the given start and end pointers.
PRISM_EXPORTED_FUNCTION void | pm_parser_register_encoding_changed_callback (pm_parser_t *parser, pm_encoding_changed_callback_t callback)
| Register a callback that will be called whenever prism changes the encoding it is using to parse based on the magic comment.
PRISM_EXPORTED_FUNCTION void | pm_parser_free (pm_parser_t *parser)
| Free any memory associated with the given parser.
PRISM_EXPORTED_FUNCTION pm_node_t * | pm_parse (pm_parser_t *parser)
| Initiate the parser with the given parser.
PRISM_EXPORTED_FUNCTION pm_node_t * | pm_parse_stream (pm_parser_t *parser, pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *fgets, const pm_options_t *options)
| Parse a stream of Ruby source and return the tree.
PRISM_EXPORTED_FUNCTION void | pm_serialize_parse_stream (pm_buffer_t *buffer, void *stream, pm_parse_stream_fgets_t *fgets, const char *data)
| Parse and serialize the AST represented by the source that is read out of the given stream into to the given buffer.
void | pm_serialize_comment_list (pm_parser_t *parser, pm_list_t *list, pm_buffer_t *buffer)
| Serialize the given list of comments to the given buffer.
void | pm_serialize_encoding (const pm_encoding_t *encoding, pm_buffer_t *buffer)
| Serialize the name of the encoding to the buffer.
void | pm_serialize_content (pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer)
| Serialize the encoding, metadata, nodes, and constant pool.
PRISM_EXPORTED_FUNCTION void | pm_serialize (pm_parser_t *parser, pm_node_t *node, pm_buffer_t *buffer)
| Serialize the AST represented by the given node to the given buffer.
PRISM_EXPORTED_FUNCTION void | pm_serialize_parse (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
| Parse the given source to the AST and dump the AST to the given buffer.
PRISM_EXPORTED_FUNCTION void | pm_serialize_parse_comments (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
| Parse and serialize the comments in the given source to the given buffer.
PRISM_EXPORTED_FUNCTION void | pm_serialize_lex (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
| Lex the given source and serialize to the given buffer.
PRISM_EXPORTED_FUNCTION void | pm_serialize_parse_lex (pm_buffer_t *buffer, const uint8_t *source, size_t size, const char *data)
| Parse and serialize both the AST and the tokens represented by the given source to the given buffer.
PRISM_EXPORTED_FUNCTION bool | pm_parse_success_p (const uint8_t *source, size_t size, const char *data)
| Parse the source and return true if it parses without errors or warnings.
PRISM_EXPORTED_FUNCTION const char * | pm_token_type_name (pm_token_type_t token_type)
| Returns a string representation of the given token type.
const char * | pm_token_type_human (pm_token_type_t token_type)
| Returns the human name of the given token type.
PRISM_EXPORTED_FUNCTION void | pm_dump_json (pm_buffer_t *buffer, const pm_parser_t *parser, const pm_node_t *node)
| Dump JSON to the given buffer.
PRISM_EXPORTED_FUNCTION pm_string_query_t | pm_string_query_local (const uint8_t *source, size_t length, const char *encoding_name)
| Check that the slice is a valid local variable name.
PRISM_EXPORTED_FUNCTION pm_string_query_t | pm_string_query_constant (const uint8_t *source, size_t length, const char *encoding_name)
| Check that the slice is a valid constant name.
PRISM_EXPORTED_FUNCTION pm_string_query_t | pm_string_query_method_name (const uint8_t *source, size_t length, const char *encoding_name)
| Check that the slice is a valid method name.

## Detailed Description

The main header file for the prism parser.

Definition in file prism.h.

## Typedef Documentation

## ◆ pm_parse_stream_fgets_t

typedef char * pm_parse_stream_fgets_t(char *string, int size, void *stream)

This function is used in pm_parse_stream to retrieve a line of input from a stream.

It closely mirrors that of fgets so that fgets can be used as the default implementation.

Definition at line 88 of file prism.h.

## Enumeration Type Documentation

## ◆ pm_string_query_t

enum pm_string_query_t

Represents the results of a slice query.

Enumerator
PM_STRING_QUERY_ERROR | Returned if the encoding given to a slice query was invalid.
PM_STRING_QUERY_FALSE | Returned if the result of the slice query is false.
PM_STRING_QUERY_TRUE | Returned if the result of the slice query is true.

Definition at line 240 of file prism.h.

## Function Documentation

## ◆ pm_dump_json()

PRISM_EXPORTED_FUNCTION void pm_dump_json | ( | pm_buffer_t * | buffer,
|  | const pm_parser_t * | parser,
|  | const pm_node_t * | node )

Dump JSON to the given buffer.

Parameters

  buffer | The buffer to serialize to.
  parser | The parser that parsed the node.
  node | The node to serialize.

Definition at line 3019 of file node.c.

## ◆ pm_parse()

PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse | ( | pm_parser_t * | parser | ) |

Initiate the parser with the given parser.

Parameters

  parser | The parser to use.

Returns
  The AST representing the source.

Initiate the parser with the given parser.

Definition at line 22608 of file prism.c.

## ◆ pm_parse_stream()

PRISM_EXPORTED_FUNCTION pm_node_t * pm_parse_stream | ( | pm_parser_t * | parser,
|  | pm_buffer_t * | buffer,
|  | void * | stream,
|  | pm_parse_stream_fgets_t * | fgets,
|  | const pm_options_t * | options )

Parse a stream of Ruby source and return the tree.

Parameters

  parser | The parser to use.
  buffer | The buffer to use.
  stream | The stream to parse.
  fgets | The function to use to read from the stream.
  options | The optional options to use when parsing.

Returns
  The AST representing the source.

Prism is designed around having the entire source in memory at once, but you can stream stdin in to Ruby so we need to support a streaming API.

Definition at line 22689 of file prism.c.

## ◆ pm_parse_success_p()

PRISM_EXPORTED_FUNCTION bool pm_parse_success_p | ( | const uint8_t * | source,
|  | size_t | size,
|  | const char * | data )

Parse the source and return true if it parses without errors or warnings.

Parameters

  source | The source to parse.
  size | The size of the source.
  data | The optional data to pass to the parser.

Returns
  True if the source parses without errors or warnings.

Definition at line 22712 of file prism.c.

## ◆ pm_parser_free()

PRISM_EXPORTED_FUNCTION void pm_parser_free | ( | pm_parser_t * | parser | ) |

Free any memory associated with the given parser.

Parameters

  parser | The parser to free.

Definition at line 22582 of file prism.c.

## ◆ pm_parser_init()

PRISM_EXPORTED_FUNCTION void pm_parser_init | ( | pm_parser_t * | parser,
|  | const uint8_t * | source,
|  | size_t | size,
|  | const pm_options_t * | options )

Initialize a parser with the given start and end pointers.

Parameters

  parser | The parser to initialize.
  source | The source to parse.
  size | The size of the source.
  options | The optional options to use when parsing.

Definition at line 22289 of file prism.c.

## ◆ pm_parser_register_encoding_changed_callback()

PRISM_EXPORTED_FUNCTION void pm_parser_register_encoding_changed_callback | ( | pm_parser_t * | parser,
|  | pm_encoding_changed_callback_t | callback )

Register a callback that will be called whenever prism changes the encoding it is using to parse based on the magic comment.

Parameters

  parser | The parser to register the callback with.
  callback | The callback to register.

Definition at line 22544 of file prism.c.

## ◆ pm_serialize()

PRISM_EXPORTED_FUNCTION void pm_serialize | ( | pm_parser_t * | parser,
|  | pm_node_t * | node,
|  | pm_buffer_t * | buffer )

Serialize the AST represented by the given node to the given buffer.

Parameters

  parser | The parser to serialize.
  node | The node to serialize.
  buffer | The buffer to serialize to.

Definition at line 22756 of file prism.c.

## ◆ pm_serialize_comment_list()

void pm_serialize_comment_list | ( | pm_parser_t * | parser,
|  | pm_list_t * | list,
|  | pm_buffer_t * | buffer )

Serialize the given list of comments to the given buffer.

Parameters

  parser | The parser to serialize.
  list | The list of comments to serialize.
  buffer | The buffer to serialize to.

Definition at line 2040 of file serialize.c.

Referenced by pm_serialize_comment_list(), and pm_serialize_parse_comments().

## ◆ pm_serialize_content()

void pm_serialize_content | ( | pm_parser_t * | parser,
|  | pm_node_t * | node,
|  | pm_buffer_t * | buffer )

Serialize the encoding, metadata, nodes, and constant pool.

Parameters

  parser | The parser to serialize.
  node | The node to serialize.
  buffer | The buffer to serialize to.

Serialize the encoding, metadata, nodes, and constant pool.

Definition at line 2133 of file serialize.c.

Referenced by pm_serialize(), pm_serialize_content(), pm_serialize_parse(), and pm_serialize_parse_stream().

## ◆ pm_serialize_encoding()

void pm_serialize_encoding | ( | const pm_encoding_t * | encoding,
|  | pm_buffer_t * | buffer )

Serialize the name of the encoding to the buffer.

Parameters

  encoding | The encoding to serialize.
  buffer | The buffer to serialize to.

Definition at line 2110 of file serialize.c.

Referenced by pm_serialize_encoding(), and pm_serialize_parse_comments().

## ◆ pm_serialize_lex()

PRISM_EXPORTED_FUNCTION void pm_serialize_lex | ( | pm_buffer_t * | buffer,
|  | const uint8_t * | source,
|  | size_t | size,
|  | const char * | data )

Lex the given source and serialize to the given buffer.

Parameters

  source | The source to lex.
  size | The size of the source.
  buffer | The buffer to serialize to.
  data | The optional data to pass to the lexer.

Definition at line 2207 of file serialize.c.

Referenced by pm_serialize_lex().

## ◆ pm_serialize_parse()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse | ( | pm_buffer_t * | buffer,
|  | const uint8_t * | source,
|  | size_t | size,
|  | const char * | data )

Parse the given source to the AST and dump the AST to the given buffer.

Parameters

  buffer | The buffer to serialize to.
  source | The source to parse.
  size | The size of the source.
  data | The optional data to pass to the parser.

Parse the given source to the AST and dump the AST to the given buffer.

Definition at line 22767 of file prism.c.

## ◆ pm_serialize_parse_comments()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse_comments | ( | pm_buffer_t * | buffer,
|  | const uint8_t * | source,
|  | size_t | size,
|  | const char * | data )

Parse and serialize the comments in the given source to the given buffer.

Parameters

  buffer | The buffer to serialize to.
  source | The source to parse.
  size | The size of the source.
  data | The optional data to pass to the parser.

Definition at line 22811 of file prism.c.

## ◆ pm_serialize_parse_lex()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse_lex | ( | pm_buffer_t * | buffer,
|  | const uint8_t * | source,
|  | size_t | size,
|  | const char * | data )

Parse and serialize both the AST and the tokens represented by the given source to the given buffer.

Parameters

  buffer | The buffer to serialize to.
  source | The source to parse.
  size | The size of the source.
  data | The optional data to pass to the parser.

Definition at line 2237 of file serialize.c.

Referenced by pm_serialize_parse_lex().

## ◆ pm_serialize_parse_stream()

PRISM_EXPORTED_FUNCTION void pm_serialize_parse_stream | ( | pm_buffer_t * | buffer,
|  | void * | stream,
|  | pm_parse_stream_fgets_t * | fgets,
|  | const char * | data )

Parse and serialize the AST represented by the source that is read out of the given stream into to the given buffer.

Parameters

  buffer | The buffer to serialize to.
  stream | The stream to parse.
  fgets | The function to use to read from the stream.
  data | The optional data to pass to the parser.

Definition at line 22790 of file prism.c.

## ◆ pm_string_query_constant()

PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_constant | ( | const uint8_t * | source,
|  | size_t | length,
|  | const char * | encoding_name )

Check that the slice is a valid constant name.

Parameters

  source | The source to check.
  length | The length of the source.
  encoding_name | The name of the encoding of the source.

Returns
  PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.

Definition at line 22936 of file prism.c.

## ◆ pm_string_query_local()

PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_local | ( | const uint8_t * | source,
|  | size_t | length,
|  | const char * | encoding_name )

Check that the slice is a valid local variable name.

Parameters

  source | The source to check.
  length | The length of the source.
  encoding_name | The name of the encoding of the source.

Returns
  PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.

Definition at line 22916 of file prism.c.

## ◆ pm_string_query_method_name()

PRISM_EXPORTED_FUNCTION pm_string_query_t pm_string_query_method_name | ( | const uint8_t * | source,
|  | size_t | length,
|  | const char * | encoding_name )

Check that the slice is a valid method name.

Parameters

  source | The source to check.
  length | The length of the source.
  encoding_name | The name of the encoding of the source.

Returns
  PM_STRING_QUERY_TRUE if the query is true, PM_STRING_QUERY_FALSE if the query is false, and PM_STRING_QUERY_ERROR if the encoding was invalid.

Definition at line 22956 of file prism.c.

## ◆ pm_token_type_human()

const char * pm_token_type_human | ( | pm_token_type_t | token_type | ) |

Returns the human name of the given token type.

Parameters

  token_type | The token type to convert to a human name.

Returns
  The human name of the given token type.

Definition at line 362 of file token_type.c.

Referenced by pm_token_type_human().

## ◆ pm_token_type_name()

PRISM_EXPORTED_FUNCTION const char * pm_token_type_name | ( | pm_token_type_t | token_type | ) |

Returns a string representation of the given token type.

Parameters

  token_type | The token type to convert to a string.

Returns
  A string representation of the given token type.

Definition at line 17 of file token_type.c.

Referenced by pm_token_type_name().

## ◆ pm_version()

PRISM_EXPORTED_FUNCTION const char * pm_version | ( | void |  | ) |

The prism version and the serialization format.

Returns
  The prism version as a constant string.

Definition at line 7 of file prism.c.