NAME

Language::Befunge::IP - an Instruction Pointer for a Befunge-97 program.

DESCRIPTION

This is the class implementing the Instruction Pointers. An Instruction Pointer (aka IP) has a stack, and a stack of stacks that can be manipulated via the methods of the class.

We need a class, since this is a concurrent Befunge, so we can have more than one IP travelling on the Lahey space.

CONSTRUCTOR

new( )

Create a new Instruction Pointer.

clone( )

Clone the current Instruction Pointer with all its stacks, position, delta, etc. Change its unique ID.

ACCESSORS

set_pos( x, y )

Set the current position of the IP to the corresponding location.

All the following accessors are autoloaded.

id( [id] )

Get or set the unique ID of the IP.

curx( [x] )

Get or set the current x-coordinate of the IP.

cury( [y] )

Get or set the current y-coordinate of the IP.

dx( [dx] )

Get or set the horizontal offset of the IP.

dy( [dy] )

Get or set the vertical offset of the IP.

storx( [x] )

Get or set the x-coordinate of the storage offset of the IP.

story( [y] )

Get or set the y-coordinate of the storage offset of the IP.

data( )

Get the library private storage space.

input( [string] )

Get or set the input cache.

string_mode( [boolean] )

Get or set the string_mode of the IP.

end( [boolean] )

Get or set wether the IP should be terminated.

libs( )

Access the current stack of loaded libraries.

ss( )

Get the stack of stack of the IP.

toss( )

Access the current stack (er, TOSS) of the IP.

soss( )

Get or set the SOSS.

PUBLIC METHODS

Internal stack

In this section, I speak about the stack. In fact, this is the TOSS - that is, the Top Of the Stack Stack.

In Befunge-98, standard stack operations occur transparently on the TOSS (as if there were only one stack, as in Befunge-93).

scount( )

Return the number of elements in the stack.

spush( value )

Push a value on top of the stack.

spush_vec( x, y )

Push a vector on top of the stack. The x coordinate is pushed first.

spush_args ( arg, ... )

Push a list of argument on top of the stack (the first argument will be the deeper one). Convert each argument: a number is pushed as is, whereas a string is pushed as a 0gnirts.

/!\ Do not push references or weird arguments: this method supports only numbers (positive and negative) and strings.

spop( )

Pop a value from the stack. If the stack is empty, no error occurs and the method acts as if it popped a 0.

spop_vec( )

Pop a vector from the stack. Return the tuple -- hi, python fans! -- (x, y).

spop_gnirts( )

Pop a 0gnirts string from the stack.

sclear( )

Clear the stack.

svalue( offset )

Return the offsetth value of the TOSS, counting from top of the TOSS. The offset is interpreted as a negative value, that is, a call with an offset of 2 or -2 would return the second value on top of the TOSS.

Stack stack

This section discusses about the stack stack. We can speak here about TOSS (Top Of Stack Stack) and SOSS (second on stack stack).

ss_count( )

Return the number of stacks in the stack stack. This of course does not include the TOSS itself.

ss_create( count )

Push the TOSS on the stack stack and create a new stack, aimed to be the new TOSS. Once created, transfer count elements from the SOSS (the former TOSS) to the TOSS. Transfer here means move - and not copy -, furthermore, order is preserved.

If count is negative, then count zeroes are pushed on the new TOSS.

ss_remove( count )

Move count elements from TOSS to SOSS, discard TOSS and make the SOSS become the new TOSS. Order of elems is preserved.

ss_transfer( count )

Transfer count elements from SOSS to TOSS, or from TOSS to SOSS if count is negative; the transfer is done via pop/push.

The order is not preserved, it is reversed.

ss_sizes( )

Return a list with all the sizes of the stacks in the stack stack (including the TOSS), from the TOSS to the BOSS.

soss_count( )

Return the number of elements in SOSS.

soss_push( value )

Push a value on top of the SOSS.

soss_pop( )

Pop a value from the SOSS. If the stack is empty, no error occurs and the method acts as if it popped a 0.

soss_clear( )

Clear the SOSS.

Changing direction

set_delta( dx, dy )

Implements the x instruction. Set the delta vector of the IP according to the provided values.

dir_go_east( )

Implements the > instruction. Force the IP to travel east.

dir_go_west( )

Implements the < instruction. Force the IP to travel west.

dir_go_north( )

Implements the ^ instruction. Force the IP to travel north.

dir_go_south( )

Implements the v instruction. Force the IP to travel south.

dir_go_away( )

Implements the ? instruction. Cause the IP to travel in a random cardinal direction ( north, south, east or west).

dir_turn_left( )

Implements the [ instruction. Rotate by 90 degrees on the left the delta of the IP which encounters this instruction.

dir_turn_right( )

Implements the ] instruction. Rotate by 90 degrees on the right the delta of the IP which encounters this instruction.

dir_reverse( )

Implements the r instruction. Reverse the direction of the IP, that is, multiply the IP's delta by -1.

Libraries semantics

load( obj )

Load the given library semantics. The parameter is an extension object (a library instance).

unload( lib )

Unload the given library semantics. The parameter is the library name.

Return the library name if it was correctly unloaded, undef otherwise.

/!\ If the library has been loaded twice, this method will only unload the most recent library. Ie, if an IP has loaded the libraries ( FOO, BAR, FOO, BAZ ) and one calls unload( "FOO" ), then the IP will follow the semantics of BAZ, then BAR, then <FOO> (!).

extdata( library, [value] )

Store or fetch a value in a private space. This private space is reserved for libraries that need to store internal values.

Since in Perl references are plain scalars, one can store a reference to an array or even a hash.

PRIVATE METHODS

get_new_id( )

Forge a new IP id, that will distinct it from the other IPs of the program.

AUTHOR

Jerome Quelin, <jquelin@cpan.org>

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Language::Befunge.

cpanm Language::Befunge

perl -MCPAN -e shell
install Language::Befunge