ST.Parser (st_parser v0.3.0)

View Source

User-friendly API for the Session Type Parser.

This module provides convenient functions for parsing session type expressions into their corresponding ST data structures. It serves as the main entry point for using the parser in application code.

Session Type Syntax

The syntax supported by this parser includes:

  • Input (external choice): &Role:{ Label1(PayloadType).Continuation, Label2(PayloadType).Continuation }
  • Output (internal choice): +Role:{ Label1(PayloadType).Continuation, Label2(PayloadType).Continuation }
  • End (termination): end

Payload Types

The following payload types are supported:

  • Basic types: string, number, boolean, unit
  • List types: type[] (e.g., string[], number[])
  • Tuple types: (type1, type2, ...) (e.g., (string, number), (boolean[], unit))

Example Session Type

&Server:{
  GetData(string).+Server:{
    Data((string, number[])).end
  }
}

This session type describes a protocol where:

  1. The user sends a GetData message with a string payload to the server
  2. The server responds with a Data message containing a tuple of a string and a number array
  3. The session then terminates

Summary

Types

Result of a failed parse operation containing an error message.

Result of a parse operation, either success or failure.

Result of a successful parse operation.

Result of a parse_type operation, either success or failure.

Result of a successful parse_type operation.

Functions

Parses a complete session type expression.

Parses a session type expression, raising an exception on failure.

Parses a payload type expression.

Parses a payload type expression, raising an exception on failure.

Types

parse_error()

@type parse_error() :: {:error, String.t()}

Result of a failed parse operation containing an error message.

parse_result()

@type parse_result() :: parse_success() | parse_error()

Result of a parse operation, either success or failure.

parse_success()

@type parse_success() :: {:ok, ST.t()}

Result of a successful parse operation.

type_result()

@type type_result() :: type_success() | parse_error()

Result of a parse_type operation, either success or failure.

type_success()

@type type_success() :: {:ok, ST.payload_type()}

Result of a successful parse_type operation.

Functions

parse(input)

@spec parse(String.t()) :: parse_result()

Parses a complete session type expression.

Returns {:ok, parsed_type} on success or {:error, reason} on failure.

Parameters

  • input: String containing the session type expression to parse

Examples

iex> ST.Parser.parse("&Server:{ Ack(unit).end }")
{:ok, %ST.SIn{
  from: :server,
  branches: [
    %ST.SBranch{
      label: :ack,
      payload: :unit,
      continue_as: %ST.SEnd{}
    }
  ]
}}

iex> ST.Parser.parse("+Client:{ Request(string).end }")
{:ok, %ST.SOut{
  to: :client,
  branches: [
    %ST.SBranch{
      label: :request,
      payload: :binary,
      continue_as: %ST.SEnd{}
    }
  ]
}}

iex> ST.Parser.parse("end")
{:ok, %ST.SEnd{}}

parse!(input)

@spec parse!(String.t()) :: ST.t() | no_return()

Parses a session type expression, raising an exception on failure.

Returns the parsed type directly on success.

Parameters

  • input: String containing the session type expression to parse

Examples

iex> ST.Parser.parse!("end")
%ST.SEnd{}

iex> ST.Parser.parse!("invalid")
** (RuntimeError) Parser error: ...

Raises

parse_type(input)

@spec parse_type(String.t()) :: type_result()

Parses a payload type expression.

Returns {:ok, parsed_type} on success or {:error, reason} on failure.

Parameters

  • input: String containing the payload type expression to parse

Examples

iex> ST.Parser.parse_type("string")
{:ok, :binary}

iex> ST.Parser.parse_type("boolean[]")
{:ok, {:list, [:boolean]}}

iex> ST.Parser.parse_type("(string, number)")
{:ok, {:tuple, [:binary, :number]}}

parse_type!(input)

@spec parse_type!(String.t()) :: ST.payload_type() | no_return()

Parses a payload type expression, raising an exception on failure.

Returns the parsed type directly on success.

Parameters

  • input: String containing the payload type expression to parse

Examples

iex> ST.Parser.parse_type!("string")
:binary

iex> ST.Parser.parse_type!("invalid_type")
** (RuntimeError) Type parser error: ...

Raises