org.parboiled.support
Interface ValueStack<V>

Type Parameters:
V - the type of the value objects
All Superinterfaces:
java.lang.Iterable<V>
All Known Implementing Classes:
DebuggingValueStack, DefaultValueStack

public interface ValueStack<V>
extends java.lang.Iterable<V>

A ValueStack is a stack implementation for parser values. The current state of the stack can be saved and restored with the methods takeSnapshot() and restoreSnapshot(Object) ()}, whose implementations should be super efficient since they are being used extensively during a parsing run. A ValueStack also serves as an Iterable over the current stack values (the values are being provided with the last value (on top of the stack) first).


Method Summary
 void clear()
          Clears all values.
 void dup()
          Duplicates the top value.
 boolean isEmpty()
          Determines whether the stack is empty.
 V peek()
          Returns the value at the top of the stack without removing it.
 V peek(int down)
          Returns the value the given number of elements below the top of the stack without removing it.
 void poke(int down, V value)
          Replaces the element the given number of elements below the current top of the stack.
 void poke(V value)
          Replaces the current top value with the given value.
 V pop()
          Removes the value at the top of the stack and returns it.
 V pop(int down)
          Removes the value the given number of elements below the top of the stack.
 void push(int down, V value)
          Inserts the given value a given number of elements below the current top of the stack.
 void push(V value)
          Pushes the given value onto the stack.
 void pushAll(java.lang.Iterable<V> values)
          Pushes all given elements onto the stack (in the order as given).
 void pushAll(V firstValue, V... moreValues)
          Pushes all given elements onto the stack (in the order as given).
 void restoreSnapshot(java.lang.Object snapshot)
          Restores the stack state as previously returned by takeSnapshot().
 int size()
          Returns the number of elements currently on the stack.
 void swap()
          Swaps the top two stack values.
 void swap3()
          Reverses the order of the top 3 stack values.
 void swap4()
          Reverses the order of the top 4 stack values.
 void swap5()
          Reverses the order of the top 5 stack values.
 void swap6()
          Reverses the order of the top 5 stack values.
 java.lang.Object takeSnapshot()
          Returns an object representing the current state of the stack.
 
Methods inherited from interface java.lang.Iterable
iterator
 

Method Detail

isEmpty

boolean isEmpty()
Determines whether the stack is empty.

Returns:
true if empty

size

int size()
Returns the number of elements currently on the stack.

Returns:
the number of elements

clear

void clear()
Clears all values.


takeSnapshot

java.lang.Object takeSnapshot()
Returns an object representing the current state of the stack. This cost of running this operation is negligible and independent from the size of the stack.

Returns:
an object representing the current state of the stack

restoreSnapshot

void restoreSnapshot(java.lang.Object snapshot)
Restores the stack state as previously returned by takeSnapshot(). This cost of running this operation is negligible and independent from the size of the stack.

Parameters:
snapshot - a snapshot object previously returned by takeSnapshot()

push

void push(V value)
Pushes the given value onto the stack. Equivalent to push(0, value).

Parameters:
value - the value

push

void push(int down,
          V value)
Inserts the given value a given number of elements below the current top of the stack.

Parameters:
down - the number of elements to skip before inserting the value (0 being equivalent to push(value))
value - the value
Throws:
java.lang.IllegalArgumentException - if the stack does not contain enough elements to perform this operation

pushAll

void pushAll(V firstValue,
             V... moreValues)
Pushes all given elements onto the stack (in the order as given).

Parameters:
firstValue - the first value
moreValues - the other values

pushAll

void pushAll(java.lang.Iterable<V> values)
Pushes all given elements onto the stack (in the order as given).

Parameters:
values - the values

pop

V pop()
Removes the value at the top of the stack and returns it.

Returns:
the current top value
Throws:
java.lang.IllegalArgumentException - if the stack is empty

pop

V pop(int down)
Removes the value the given number of elements below the top of the stack.

Parameters:
down - the number of elements to skip before removing the value (0 being equivalent to pop())
Returns:
the value
Throws:
java.lang.IllegalArgumentException - if the stack does not contain enough elements to perform this operation

peek

V peek()
Returns the value at the top of the stack without removing it.

Returns:
the current top value
Throws:
java.lang.IllegalArgumentException - if the stack is empty

peek

V peek(int down)
Returns the value the given number of elements below the top of the stack without removing it.

Parameters:
down - the number of elements to skip (0 being equivalent to peek())
Returns:
the value
Throws:
java.lang.IllegalArgumentException - if the stack does not contain enough elements to perform this operation

poke

void poke(V value)
Replaces the current top value with the given value. Equivalent to poke(0, value).

Parameters:
value - the value
Throws:
java.lang.IllegalArgumentException - if the stack is empty

poke

void poke(int down,
          V value)
Replaces the element the given number of elements below the current top of the stack.

Parameters:
down - the number of elements to skip before replacing the value (0 being equivalent to poke(value))
value - the value to replace with
Throws:
java.lang.IllegalArgumentException - if the stack does not contain enough elements to perform this operation

dup

void dup()
Duplicates the top value. Equivalent to push(peek()).

Throws:
java.lang.IllegalArgumentException - if the stack is empty

swap

void swap()
Swaps the top two stack values.

Throws:
GrammarException - if the stack does not contain at least two elements

swap3

void swap3()
Reverses the order of the top 3 stack values.

Throws:
GrammarException - if the stack does not contain at least 3 elements

swap4

void swap4()
Reverses the order of the top 4 stack values.

Throws:
GrammarException - if the stack does not contain at least 4 elements

swap5

void swap5()
Reverses the order of the top 5 stack values.

Throws:
GrammarException - if the stack does not contain at least 5 elements

swap6

void swap6()
Reverses the order of the top 5 stack values.

Throws:
GrammarException - if the stack does not contain at least 5 elements