/ 
Language-Befunge-5.000
River stage one • 3 direct dependents • 3 total dependents
/ Language::Befunge::IP

NAME

Language::Befunge::IP - an Instruction Pointer for a Befunge-98 program

VERSION

version 5.000

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.

CONSTRUCTORS

my $ip = LB::IP->new( [$dimensions] )

Create a new Instruction Pointer, which operates in a universe of the given $dimensions. If $dimensions is not specified, it defaults to 2 (befunge world).

my $clone = $ip->clone()

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

ACCESSORS

Attributes

The following is a list of attributes of a Language::Befunge::IP object. For each of them, a method get_foobar and set_foobar exists.

$ip->get_id() / $ip->set_id($id)

The unique ID of the IP (an integer). Don't set the ID yourself.

$ip->get_dims()

The number of dimensions this IP operates in (an integer). This is read-only.

$ip->get_position() / $ip->set_position($vec)

The current coordinates of the IP (a Language::Befunge::Vector object).

$ip->get_delta() / $ip->set_delta($vec)

The velocity of the IP (a Language::Befunge::Vector object).

$ip->get_storage() / $ip->set_storage($vec)

The coordinates of the storage offset of the IP (a Language::Befunge::Vector object).

$ip->get_data() / $ip->set_data({})

The library private storage space (a hash reference). Don't set this yourself. FIXME: not supposed to be accessible

$ip->get_string_mode() / set_string_mode($bool)

The string_mode of the IP (a boolean).

$ip->get_end() / $ip->set_end($bool)

Whether the IP should be terminated (a boolean).

$ip->get_libs() / $ip->set_libs($aref)

The current stack of loaded libraries (an array reference). Don't set this yourself. FIXME: not supposed to be accessible

$ip->get_ss() / $ip->set_ss($aref)

The stack of stack of the IP (an array reference). Don't set this yourself. FIXME: not supposed to be accessible

$ip->get_toss() / $ip->set_toss($aref)

The current stack (er, TOSS) of the IP (an array reference). Don't set this yourself. FIXME: not supposed to be accessible

$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( vector )

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_mult( <count> )

Pop multiple values from the stack. If the stack becomes empty, the remainder of the returned values will be 0.

spop_vec( )

Pop a vector from the stack. Returns a Vector object.

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_mult( <count> )

Pop multiple values from the SOSS. If the stack becomes empty, the remainder of the returned values will be 0.

soss_push_vec( vector )

Push a vector 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_pop_vec( )

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

soss_clear( )

Clear the SOSS.

Changing direction

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.

Not valid for Unefunge.

dir_go_south( )

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

Not valid for Unefunge.

dir_go_high( )

Implements the h instruction. Force the IP to travel up.

Not valid for Unefunge or Befunge.

dir_go_low( )

Implements the l instruction. Force the IP to travel down.

Not valid for Unefunge or Befunge.

dir_go_away( )

Implements the ? instruction. Cause the IP to travel in a random cardinal direction (in Befunge's case, one of: 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.

Not valid for Unefunge. For Trefunge and greater, only affects the X and Y axes.

dir_turn_right( )

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

Not valid for Unefunge. For Trefunge and higher dimensions, only affects the X and Y axes.

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.

AUTHOR

Jerome Quelin

COPYRIGHT AND LICENSE

This software is copyright (c) 2003 by Jerome Quelin.

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