#!/usr/bin/perl ############################################################################### # # # main.c # # # # Convert a ca65 source into HTML # # # # # # # # (C) 2000 Ullrich von Bassewitz # # Wacholderweg 14 # # D-70597 Stuttgart # # EMail: uz@musoftware.de # # # # # # This software is provided 'as-is', without any expressed or implied # # warranty. In no event will the authors be held liable for any damages # # arising from the use of this software. # # # # Permission is granted to anyone to use this software for any purpose, # # including commercial applications, and to alter it and redistribute it # # freely, subject to the following restrictions: # # # # 1. The origin of this software must not be misrepresented; you must not # # claim that you wrote the original software. If you use this software # # in a product, an acknowledgment in the product documentation would be # # appreciated but is not required. # # 2. Altered source versions must be plainly marked as such, and must not # # be misrepresented as being the original software. # # 3. This notice may not be removed or altered from any source # # distribution. # # # ############################################################################### # Things currently missing: # # - Scoping with .proc/.endproc # - .global is ignored # - .constructor/.destructor/.condes dito # - .ignorecase is ignored, labels are always case sensitive # - .include handling (difficult) # - The global namespace operator :: # use strict 'vars'; use warnings; # Modules use Getopt::Long; #-----------------------------------------------------------------------------# # Variables # # ----------------------------------------------------------------------------# # Global variables my %Files = (); # List of all files. my $FileCount = 0; # Number of input files my %Exports = (); # List of exported symbols. my %Imports = (); # List of imported symbols. my %Labels = (); # List of all labels my $LabelNum = 0; # Counter to generate unique labels # Command line options my $BGColor = "#FFFFFF"; # Background color my $Debug = 0; # No debugging my $Help = 0; # Help flag my $HTMLDir = ""; # Directory in which to create the files my $IndexCols = 6; # Columns in the file listing my $IndexTitle = "Index"; # Title of index page my $IndexName = "index.html"; # Name of index page my $IndexPage = 0; # Create an index page my $LinkStyle = 0; # Default link style my $ReplaceExt = 0; # Replace extension instead of appending my $TextColor = "#000000"; # Text color my $Verbose = 0; # Be quiet # Table used to convert the label number into names my @NameTab = ("A", "B", "C", "D", "E", "F", "G", "H", "I", "J", "K", "L", "M", "N", "O", "P", "Q", "R", "S", "T", "U", "V", "W", "X", "Y", "Z", "0", "1", "2", "3", "4", "5", "6", "7", "8", "9"); #-----------------------------------------------------------------------------# # Helper functions # # ----------------------------------------------------------------------------# # Terminate with an error sub Abort { print STDERR "ca65html: @_\n"; exit 1; } # Print a message if verbose is true sub Gabble { if ($Verbose) { print "ca65html: @_\n"; } } # Generate a label and return it sub GenLabel { my $I; my $L = "";; my $Num = $LabelNum++; # Generate the label for ($I = 0; $I < 4; $I++) { $L = $NameTab[$Num % 36] . $L; $Num /= 36; } return $L; } # Make an output file name from an input file name sub GetOutName { # Input name is parameter my $InName = $_[0]; # Create the output file name from the input file name if ($ReplaceExt && $InName =~ /^(.+)\.([^\.\/]*)$/) { return "$1.html"; } else { return "$InName.html"; } } # Remove illegal characters from a string sub Cleanup { my $S = shift (@_); $S =~ s/&/&/g; $S =~ s//>/g; $S =~ s/\"/"/g; return $S; } # Strip a path from a filename and return just the name sub StripPath { # Filename is argument my $FileName = $_[0]; # Remove a path name if we have one $FileName =~ /^(.*?)([^\/]*)$/; return $2; } #-----------------------------------------------------------------------------# # Document header and footer # # ----------------------------------------------------------------------------# # Print the document header sub DocHeader { my $OUT = shift (@_); my $Asm = shift (@_); print $OUT <<"EOF"; $Asm


$Asm



EOF
}

