lib/Language/Befunge.pm

   1 #
   2 # This file is part of Language::Befunge.
   3 # Copyright (c) 2001-2008 Jerome Quelin, all rights reserved.
   4 #
   5 # This program is free software; you can redistribute it and/or modify
   6 # it under the same terms as Perl itself.
   7 #
   8 #
   9
  10 package Language::Befunge;
  11 require 5.006;
  12
  13 use strict;
  14 use warnings;
  15
  16 use Carp;
  17 use Language::Befunge::Interpreter;
  18
  19 # Public variables of the module.
  20 our $VERSION = '3.03';
  21 $| = 1;
  22
  23 sub new {
  24     shift;
  25     return Language::Befunge::Interpreter->new(@_);
  26 }
  27
  28 1;
  29 __END__
  30
  31 =head1 NAME
  32
  33 Language::Befunge - a Befunge-98 interpreter
  34
  35
  36 =head1 SYNOPSIS
  37
  38     use Language::Befunge;
  39     my $interp = Language::Befunge->new( "program.bf" );
  40     $interp->run_code( "param", 7, "foo" );
  41
  42     Or, one can write directly:
  43     my $interp = Language::Befunge->new;
  44     $interp->store_code( <<'END_OF_CODE' );
  45     < @,,,,"foo"a
  46     END_OF_CODE
  47     $interp->run_code;
  48
  49
  50 =head1 DESCRIPTION
  51
  52 Enter the realm of topological languages!
  53
  54 This module implements the Funge-98 specifications on a 2D field (also
  55 called Befunge). It can also work as a Trefunge implementation (3D).
  56
  57 This Befunge-98 interpreters assumes the stack and Funge-Space cells
  58 of this implementation are 32 bits signed integers (I hope your os
  59 understand those integers). This means that the torus (or Cartesian
  60 Lahey-Space topology to be more precise) looks like the following:
  61
  62               32-bit Befunge-98
  63               =================
  64                       ^
  65                       |-2,147,483,648
  66                       |
  67                       |         x
  68           <-----------+----------->
  69   -2,147,483,648      |      2,147,483,647
  70                       |
  71                      y|2,147,483,647
  72                       v
  73
  74 This implementation is meant to work on unix-like systems, because
  75 this interpreters only handle the character which ordinal value is 10
  76 (also known as \n) as an End-Of-Line chars. In particular, no warranty
  77 is made neither for Microsoft systems (\r\n) nor for Macs (\r).
  78
  79 This module also implements the Concurrent Funge semantics.
  80
  81
  82 =head1 PUBLIC METHODS
  83
  84 =head2 new( [params] )
  85
  86 Call directly the Language::Befunge::Interpreter constructor. Refer to
  87 L<Language::Befunge::Interpreter> for more information.
  88
  89
  90 =head1 TODO
  91
  92 =over 4
  93
  94 =item o
  95
  96 Write standard libraries.
  97
  98 =back
  99
 100
 101 =head1 BUGS
 102
 103 Although this module comes with a full set of tests, maybe there are
 104 subtle bugs - or maybe even I misinterpreted the Funge-98
 105 specs. Please report them to me.
 106
 107 There are some bugs anyway, but they come from the specs:
 108
 109 =over 4
 110
 111 =item o
 112
 113 About the 18th cell pushed by the C<y> instruction: Funge specs just
 114 tell to push onto the stack the size of the stacks, but nothing is
 115 said about how user will retrieve the number of stacks.
 116
 117 =item o
 118
 119 About the load semantics. Once a library is loaded, the interpreter is
 120 to put onto the TOSS the fingerprint of the just-loaded library. But
 121 nothing is said if the fingerprint is bigger than the maximum cell
 122 width (here, 4 bytes). This means that libraries can't have a name
 123 bigger than C<0x80000000>, ie, more than four letters with the first
 124 one smaller than C<P> (C<chr(80)>).
 125
 126 Since perl is not so rigid, one can build libraries with more than
 127 four letters, but perl will issue a warning about non-portability of
 128 numbers greater than C<0xffffffff>.
 129
 130 =back
 131
 132
 133 =head1 ACKNOWLEDGEMENTS
 134
 135 I would like to thank Chris Pressey, creator of Befunge, who gave a
 136 whole new dimension to both coding and obfuscating.
 137
 138
 139 =head1 SEE ALSO
 140
 141 =over 4
 142
 143 =item L<perl>
 144
 145 =item L<http://www.catseye.mb.ca/esoteric/befunge/>
 146
 147 =item L<http://dufflebunk.iwarp.com/JSFunge/spec98.html>
 148
 149 =back
 150
 151
 152 =head1 AUTHOR
 153
 154 Jerome Quelin, E<lt>jquelin@cpan.orgE<gt>
 155
 156 Development is discussed on E<lt>language-befunge@mongueurs.netE<gt>
 157
 158
 159 =head1 COPYRIGHT & LICENSE
 160
 161 Copyright (c) 2001-2008 Jerome Quelin, all rights reserved.
 162
 163 This program is free software; you can redistribute it and/or modify
 164 it under the same terms as Perl itself.
 165
 166
 167 =cut