Traverse

traverse functions:

  astranaut_traverse:map(map_fun(), form(), Opts :: opts()) -> 
    traverse_return(node()) | parse_transform_return(node()).
    
  astranaut_traverse:reduce(reduce_fun(), state(), form(), Opts :: opts()) -> 
    traverse_return(state()).
    
  astranaut_traverse:map_with_state(map_state_fun(), state(), form(), Opts :: opts()) -> 
    traverse_return(node()) | parse_transform_return(node()).
    
  astranaut_traverse:mapfold(mapfold_fun(), state(), form(), Opts :: opts()) -> 
    traverse_return({form(), state()}).

arguments

  form()    :: node() | [node()].
  node()    :: erlang ast node.
  state()   :: any().

traverse_fun()

  map_fun()       :: (node(), Attr :: attr()) -> TraverseFunReturn :: traverse_fun_return(node()).
  reduce_fun()    :: (node(), state(), Attr :: attr()) -> TraverseFunReturn :: traverse_fun_return(state()).
  map_state_fun() :: (node(), state(), Attr :: attr()) -> TraverseFunReturn :: traverse_fun_return(node()).
  mapfold_fun()   :: (node(), state(), Attr :: attr()) -> TraverseFunReturn :: traverse_fun_return({node(), state()}).

Attr

  attr() :: #{step => Step :: step(), node :: NodeType :: node_type(), attribute :: Attribute}.

Step

  which traverse step while traversing, very useful while traverse_style() in opts() is all.

  step()  :: pre | post | leaf. 

NodeType

  ast node type.

  node_type() :: form | attribute | pattern | expression | guard. 

Attribute

  if NodeType is attribute, Attribute is name of attribute, or Attribute does not exists.

TraverseFunReturn

  traverse_fun_return(A) :: A | {error, error()} | continue | {continue, A} |
                            #{'__struct__' => astranaut_traverse_fun_return, 
                              node := Node :: node(), state := State :: state(), continue := Continue :: boolean(),
                              error := error(), warning := error(), errors := [error()], warnings => [error()]}.

Node

  node transformed to new node in traverse_walk_fun(), default is node() provided in traverse_walk_fun().

State

  state used in traverse_walk_fun(), default is state() provided in traverse_walk_fun().

Continue

  if Continue is true or traverse_fun_return(A) is continue | {continue, A}, and Step of attr() is pre
  skip traverse children of currrent node and go to next node, nothing affected when Step of attr() is leaf or post.

error()

  error()   :: #{'__struct__' => astranaut_traverse_error, 
                 line := Line :: integer(), module := Module :: module(), reason => Reason :: term()} | 
                {Line, Module, Reason} | {Line, Reason} | Reason.

Line

  expected error line, default is line of node in traverse_walk_fun().

Module

  error formatter module which provide format_error/1, default is formatter option in opts().

Opts

  opts()    :: {traverse => TraverseStyle :: traverse_style(), parse_transform => ParseTransform :: boolean(),
                node => FormType :: form_type(), formatter => Formatter}.

Formatter

  error formatter module which provide format_error/1, default is astranaut_traverse.

ParseTransform

  traverse_return(node()) will be transformed to parse_transform_return()
  which could directed used as return in parse_transform/2, useful in map/3, map_with_state/3.

NodeType

  node_type(). if from() is incomplete erlang ast, this should be provided to help generate node_type() in attr().
  if top node is function or attribute, default top node_type() in attr() is form.
  else, default top node_type() in attr() is expression.

TraverseStyle

  pre | post | all | leaf.

traverse_return(Return)

  traverse_return(Return) :: Return | {ok, Return, Errors :: traverse_return_error(), Warnings :: traverse_return_error()} | 
                             {error, Errors, Warnings}.

parse_transform_return(Return)

  parse_transform_return(Return) :: Return | {warning, Return, Warnings :: prase_transform_error()} |
                                    {error, Errors :: parse_transform_error(), Warnings}.

ReturnError

  traverse_return_error() :: [{Line :: line(), Module :: module(), Reason :: term()}].
  parse_transform_error() :: [{File, traverse_retrun_error()}].

Structs

  astranaut_traverse:traverse_fun_return(#{}) -> traverse_fun_return(). 
  astranaut_traverse:traverse_error(#{}) -> error(). 

Advanced

  powerful map_m function if you famillar with monad.

  astranaut_traverse:map_m((A, attr()) => monad(A), map_m_opts()) -> monad(A).