NAME

D64::File::PRG - Handling individual C64's PRG files

SYNOPSIS

  use D64::File::PRG;

  my $prg = D64::File::PRG->new('FILE' => $file);
  my $prg = D64::File::PRG->new('RAW_DATA' => \$data, 'LOADING_ADDRESS' => 0x0801);

  $prg->change_loading_address('LOADING_ADDRESS' => 0x6400);

  my $data = $prg->get_data();
  my $data = $prg->get_data('FORMAT' => 'ASM', 'ROW_LENGTH' => 10);

  $prg->set_data('RAW_DATA' => \$data, 'LOADING_ADDRESS' => 0x1000);
  $prg->set_data('RAW_DATA' => \$data);
  $prg->set_file_data('FILE_DATA' => \$file_data);

  $prg->write_file('FILE' => $file);

DESCRIPTION

D64::File::PRG is a Perl module providing the set of methods for handling individual C64's PRG files. It enables an easy access to the raw contents of any PRG file, manipulation of its loading address, and transforming binary data into assembly code understood by tools like "Dreamass" or "Turbo Assembler".

METHODS

new

A new D64::File::PRG object instance is created either by providing the path to an existing file, which is then being read into a memory, or by providing a scalar reference to the raw binary data with an accompanying loading address. This is illustrated by the following examples:

  my $prg = D64::File::PRG->new('FILE' => $file);
  my $prg = D64::File::PRG->new('RAW_DATA' => \$data, 'LOADING_ADDRESS' => 0x0801);

Constructor will die upon one of the following conditions:

  1. File size is less than two bytes.
  2. Loading address provided is outside of a 16-bit range.
  3. Any character within a raw data is not a single byte.

There is an additional optional boolean "VERBOSE" available (defaulting to 0), which indicates that the extensive debugging messages should be printed out to the standard output. By default module acts silently, reporting error messages only.

read_file

While operating an existing D64::File::PRG object instance, there is no need to create a new one when you simply want to replace it with the contents of another file, that is if you only want to load a new data (however you need to create a new object instance if you want to provide raw data through a scalar reference - this limitation should be patched with the next release of this module). The example follows:

  $prg->read_file('FILE' => $file);

get_data

All raw data can be accessed through this method. You might explicitly want to request the format of a data retrieved. By default the raw content is collected unless you otherwise specify to get an assembly formatted source code. In both cases a scalar value is returned. In the latter case you are able to provide an additional parameter indicating how many byte values will be returned on a single line (these are 8 bytes by default). Here are a couple of examples:

  my $raw_data = $prg->get_data('FORMAT' => 'RAW', 'LOAD_ADDR_INCL' => 0);
  my $asm_data = $prg->get_data('FORMAT' => 'ASM', 'LOAD_ADDR_INCL' => 1, 'ROW_LENGTH' => 4);

There is an additional optional boolean "LOAD_ADDR_INCL", which indicates if a loading address should be included in the output string. For raw contents it defaults to 0, while for assembly source code format it defaults to 1. This is reasonable, as you usually don't want loading address included in a raw data, but it becomes quite useful when compiling a source code.

change_loading_address

You can modify original file loading address by performing the following operation:

  $prg->change_loading_address('LOADING_ADDRESS' => 0x6400);

set_data

You can update raw program data and its loading address by performing the following operation:

  $prg->set_data('RAW_DATA' => \$data, 'LOADING_ADDRESS' => 0x1000);

You can update raw program data without modifying its loading address by performing the following operation:

  $prg->set_data('RAW_DATA' => \$data);

set_file_data

You can replace original program data assuming that its loading address is included within the first two bytes of provided file data by performing the following operation:

  $prg->set_file_data('FILE_DATA' => \$file_data);

write_file

There is a command allowing you to save the whole contents into a disk file:

  $prg->write_file('FILE' => $file, 'OVERWRITE' => 1);

Note that when you specify any value evaluating to true for 'OVERWRITE' parameter, any existing file will be replaced (overwriting is disabled by default).

EXAMPLES

Retrieving raw data as an assembly formatted source code can be expressed using the following few lines of Perl code:

  use D64::File::PRG;
  my $data = join ('', map {chr} (1,2,3,4,5));
  my $prg  = D64::File::PRG->new('RAW_DATA' => \$data, 'LOADING_ADDRESS' => 0x0801);
  my $src  = $prg->get_data('FORMAT' => 'ASM', 'ROW_LENGTH' => 4);
  print $src;

When executed, it prints out the source code that is ready for compilation:

  ;---------------------------------------
                  *= $0801
  ;---------------------------------------
                  .byte $01, $02, $03, $04
                  .byte $05
  ;---------------------------------------

BUGS

There are no known bugs at the moment. Please report any bugs or feature requests.

EXPORT

None. No method is exported into the caller's namespace either by default or explicitly.

SEE ALSO

I am working on the set of modules providing an easy way to access and manipulate the contents of D64 disk images and T64 tape images. D64::File::PRG is the first module of this set, as it provides operations necessary for handling individual C64's PRG files, which are the smallest building blocks for those images. Upon completion I am going to successively upload all my new modules into the CPAN.

AUTHOR

Pawel Krol, <pawelkrol@cpan.org>.

VERSION

Version 0.03 (2013-01-19)

COPYRIGHT AND LICENSE

Copyright (C) 2010, 2013 by Pawel Krol.

This library is free open source software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.

PLEASE NOTE THAT IT COMES WITHOUT A WARRANTY OF ANY KIND!

cpanm D64::File::PRG

perl -MCPAN -e shell
install D64::File::PRG