/ 
Inline-Befunge-1.1.1
River stage zero No dependents
/ Inline::Befunge

NAME

Inline::Befunge - write Perl subs in Befunge

SYNOPSIS

use Inline "Befunge";

print "9 + 16 = ", add(9, 16), "\n";
print "9 - 16 = ", subtract(9, 16),"\n";

__END__
__Befunge__
;:add; +q

;:subtract; -q

DESCRIPTION

The Inline::Befunge module allows you to put Befunge source code directly "inline" in a Perl script or module.

This allows you to write cool stuff with all the power of Befunge!

USING Inline::Befunge

Using Inline::Befunge will seem very similar to using a another Inline language, thanks to Inline's consistent look and feel.

This section will explain how to use Inline::Befunge.

For more details on Inline, see perldoc Inline.

Feeding Inline with your code

The recommended way of using Inline is the following:

use Inline Befunge;

...

__END__
__Befunge__

  Befunge source code goes here.

But there are much more ways to use Inline. You'll find them in perldoc Inline.

Defining functions

As a befunge fan, you know that Befunge does not support named subroutines. So, I introduced a little hack (thank goes to Sean O'Rourke) in order for Inline to work: each subroutine definition should be prepended with a comment ;:subname; (notice the colon prepended).

You'll notice how smart it is, since it's enclosed in comments, and therefore the overall meaning of the code isn't changed.

You can define your subroutines in any of the four cardinal directions, and the subroutine velocity will be the velocity defined by the comment. That is, if you define a subroutine in a vertical comment from bottom to top, when called, the subroutine will start with a velocity of (0,-1).

You can add comments after the subname. Thus, ;:foo - a foo subroutine; defines a new subroutine foo.

So, here's a valid example:

use Inline "Befunge";

hello();

__END__
__Befunge__
;:hello - print a msg;<q_,#! #:<"Hello world!"a

    ;
    :
    a             q - ;tcartsbus:;
    d
    d
    ;
    +  ;not a valid func def;
    q

In this example, I defined three functions: hello(), add() and substract, and you can call them from within perl as if they were valid perl functions. The fourth comment ;not a valid func def; isn't a valid function definition since it lacks a colon : just after the ;.

Passing arguments

In order to write useful functions, one should be able to pass arguments. This is possible, and one will find the arguments on the TOSS of the interpreter: this means the stack may not be empty at the beginning of the run. If you're a purist, then you may ignore this and call your functions without arguments, and the stack will be empty.

Strings are pushed as 0gnirts.

/!\ Remember, Befunge works with a stack: the first argument will be the first pushed, ie, the deeper in the stack.

For example, when calling an inlined Befunge function like this: foo( 'bar', 7, 'baz' );, then the stack will be (bottom->top): (0 114 97 98 7 0 122 97 98).

Return values

Furthermore, one can return some values from the befunge subroutines... how exciting!

To do so, the Befunge semantics have been a little adapted:

o

when an Instruction Pointer reaches a q instruction, one cell will be popped from its stack and will be returned. This works like a scalar return.

o

when an Instruction Pointer reaches a @ instruction, it will be killed (just as in traditional Befunge). But when the last IP reaches a @, then the sub is exited and will return the whole stack of the IP that just died. This works like a list return.

/!\ Be careful, that you will return a list of integer values. You are to decide what to do with those values (especially, you are to convert back to characters with the chr perl builtin function and join the chars if you're waiting for a string!).

Supported options

Inline::Befunge supports a DEBUG option, to follow the IP(s) as they are running on the funge-space.

Use the following to activate it:

use Inline( Befunge => 'DATA',
            DEBUG   => 1 );

...
__END__
__Befunge__

  Enter you befunge code here.

PUBLIC METHODS

register( )

Register as an Inline Language Support Module.

validate( )

Check the params for the Befunge interpreter. Currently no options are supported.

build( )

Register the Befunge as a valid Inline extension.

load( )

This function actually fetches the Befunge code. It first splits it to find the functions.

info( )

Return a small report about the Befunge code.

SEE ALSO

perl
Inline
Language::Befunge

ACKNOWLEDGEMENTS

I would like to thank:

o

Brian Ingerson, for writing the incredibly cool Inline module, and giving the world's programmers enough rope to hang themselves many times over.

o

Chris Pressey, creator of Befunge, who gave a whole new dimension to both coding and obfuscating.

o

Sean O'Rourke <seano@alumni.rice.edu> for his incredible cool idea on defining labels in Befunge code.

AUTHOR

Jerome Quelin, <jquelin at cpan.org>

COPYRIGHT AND LICENCE

Copyright (c) 2001-2007 Jerome Quelin, all rights reserved.

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