yaml2html

I saw on the "Stages of Perl" website that an Adept writes his own pod2xyz script. I took that as a personal challenge.

So here's a twist on the theme: my first attempt to bypass POD by translating YAML directly to HTML.

#
 #
 #  yaml2html.pl
 #
 #  rje 5 Jan 2005
 #
#
use YAML;
use strict;

my $doc   = shift || die "SYNOPSIS: ", basename $0, " yaml-doc\n";
my $yaml  = readYaml( $doc );
my $level = 1;

my @toc;
my @body;

processRef( $yaml );

print<<HTML;
<html>
<body>
@toc
<hr>
@body
</body>
</html>
HTML

sub readYaml  # ugly kludge
{
   my $doc = shift;
   my @yamlsrc;
   open IN, $doc || die "ERROR: Cannot open file $doc\n";
   foreach (<IN>)
   {
         next unless /^-{3}/ .. /^\.{3}/;
      push @yamlsrc, $_;
   }
   close IN;
   pop @yamlsrc if $yamlsrc[-1] =~ /^\.{3}/; # remove final EOD
   
   my $yamlsrc = join '', @yamlsrc;
   return YAML::Load( $yamlsrc );
}

sub processRef
{
   my $yref = shift;
   
   processMapref($yref)    if ref($yref) eq 'HASH';
   processArrayref($yref)  if ref($yref) eq 'ARRAY';
   processString($yref)    if ref($yref) eq ''; # just a string!
}

sub processMapref
{
     my $mapref = shift;
   foreach my $key (sort keys %$mapref)
   {
         my $val = $mapref->{$key};
         push @toc,  "<li><a href='#$key'>$key</a></li>\n";
         push @body, "<li><a name='$key'><h$level>$key</h$level></a></
+li>\n";
      $level++;    
      processRef( $val );
      $level--;
   }
}

sub processArrayref
{
   my $aryref = shift;
 
     push @toc, "<ol>\n";
     push @body, "<ul>\n";
   foreach my $key (@$aryref)
   {
         my $val = $key;
      processRef( $val );
   }
   push @body, "</ul>\n";
   push @toc, "</ol>\n";
}

sub processString
{
   my $str = shift;
   my $indent = '  ' x $level;
   my @lines = split( "\n", $str );
   
   foreach(@lines)
   {
         next while /<pre>/ .. /<\/pre>/;
         $_ .= '<br>';
   }
   
   foreach(@lines)
   {
         next unless /<pre>/ .. /<\/pre>/;
         $_ = $indent . $_ . "\n";
   }
   
   push @body, @lines;
}

__END__
---
- yaml2html:
   - Version: 0.1
   - Author: Robert Eaglestone
   - Date: 5 January 2005

- Example: |
     <pre> yaml2html.pl [input file] > [html output] </pre>
     <pre> yeml2html.pl yaml2html.pl > yaml2html.html </pre>

- Detail:
   - Purpose: >
      This is a YAML parser which takes its input document
      and emits primitive HTML.
   
   - Origins: >
      I recently learned POD.  Immediately, I was taken by
      its simplicity.  It's so much easier to use than HTML,
      I even began writing simple HTML documents -- which had
      nothing to do with Perl -- with POD, then using pod2html 
      to convert to a webbable format.
      
      
      After doing this for awhile, I started to realize that
      POD was simply a shorthand for relatively simple, 
      heirarchical markup documentation... just the kind of
      thing that YAML is good for.  Well, being rather lazy
      when it comes to using two tools where a single tool
      will work fine, I decided to write a proof-of-concept
      Perl structure parser that could output HTML... a back-end
      to YAML, in a way.
      
   - How to use it: 
      - Assumptions: I assume you already know the basics of YAML.
      
      - Format: |
         Since hashtables are unordered, I find that using arrays
         ensures that my sections come out in the order I entered
         them.  So all section lists, including the root "Chapters",
         are arrays.  List items themselves are maps or hashtables
         containing either (1) another list, or (2) text.
         
         The leaf nodes, which necessarily are strings, are mapped
         to their section titles.  Refer to this example to see
         what I mean.
         
   - What this script does with the text: |
         This script builds a table of contents and a body.
         
         Sections are titled using < h1 >, < h2 >...< hn >, according
         to their subordinate level.  They're also indented: the table
         of contents is indented using an Ordered (Numbered) List, and
+ 
         the body is indented using an Unordered (Bullet) List.
         
         < br > tags are added before newline characters in the body t
+ext,
         except when the text is inside < pre >...< /pre > tags, in wh
+ich
         case it's left alone.
...
[download]

Comment on yaml2html Download Code

Replies are listed 'Best First'.
Re: yaml2html by mirod (Canon) on Jan 05, 2005 at 19:54 UTC
I take it that's just a first version ;--) The results aren't too spectacular with things like: `--- #YAML:1.0 - &1 !perl/my_class bar: 2 foo: 1 - object: *1` [download] The yaml file was generated by doing `perl -MYAML -e'my $o= bless { foo => 1, bar => 2}, "my_class"; print Dump [ $o, { object => $o}];' > test_object.yaml` Getting your tool to cover the entire spec would certainly get you well on your way to Perl Hacker!	[reply] [d/l] [select]
Re: yaml2html by gaal (Parson) on Jan 05, 2005 at 20:47 UTC
Two stylistic notes, if you don't mind: you're using @toc, @body and so on like globals: everybody is accessing them freely. In that case, consider declaring them package globals with `our` (or `use vars` if you care about this running on older perls); and also, using ALL_UPPERCASE names, or at least Capitalized ones. (Lexicals do work here. It's a matter of how you're working with them that suggests the package globals. If you decide to modularize this code, you will probably have to rework them into something else -- because they're used like globals. So at least make it explicit :-)	[reply] [d/l] [select]
Re: yaml2html by Aristotle (Chancellor) on Jan 12, 2005 at 14:29 UTC
Now you just need to write something that does half as good a job as `perldoc(1)` does for finding such documentation in scripts and browsing it on the console, and then you might be able to call it “bypassing” POD… `:-)` Makeshifts last the longest.	[reply]