Document HashTable

1 files changed, 60 insertions, 2 deletions

diff --git a/lib/VarnishMib/HashTable.pm b/lib/VarnishMib/HashTable.pm
index 0f3b47e..1faef96 100644
--- a/lib/VarnishMib/HashTable.pm
+++ b/lib/VarnishMib/HashTable.pm
@@ -139,62 +139,120 @@ sub create {
     if ($self->{verbose}) {
 #	print STDERR "Input: " . @$names . "\n";
 	if ($self->{hash_table}) {
 	    print STDERR "Table size: " . @{$self->{hash_table}} . "\n";
 	    print STDERR "Collisions: " . $self->{collisions} . "\n";
 	} else {
 	    print STDERR "FAILED\n";
 	}
     }
     return $self->{hash_table};
 }
 
+=head2 format_input_table
+
+    $ht->format_input_table([FILEHANDLE]);
+
+Outputs to I<FILEHANDLE> (default B<STDOUT>) a C array of input names. The
+array is declared as
+
+    char const *PFXname_table[]
+
+where I<PFX> is replaced by the prefix given when creating the HashTable
+object.    
+
+=cut
+
 sub format_input_table {
     my ($self, $fh) = @_;
     $fh ||= \*STDOUT;
     croak "no input data to format" unless $self->{input};
-    print $fh 'char const *' . $self->{prefix} . "name_table[] = {\n";    
+    print $fh 'static char const *' . $self->{prefix} . "name_table[] = {\n";    
     foreach my $name (@{$self->{input}}) {
 	printf $fh $self->{indent} . '"' . $name . "\",\n";
     }
     print $fh "};\n";
     
 }
 
+=head2 format_data_table
+
+    $ht->format_data_table(CTYPE [, FILEHANDLE])
+
+Outputs a C array of data associated with input strings. The array is declared
+as
+
+    CTYPE PFXdata_table[N];
+
+where I<CTYPE> is the first parameter to the method, I<PFX> is the prefix and
+I<N> is the dimension (number of strings for which the hash table is built).
+Both B<name_table> and B<data_table> have the same dimension.    
+
+=cut
+    
 sub format_data_table {
     my ($self, $type, $fh) = @_;
     $fh ||= \*STDOUT;
     croak "no data to format" unless $self->{input};
     my $n = @{$self->{input}};
-    print $fh $type . ' ' . $self->{prefix} . "data_table[$n];\n";    
+    print $fh 'static '. $type . ' ' . $self->{prefix} . "data_table[$n];\n";
 }
 
+=head2 format_hash_table
+
+    $ht->format_hash_table([FILEHANDLE]);
+
+
+Outputs the hash table to I<FILEHANDLE> (B<STDOUT> by default). The table
+is declared as    
+
+    int PFXhash_table[]
+
+where I<PFX> is the prefix.
+    
+=cut
+
 sub format_hash_table {
     my ($self, $fh) = @_;
     $fh ||= \*STDOUT;
     croak "no hash table to format" unless $self->{hash_table};
     print $fh "static int ".$self->{prefix}."hash_table[] = {\n";
     my $col = 0;
     print $fh $self->{indent};
     foreach my $p (@{$self->{hash_table}}) {
 	printf $fh "%3d,", defined($p) ? $p : -1;
 	$col++;
 	print $fh ($col % 10 == 0) ? "\n".$self->{indent} : ' ';
     }
     print $fh "\n" if ($col % 10);
     print $fh "};\n";
     my $pfx = $self->{prefix} . 'hash_table';
     print $fh "unsigned ${pfx}_size = sizeof($pfx) / sizeof(${pfx}[0]);\n";
 }
 
+=head2 format_code
+
+    $ht->format_code([FILEHANDLE])
+
+Formats the supporting C code to the I<FILEHANDLE> (B<STDOUT>, if not given).
+The code contains at least the following function:
+    
+    unsigned string_hash(const char *str, unsigned size)
+
+which, given the string I<str> and the size of the hash table (I<size>)
+returns the index in the table starting from which the pointer to that
+string and associated data can be located.
+    
+=cut
+
 sub format_code {
     my ($self, $fh) = @_;
     $fh ||= \*STDOUT;
     seek DATA, 0, 0;
     my $visible = 0;
     while (<DATA>) {
 	if (/^__C__$/) {
 	    $visible = 1;
 	} elsif ($visible) {
 	    s{/\*\s*STATIC\s*\*/}{static};
 	    print $fh "$_";
 	}