# Print the document footer
sub DocFooter {
    my $OUT  = shift (@_);
    my $Name = shift (@_);

    # Get the current date and time
    my $Today = localtime;

    print $OUT <<"EOF";



Valid HTML 4.0! $Name; generated on $Today by ca65html
uz\@cc65.org
EOF } #-----------------------------------------------------------------------------# # File list management # # ----------------------------------------------------------------------------# sub AddFile { # Argument is file to add my $FileName = $_[0]; # Get just the name (remove a path if there is one) my $Name = StripPath ($FileName); # Check if we have the file already if (exists ($Files{$Name})) { Gabble ("File \"$FileName\" already known"); return; } # Check with the full pathname. If we don't find it, search in the current # directory if (-f $FileName && -r $FileName) { $Files{$Name} = $FileName; $FileCount++; } elsif (-f $Name && -r $Name) { $Files{$Name} = $Name; $FileCount++; } else { Abort ("$FileName not found or not readable"); } } #-----------------------------------------------------------------------------# # Referencing and defining labels # # ----------------------------------------------------------------------------# # Get a label reference sub RefLabel { # Arguments are: Filename, identifier, item that should be tagged my $FileName = $_[0]; my $Id = $_[1]; my $Item = $_[2]; # Search for the identifier in the list of labels if (exists ($Labels{$FileName}{$Id})) { # It is a label (in this file) return sprintf ("%s", $Labels{$FileName}{$Id}, $Item); } elsif (exists ($Imports{$FileName}{$Id})) { # It is an import. If LinkStyle is 1, or if the file exporting the # identifier is not visible, we link to the .import statement in the # current file. Otherwise we link directly to the referenced symbol # in the file that exports it. if ($LinkStyle == 1 or not exists ($Exports{$Id})) { return sprintf ("%s", $Imports{$FileName}{$Id}, $Item); } else { # Get the filename from the export my $Label; ($FileName, $Label) = split (/#/, $Exports{$Id}); if (not defined ($Labels{$FileName}{$Id})) { # This may currently happen because we don't see .include # statements, so we may have an export but no definition. # Link to the .export statement instead $Label = $Exports{$Id}; } else { # Link to the definition in the file $Label = sprintf ("%s#%s", $FileName, $Labels{$FileName}{$Id}); } return sprintf ("%s", $Label, $Item); } } else { # The symbol is unknown, return as is return $Item; } } #-----------------------------------------------------------------------------# # Pass 1 # # ----------------------------------------------------------------------------# # Process1: Read one file for the first time. sub Process1 { # Variables my $Line; my $Id; # Filename is parameter my $InName = shift(@_); # Create the output file name from the input file name my $OutName = GetOutName ($InName); # Current cheap local label prefix is empty my $CheapPrefix = ""; # Open a the input file my $FileName = $Files{$InName}; # Includes path if needed open (INPUT, "<$FileName") or Abort ("Cannot open $FileName: $!"); # Keep the user happy Gabble ("$FileName => $OutName"); # Read and process all lines from the file while ($Line = ) { # Remove the newline chop ($Line); # Check for a label if ($Line =~ /^\s*(\@?)([_a-zA-Z][_\w]*)\s*(:|=)/) { # Is this a local label? if ($1 eq "\@") { # Use the prefix $Id = "$CheapPrefix$1$2"; } else { # Use as is $Id = $2; # Remember the id as new cheap local prefix $CheapPrefix = $Id; } # Remember the label $Labels{$OutName}{$Id} = GenLabel(); # Check for an import statement } elsif ($Line =~ /^\s*(\.import|\.importzp)\s+(.*?)(\s*)(;.*$|$)/) { # Split into a list of identifiers my @Ids = split (/\s*,\s*/, $2); for $Id (@Ids) { $Imports{$OutName}{$Id} = GenLabel(); } # Check for an export statement } elsif ($Line =~ /^\s*(\.export|\.exportzp)\s+(.*?)(\s*)(;.*$|$)/) { # Split into a list of identifiers my @Ids = split (/\s*,\s*/, $2); for $Id (@Ids) { $Exports{$Id} = sprintf ("%s#%s", $OutName, GenLabel()); } # Check for a .proc statement } elsif ($Line =~ /^\s*\.proc\s+([_a-zA-Z][_\w]*)?.*$/) { # Do we have an id? $Id = $1; if ($Id ne "") { $Labels{$OutName}{$Id} = GenLabel(); } } } # Close the input file close (INPUT); } # Pass1: Read all files for the first time. sub Pass1 () { # Keep the user happy Gabble ("Pass 1"); # Walk over the files for my $InName (keys (%Files)) { # Process one file Process1 ($InName); } } #-----------------------------------------------------------------------------# # Pass 2 # # ----------------------------------------------------------------------------# # Process2: Read one file the second time. sub Process2 { # Variables my $Base; my $Ext; my $Line; my $OutLine; my $Id; my $Label; my $Operand; my $Comment; # Input file is parameter my $InName = shift(@_); # Create the output file name from the input file name my $OutName = GetOutName ($InName); # Current cheap local label prefix is empty my $CheapPrefix = ""; # Open a the input file my $FileName = $Files{$InName}; # Includes path if needed open (INPUT, "<$FileName") or Abort ("Cannot open $FileName: $!"); # Open the output file and print the HTML header open (OUTPUT, ">$HTMLDir$OutName") or Abort ("Cannot open $OutName: $!"); DocHeader (OUTPUT, $InName); # Keep the user happy Gabble ("$FileName => $OutName"); # The instructions that will have hyperlinks if a label is used my $Ins = "adc|add|and|bcc|bcs|beq|bit|bmi|bne|bpl|bcv|bra|bvs|". "cmp|cpx|cpy|dec|eor|inc|jmp|jsr|lda|ldx|ldy|ora|rol|". "sbc|sta|stx|sty|sub|"; # Read the input file, replacing references by hyperlinks and mark # labels as link targets. while ($Line = ) { # Remove the newline chop ($Line); # Clear the output line $OutLine = ""; # Check for a label. If we have one, process it and remove it # from the line if ($Line =~ /^\s*?(\@?)([_a-zA-Z][_\w]*)(\s*)(:|=)(.*)$/) { # Is this a local label? if ("$1" eq "\@") { # Use the prefix $Id = "$CheapPrefix$1$2"; } else { # Use as is $Id = $2; # Remember the id as new cheap local prefix $CheapPrefix = $Id; } # Get the label for the id $Label = $Labels{$OutName}{$Id}; # Print the label with a tag $OutLine .= sprintf ("%s%s%s%s", $Label, $1, $2, $3, $4); # Use the remainder for line $Line = $5; } # Print any leading whitespace and remove it, so we don't have to # care about whitespace below. if ($Line =~ /^(\s+)(.*)$/) { $OutLine .= "$1"; $Line = $2; } # Handle the import statements if ($Line =~ /^(\.import|\.importzp)(\s+)(.*)$/) { # Print any fixed stuff from the line and remove it $OutLine .= "$1$2"; $Line = $3; # Print all identifiers if there are any while ($Line =~ /^([_a-zA-Z][_\w]*)(.*)$/) { # Identifier is $1, remainder is $2 $Id = $1; $Line = $2; # Variable to assemble HTML representation my $Contents = ""; # Make this import a link target if (exists ($Imports{$OutName}{$Id})) { $Label = $Imports{$OutName}{$1}; $Contents .= sprintf (" name=\"%s\"", $Label); } # If we have an export for this import, add a link to this # export definition if (exists ($Exports{$Id})) { $Label = $Exports{$Id}; $Contents .= sprintf (" href=\"%s\"", $Label); } # Add the HTML stuff to the output line if ($Contents ne "") { $OutLine .= sprintf ("%s", $Contents, $Id); } else { $OutLine .= $Id; } # Check if another identifier follows if ($Line =~ /^(\s*),(\s*)(.*)$/) { $OutLine .= "$1,$2"; $Line = $3; } else { last; } } # Add an remainder if there is one $OutLine .= Cleanup ($Line); # Handle export statements } elsif ($Line =~ /^(\.export|\.exportzp)(\s+)(.*)$/) { # Print the command the and white space $OutLine .= "$1$2"; $Line = $3; # Print all identifiers if there are any while ($Line =~ /^([_a-zA-Z][_\w]*)(.*)$/) { # Identifier is $1, remainder is $2 $Id = $1; $Line = $2; # Variable to assemble HTML representation my $Contents = ""; # If we have a definition for this export in this file, add # a link to the definition. if (exists ($Labels{$OutName}{$1})) { $Label = $Labels{$OutName}{$1}; $Contents = sprintf (" href=\"#%s\"", $Label); } # If we have this identifier in the list of exports, add a # jump target for the export. if (exists ($Exports{$Id})) { $Label = $Exports{$Id}; # Be sure to use only the label part $Label =~ s/^(.*#)(.*)$/$2/; # ##FIXME: Expensive $Contents .= sprintf (" name=\"%s\"", $Label); } # Add the HTML stuff to the output line if ($Contents ne "") { $OutLine .= sprintf ("%s", $Contents, $Id); } else { $OutLine .= $Id; } # Check if another identifier follows if ($Line =~ /^(\s*),(\s*)(.*)$/) { $OutLine .= "$1,$2"; $Line = $3; } else { last; } } # Add an remainder if there is one $OutLine .= Cleanup ($Line); # Check for .addr and .word } elsif ($Line =~ /^(\.addr|\.word)(\s+)(.*)$/) { # Print the command the and white space $OutLine .= "$1$2"; $Line = $3; # Print all identifiers if there are any while ($Line =~ /^([_a-zA-Z][_\w]*)(.*)$/) { if (exists ($Labels{$OutName}{$1})) { $Label = $Labels{$OutName}{$1}; $OutLine .= sprintf ("%s", $Label, $1); } else { $OutLine .= "$1"; } $Line = $2; if ($Line =~ /^(\s*),(\s*)(.*)$/) { $OutLine .= "$1,$2"; $Line = $3; } else { last; } } # Add an remainder if there is one $OutLine .= Cleanup ($Line); # Handle .proc } elsif ($Line =~ /^(\.proc\s+)([_a-zA-Z][_\w]*)?(.*)$/) { # Do we have an identifier? if ($2 ne "") { # Get the label for the id $Label = $Labels{$OutName}{$2}; # Print the label with a tag $OutLine .= sprintf ("%s%s", $1, $Label, $2); # Use the remainder for line $Line = $3; } # Cleanup the remainder and add it $OutLine .= Cleanup ($Line); # Handle .include } elsif ($Line =~ /^(\.include)(\s+)\"((?:[^\"]+?|\\\")+)\"(\s*)(;.*$|$)/) { # Add the fixed stuff to the output line $OutLine .= "$1$2\""; # Get the filename into a named variable my $FileName = $3; # Remember the remainder $Line = "\"$4$5"; # Get the name without a path my $Name = StripPath ($FileName); # We don't need FileName any longer as is, so clean it up $FileName = Cleanup ($FileName); # If the include file is among the list of our files, add a link, # otherwise just add the name as is. if (exists ($Files{$Name})) { $OutLine .= sprintf ("%s", GetOutName ($Name), $FileName); } else { $OutLine .= $FileName; } # Add the remainder $OutLine .= Cleanup ($Line); # Check for any legal instruction } elsif ($Line =~ /^($Ins)(\s+)(.*?)(\s*)(;.*$|$)/) { # Print the instruction and white space $OutLine .= "$1$2"; # Remember the remaining parts $Operand = $3; $Comment = Cleanup ("$4$5"); # Check for the first identifier in the operand and replace it # by a hyperlink if ($Operand =~ /^([^_a-zA-Z]*?)(\@?)([_a-zA-Z][_\w]*)(.*)$/) { # Is this a local label? if ("$2" eq "\@") { # Use the prefix $Id = "$CheapPrefix$2$3"; } else { # Use as is $Id = $3; } # Get the reference to this label if we find it $Operand = Cleanup($1) . RefLabel($OutName, $Id, $2 . $3) . Cleanup($4); } # Reassemble and print the line $OutLine .= "$Operand$Comment"; } else { # Nothing known - print the line $OutLine .= Cleanup ($Line); } # Print the result print OUTPUT "$OutLine\n"; } # Print the HTML footer DocFooter (OUTPUT, $OutName); # Close the files close (INPUT); close (OUTPUT); } # Pass2: Read all files the second time. sub Pass2 () { # Keep the user happy Gabble ("Pass 2"); # Walk over the files for my $InName (keys (%Files)) { # Process one file Process2 ($InName); } } #-----------------------------------------------------------------------------# # Create an index page # # ----------------------------------------------------------------------------# # Print a list of all files sub FileIndex { # File is argument my $INDEX = $_[0]; # Print the file list in a table print $INDEX "

