--- VRac.pm	2007/08/04 22:34:16	136
+++ VRac.pm	2007/08/05 17:46:47	157
@@ -3,7 +3,7 @@
 use warnings;
 use strict;
 
-use Carp qw/confess croak/;
+use Carp qw/confess croak cluck carp/;
 use File::Slurp;
 use Data::Dump qw/dump/;
 
@@ -29,6 +29,14 @@
 This project is homage to 8-bit computers in Croatia and former Yugoslavia
 from 1980-1990. Word B<vrac> means also I<wizard> in Croatian.
 
+This project should enable anyone with limited knowledge of perl and 8-bit
+arhitecture of some machine to write emulator in an afternoon. To achieve this,
+code is written is as cleanly as possible.
+
+Porting existing emulators should be especially easy: you need passive
+understaning of language in which emulator is written and you can be on your
+way C<:-)>
+
 =cut
 
 =head1 FUNCTIONS
@@ -50,6 +58,43 @@
 }
 
 
+=head1 Memory management
+
+VRac implements callback for all I/O operations. This was main reason why
+L<Acme::6502> module with tied memory was too slow to emulate L<Orao>, so I
+had to write C binding for L<M6502>.
+
+B<This functions will die with stack trace when called>. They should be
+implemented for each architecture.
+
+=cut
+
+=head2 read
+
+Read from memory
+
+  $byte = read( $address );
+
+=cut
+
+sub read {
+	my $self = shift;
+	confess "please implement $self::read()";
+}
+
+=head2 write
+
+Write into emory
+
+  write( $address, $byte );
+
+=cut
+
+sub write {
+	my $self = shift;
+	confess "please implement $self::write()";
+}
+
 =head1 Helper functions
 
 =head2 load_rom
@@ -110,12 +155,16 @@
 	$from ||= 0;
 	$to ||= 0xffff;
 
-	open(my $fh, '>', $path) || die "can't open $path: $!";
-	print $fh $self->read_chunk( $from, $to );
-	close($fh);
+	if ( open(my $fh, '>', $path) ) {
+		print $fh $self->read_chunk( $from, $to );
+		close($fh);
+
+		my $size = -s $path;
+		warn sprintf "saved %s %04x-%04x %d %x bytes\n", $path, $from, $to, $size, $size;
+	} else {
+		warn "can't create $path: $!";
+	}
 
-	my $size = -s $path;
-	warn sprintf "saved %s %d %x bytes\n", $path, $size, $size;
 }
 
 =head2 hexdump
@@ -141,37 +190,33 @@
 	);
 }
 
-=head1 Memory management
+=head2 append_to_file
 
-VRac implements all I/O using mmap addresses. This was main reason why
-L<Acme::6502> was just too slow to handle it.
+  $self->append_to_file( '/path/to/file', $byte, $byte ... );
 
 =cut
 
-=head2 read
-
-Read from memory
-
-  $byte = read( $address );
-
-=cut
-
-sub read {
+sub append_to_file {
 	my $self = shift;
-	confess "please implement $self::read()";
-}
+	my $path = shift || confess "no path?";
+	my $bytes = join('', @_);
 
-=head2 write
+	my $size = -s $path || 0;
+	my $len = length($bytes);
 
-Write into emory
-
-  write( $address, $byte );
+	open(my $fh, '>>', $path) || confess "can't open $path: $!";
+	print($fh $bytes);
+	my $pos = tell($fh);
+
+	my $expected = $size + $len;
+	if ( $pos != $expected ) {
+		carp "BUG: file grows too big got $pos, expected $expected !";
+		truncate $fh, $expected;
+	}
 
-=cut
+	close($fh);
 
-sub write {
-	my $self = shift;
-	confess "please implement $self::write()";
+	warn sprintf("## append_to_file('%s',%s)\n", $path, dump($bytes));
 }
 
 =head1 Command Line
@@ -321,7 +366,7 @@
 
 =head1 SEE ALSO
 
-Components: L<M6502>, L<Z80>, L<Screen>, L<Tape>
+Components: L<M6502>, L<Z80>, L<Screen>, L<Tape>, L<Session>
 
 Emulators: L<Orao>, L<Galaksija>
 
@@ -329,10 +374,13 @@
 
 Dobrica Pavlinusic, C<< <dpavlin@rot13.org> >>
 
-=head1 BUGS
-
 =head1 ACKNOWLEDGEMENTS
 
+Structure and Interpretation of Computer Programs by Abelson, Sussman, and
+Sussman L<http://mitpress.mit.edu/sicp/> is a great book. It gave me idea
+that you should have wizard powers over your computer, even if it's 8 bit
+one.
+
 =head1 COPYRIGHT & LICENSE
 
 Copyright 2007 Dobrica Pavlinusic, All Rights Reserved.