/ 
parrot-0.0.2
/ Parrot::Assembler

NAME

Parrot::Assembler

SYNOPSIS

#! /usr/bin/perl -w
use strict;
use Parrot::Assembler;
init_assembler(@ARGV);
process_program_lines();
fixup();
add_constants();
output_bytecode() unless $options{'checksyntax'};
output_listing() if $options{'listing'};
exit 0;

############################################################################### ###############################################################################

DESCRIPTION

The support routines for the Parrot assembler. Eventually, this may become a class, allowing on-the-fly assembly instead of just a few functions to be called by the driver routine. Use would be something like:

use Parrot::Assembler;
use Parrot::Interpreter;
my $asm    = new Parrot::Assembler;
my $interp = new Parrot::Interpreter;
my $code   = ...;
my $pf = $asm->assemble($code);
exit $interp->run($pf);

############################################################################### ###############################################################################

VARIABLES

%type_to_suffix

type_to_suffix is used to change from an argument type to the suffix that would be used in the name of the function that contained that argument.

@program

@program will hold an array ref for each line in the program. Each array ref will contain:

  1. The file name in which the source line was found

  2. The line number in the file of the source line

  3. The chomped source line without beginning and ending spaces

  4. The chomped source line

$output =head2 $listing =head2 $bytecode

$output

will be what is output to the bytecode file.

$listing

will be what is output to the listing file.

$bytecode

is the program's bytecode (executable instructions).

$file =head2 $line =head2 $pline =head2 $sline

$file, $line, $pline, and $sline are used to reference information from the @program array. Please look at the comments for @program for the description of each.

%label =head2 %fixup =head2 %macros =head2 %local_label =head2 %local_fixup =head2 $last_label

%label

will hold each label and the PC at which it was defined.

%fixup

will hold labels that have not yet been defined, where they are used in the source code, and the PC at that point. It is used for backpatching.

%macros

will map a macro name to an array of program lines with the same format as @program.

%local_label

will hold local label definitions,

%local_fixup

will hold the occurances of local labels in the source file.

$last_label

is the name of the last label seen

$pc =head2 $op_pc

pc is the current program counter. op_pc is the program counter for the most recent operator.

%constants =head2 @constants

%constants is a map of constant name to index in the constant table @constants is an array of constant values in the same order that they should be in the constant table

%equate

maps assembler directives to their replacements.

SUPPORT SUBROUTINES

get_options

This function gets and verifies the options current options are:

checksyntax

do not emit bytecode, only check to see if the assembly is valid

help

emit a help message (usage)

version

emit the CVS revision of this file

verbose

output log messages

output

the file to output the bytecode

listing

the file to output the listing

include

a list of files to add to the source code

Validation checks to make sure that if either output or listing is present, it has an argument (which is the name of the file to output to.

init_assembler()

  1. adds the opcode fingerprint to the constant table

  2. adds the listing header

  3. creates the program lines array from each source file passed in

fixup

Checks to make sure that all labels are defined. Also outputs the label information to the listing.

add_constants()

Adds each constant to the PackFile's ConstTable.

output_bytecode

Writes the bytecode to the output file (or stdout if no filename was given). Ensures the file is in binmode.

output_listing

outputs the listing information to the filename given by the listing option.

process_program_lines

loops through each program line and checks for comments, labels, and assembler directives. Then, it examines the operator and arguments to find the best match. Finally, it outputs its information to the listing.

is_comment

Returns whether or not the entire line is a comment. This is true if the line starts with a '#' character

has_label

Returns whether or not the line begins with a label. This is true if the line begins with a word followed by a colon.

replace_constants

This function strips out string and number constants and replaces them with the string [sc N] (for string constants) or [nc N] (for numeric constants), where N is the index into the constants table where the constant is located.

has_asm_directive

returns true if there is a macro or equ directive

handle_asm_directive

Processes macros and equ directives. equ directives get stored in an equ hash. Macros store all program lines in an array.

NOTE: This function modifies @program.

handle_label

This function handles a label definition by storing the PC where the label was found and backpatching all previous instances of that label with the correct offset. This function handles both local labels and global labels.

expand_macro

Expands the macro into the @program array also replaces the macro arguments with the ones given to the macro. NOTE: modifies @program.

find_correct_opcode

Given an opcode like sin with arguments i n i, it will look through the opcode hash for a function that takes the correct number and types of arguments and is of the form sin(_x)* where x is one of i, n, s, p, ic, nc, or sc. It will prefer an exact argument match, but if one cannot be found, it will try to use ic for nc. It will stop on the first exact match, but will continue for non-exact matches to make sure the operator is unambiguous.

handle_operator

This function finds the correct opcode for the operator and packs the opcode into the output.

handle_arguments

Packs the argument into the bytecode.

add_line_to_listing

Adds a line to the listing string.

from_binary

Convert a string of the form 0b[01]+ to a decimal number

error

Outputs and error message and exits.

log_message

Outputs a message to the log( STDERR ).

constantize_number

TODO: Document this.

constantize_string

Replaces some escape sequences in a string then adds the string to the constant array and hash, remembering the index into the array where the constant string is stored. The hash is so duplicate strings do not get duplicated in the constants table.

read source

Reads in a file putting the informatino gathered into the @program array. It also processes INCLUDE directives opening the included file and recursively processing it.