<<
Web::Chain::IO::Html - adds the capability to the IO object to handle the DF Html format.
See Web::Chain::IO;
This class returns an input handle used dynamically by a Web::Chain::IO handle.
It provides input and output methods for files of the DF (aka "Doomfiles") Html format.
Two different types of input are supported by this module:
(1) It can do a light weight skim through a chain of files, following the next (or prev) links to record information about the browse sequence.
(2) It can load the nodes of a chain with all information in the body of html files (node name, next and prev links, and the main body).
- new - create an input/output handle, used by a Web::Chain::IO object. Ex. my $io_handle = $io_class->new( $self ); See Web::Chain::IO
- input_location - return the input_location
- input - Read some doomfiles nodes in html format from the input_location, return a newly created chain object containing the information. Uses two ordered arguments which are passed in from the IO input method: First, the name of the node (or the file, with '.html' extension) to begin with, second an argument to specify where in the browse sequence to terminate the input. If the first argument is undefined, it will start from the top node name defined in Definitions.pm (typically 'TOP.html', as of this writing). The second argument can be one of three things: undefined, which means to continue to the end of the chain, the final node (or file) name to be input, or it can be the total number of nodes (an integer). Example usage:
my $dfh = Web::Chain::IO->new; # Create a doomfiles io handle
$dfh->input_location($input_location); # the current input directory
$dfh->input_format('Html'); # requires Web::Chain::IO::Input::Html
my $chain = $dfh->input('FIN', 1); # should read just the node "FIN"
# Alternate:
my $chain = $dfh->input('TOP', 'DATA'); # should read sequence TOP -> DATA
# Alternate:
my $chain = $dfh->input(); # read the whole sequence
- get_browse_sequence - takes a single argument, the location, and determines the browse sequence for the existing DF nodes there. This is essentially an internally used routine containing code to implement the following two methods. This version is capable of getting a sequence from locations without a TOP or a FIN node.
- get_browse_sequence_from_output - returns a reference to a list of all doomfiles html pages in the output location, in the order of the browse sequence.
- get_browse_sequence_from_input - returns a reference to a list of all doomfiles html pages in the input location, in the order of the browse sequence.
- output_location - return the output_location
- output - writes some nodes to the output_location in HTML format. Uses three ordered arguments which are passed in from the IO output method: First, a chain object, second, the node in the chain to begin from -- as usual, either the node object or the node name work, and the third which specifies where in the chain to terminate output. The third argument can be one of three things: undefined, which means to continue to the end of the chain, the final node to be output, or it can be the total number of nodes (an integer). Example usage:
$io_obj->output( $chain, $begin_node, $termination );
- output_splice - output_splice is similar to output though it is designed to be used with an output_location that already has some content: output_splice outputs an entire chain at some position in the existing browse sequence, splicing the ends of the chain and the two existing nodes that are affected. It takes two arguments, a chain object, and the name of the position in the existing browse sequence. This position is expected to match the DF name pattern, and for output_splice to take place, all names involved have to be unique, i.e. none of the node names in the chain can already be in use in the output location. Example usage:
$self->output_splice( $chain, $position );
The following two routines look-up a node by name (from either the input or the output location) returning three items, the name of the node, the next node link, and the prev node link. Returning the node name when node name is also the argument might seem redundant, but (a) it can be treated as a flag to determine if the input was sucessful (prev or next would be undef for the first and last nodes, respectively) and also (b) where possible the format-specific code will read the node name in a different way than the lookup is performed -- e.g. in the case of Html, the returned name is that of the page title, but the given name is the file name.
- input_meta_info - internally used routine that takes two arguments, the location and the node name, and does the real work of looking up the meta information. Used by input_meta_info_from_input and input_meta_info_from_output. Note that this code is intentionally kept quite simple, and does no argument checking of any sort (not even a pattern match to make sure it's a well-formed DF name). It is indirectly used by other code that does argument checking.
- input_meta_info_from_input - given a node name, gets meta information for a node located in the input location. Example usage:
($node_name, $next_name, $prev_name) = $io_handle->input_meta_info_from_input($node_name)
- input_meta_info_from_output - given a node name, gets meta information for a node located in the output location. Example usage:
($node_name, $next_name, $prev_name) = $io_handle->output_meta_info_from_output($node_name)
- log_new_names - given a reference to an array of node names, include a list of them in a special node reserved for the purpose of logging these additions. The default name for that node is defined in Web::Definitions as $DF_WHATSNEW_NODE_NAME, it can be overridden by specifying it as the optional second argument. The return value is the date stamp value used in the log is returned (this is largely for testing purposes: it makes the exact output a little easier to predict). Example usage:
$dfh->log_new_names( \@new_node_names, $log_node );
- generate_contents_node - re-generate the "contents" (think "table of contents") node, a listing of all nodes in the project (i.e. in the output location). The default name for that node is defined in Web::Definitions as $DF_CONTENTS_NODE_NAME, it can be overridden with the optional argument. This method reads in the existing file first, updates it, and writes it out again: this ensures that next and prev links remain intact. The main body of the node is replaced by a new list describing the current browse sequence, though any introductory remarks before the first link will be preserved.
Some older routines imported from a proceedural codebase. There's no point in being any fancier than this, since a re-write to use Mason components is in the works.
These have all been moved to:
Web::Pro::HtmlOutput
- header =item footer =item first_header =item last_footer =item text2html
Future development plans:
The conversion of the main body to html, and the html format of the headers and footers, is currently handled by some proceedural routines, closely based on the original legacy scripts. Ultimately, I expect to replace with a templating system (most likely Mason, though TextTemplate is a candidate).
Project Documentation
Joseph Brenner, <doom@kzsu.stanford.edu>
Copyright (C) 2004 by Joseph Brenner
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.2 or, at your option, any later version of Perl 5 you may have available.
None reported... yet.
<<