Files

\n"; print $INDEX "\n"; my $Count = 0; for my $File (sort (keys (%Files))) { # if (($Count % $IndexCols) == 0) { print $INDEX "\n"; } printf $INDEX "\n", GetOutName ($File), $File; if (($Count % $IndexCols) == $IndexCols-1) { print $INDEX "\n"; } $Count++; } if (($Count % $IndexCols) != 0) { print $INDEX "\n"; } print $INDEX "
%s


\n"; } # Print a list of all exports sub ExportIndex { # File is argument my $INDEX = $_[0]; # Print the file list in a table print $INDEX "

Exports

\n"; print $INDEX "\n"; my $Count = 0; for my $Export (sort (keys (%Exports))) { # Get the export my $File; my $Label; ($File, $Label) = split (/#/, $Exports{$Export}); # The label is the label of the export statement. If we can find the # actual label, use this instead. if (exists ($Labels{$File}{$Export})) { $Label = $Labels{$File}{$Export}; } # if (($Count % $IndexCols) == 0) { print $INDEX "\n"; } printf $INDEX "\n", $File, $Label, $Export; if (($Count % $IndexCols) == $IndexCols-1) { print $INDEX "\n"; } $Count++; } if (($Count % $IndexCols) != 0) { print $INDEX "\n"; } print $INDEX "
%s


