/ 
parrot-0.0.5
/ 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

This 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

This holds an array ref for each line in the program. Each array ref contains:

  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

What is output to the bytecode file.

$listing

What is output to the listing file.

$bytecode

The program's bytecode (executable instructions).

$file, $line, $pline, $sline

These variables are used to reference information from the @program array. Please look at the comments for @program for the description of each.

%label

This holds each label and the PC at which it was defined.

%fixup

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

%macros

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

%local_label

This holds local label definitions.

%local_fixup

This holds the occurrences of local labels in the source file.

$last_label

This the name of the last label seen.

$pc

This is the current program counter.

$op_pc

This is the program counter for the most recent operator.

%constants

This maps the name of each constant to its index in the constant table.

@constants

This holds a list of constant values in the same order that they should be in the constant table.

%equate

This hash maps assembler directives to their replacements.

%encodings

This maps string prefixes to the corresponding encodings.

SUPPORT SUBROUTINES

get_options

This function gets and verifies the options. The 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 details of this file.

verbose

Output log messages.

output

The file to which the bytecode should be output.

listing

The file to which the listing should be output.

include

A list of files to add to the source code.

If either the output or listing options are specified, they must be accompanied by the name of the file to send the appropriate 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. Next, it examines the operator and arguments to find the best match. Finally, it outputs its information to the listing.

is_comment

Determines whether the entire line is a comment. It returns true if the first character is a '#' or the line is empty; otherwise it returns false.

has_pragma

Determines whether or not the line begins with a pragma. Returns true if the line begins with a . followed by a word; otherwise returns false.

has_label

Determines whether or not the line begins with a label. Returns true if the line begins with a word followed by a colon; otherwise returns false.

replace_string_constants

This function strips out string constants and replaces them with the string [sc N] (for string constants), where N is the index in the constants table at which 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.

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. It 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 an error message and exits.

log_message

Outputs a message to the log( STDERR ).

constantize_number

Adds a floating-point constant to the constant array and hash, remembering the index in the array at which it is stored. By using a hash, we ensure that duplicate numbers do not get duplicate entries in the constant table.

constantize_integer

Verifies that its argument is an integer, converting from binary or hexadecimal if necessary, and returns its value. Calling it with a non-integer argument, or with an integer greater or smaller than Parrot can handle produces a fatal error.

constantize_string

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

read_source

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