\n"; } sub CreateIndex { # Open the index page file open (INDEX, ">$HTMLDir$IndexName") or Abort ("Cannot open $IndexName: $!"); # Print the header print INDEX <<"EOF"; $IndexTitle


$IndexTitle



EOF # Print the file list in a table FileIndex (INDEX); ExportIndex (INDEX); # Print the document footer DocFooter (INDEX, $IndexName); # Close the index file close (INDEX); } #-----------------------------------------------------------------------------# # Print usage information # # ----------------------------------------------------------------------------# sub Usage { print "Usage: ca65html [options] file ...\n"; print "Options:\n"; print " --bgcolor color Use background color c instead of $BGColor\n"; print " --help This text\n"; print " --htmldir dir Specify directory for HTML files\n"; print " --indexcols n Use n columns on index page (default $IndexCols)\n"; print " --indexname file Use file for the index file instead of $IndexName\n"; print " --indexpage Create an index page\n"; print " --indextitle title Use title as the index title instead of $IndexTitle\n"; print " --linkstyle style Use the given link style\n"; print " --replaceext Replace source extension instead of appending .html\n"; print " --textcolor color Use text color c instead of $TextColor\n"; print " --verbose Be more verbose\n"; } #-----------------------------------------------------------------------------# # Main # # ----------------------------------------------------------------------------# # Get program options GetOptions ("bgcolor=s" => \$BGColor, "debug!" => \$Debug, "help" => \$Help, "htmldir=s" => \$HTMLDir, "indexcols=i" => \$IndexCols, "indexname=s" => \$IndexName, "indexpage" => \$IndexPage, "indextitle=s" => \$IndexTitle, "linkstyle=i" => \$LinkStyle, "replaceext" => \$ReplaceExt, "textcolor=s" => \$TextColor, "verbose!" => \$Verbose, "<>" => \&AddFile); # Check some arguments if ($IndexCols <= 0 || $IndexCols >= 20) { Abort ("Invalid value for --indexcols option"); } if ($HTMLDir ne "" && $HTMLDir =~ /[^\/]$/) { # Add a trailing path separator $HTMLDir .= "/"; } # Print help if requested if ($Help) { Usage (); } # Check if we have input files given if ($FileCount == 0) { Abort ("No input files"); } # Convert the documents Pass1 (); Pass2 (); # Generate an index page if requested if ($IndexPage) { CreateIndex (); } # Done exit 0;