App::Plog - The one and a half minute blog
use App::Plog ; App::Plog::create_blog(@ARGV) ; exit(0) ;
Generate a rudimentary HTML blog.
This module installs a script that allow you to generate a rudimentary blog using your prefered editor and the command line. This file documents the inner workings of the module.
Further documentation, useful to the user is displayed by running the plog end user application:
$> plog --help
App::Plog purpose is to transform input blocks, in a well defined format, to HTML snippets that are aggregated to form a single HTML file blog you can publish. The application itself is very simple as it delegates almost every action it takes to specialized modules. The modules can be completely replaced or inherited from to tune them.
The default modules used by App::Plog are all defined inline within the App::Plog module. This document describes the working of those default modules.
****************** .-----------------------. * RCS * | Extension matching | ****************** |-----------------------| * .-------. * | .--------------. | .----------. ************ * | .-------. * | | pod renderer | | | .----------. * HTML * * '-| .-------. * .->| '--------------' |-->| | rendered | * template * * '-| entry | * | | .-------------------. | '-| entry | ************ * '-------' * | | | Asciidoc renderer | | '----------' | ****************** | | '-------------------' | | | | | '-----------------------' | | v | | | .-----------. | | | | .-----------. | v v | | raw data | | .----------------------. .-----------------------. | | + |--'-->| feed generator | | aggregator | '-| RCS data | '----------------------' '-----------------------' '-----------' | | | | | | ************************** .------|--------------------------|-------. * blog elements * | | tmp directory | | ************************** |------|--------------------------|-------| * .-------. .-----. * | v v | * | image |. | css | * | .----------. .-----------. | * '-------'| '-----'--. * | | feed.xml | | blog.html | | * '-------' | ... | * | '----------' '-----------' | * '-----' * | | ************************** '-----------------------------------------' | | | | ******************** | .-------------------. | * note: input data * '------>| publishing script |<-------' * is in box with * '-------------------' * star border * ********************
Each blog has a specific configuration which allows you to fine tune the default behavior or override it. The elements used by App::Plog are defined within the blog configuration file so you can use your own modules or specialize the default modules.
The blog configuration is a perl data structure looking like:
{ commands => { class => 'App::Plog::Commands', }, rcs => { class => 'App::Plog::RCS::Git', entry_directory => '/where/the/blogs/entries/git/repository/is', }, renderer => { class => 'App::Plog::Renderer::Extension', renderers => { # match the entry file extension to the specialized renderer # using perl regex '.pod$' => { class => 'App::Plog::Renderer::HTML::Pod', css => 'sco.css' # make it look like search.cpan.org }, '.txt$' => { class => 'App::Plog::Renderer::HTML::Asciidoc', }, '.' => # default to pod { class => 'App::Plog::Renderer::HTML::Pod', css => 'sco.css' }, }, }, aggregator => { class => 'App::Plog::Aggregator::Template::Inline', # information passed to the Aggregator template => 'frame.html', feed_tag => 'FEED_TAG', entries_tag => 'ENTRIES_TAG', result_file => 'plog.html', }, feed => { class => 'App::Plog::Feed::Atom', page => 'http://your_server/your_blog/your_plog.html', } , # used in the update sub destination_directory => '/some/directory/to/publish/your_blog/in', #relative to blog root directory, can contain css, images, ... elements_directory => 'elements', update_script => 'update_blog.pl', # or shell script, bat file, ... # or sub { my ($configuration, $blog_directory, $temporary_directory) = @_ ; my $elements_directory = "$blog_directory/$configuration->{elements_directory}/*" ; ... }, }
The default commands are defined within the App::Plog::Commands package. You can add or remove commands from the plog application by deriving from App::Plog::Commands or writing a new module.
The default RCS is git. App::Plog::RCS::Git implements the interface needed by App::Plog. Other RCS are possible as well as a plain file system backend. I'll be happy to add another RCS to the distribution.
Transform input blocks to HTML snippets is handled, at the top level, by App::Plog::Renderer::Extension. App::Plog::Renderer::Extension doesn't render the input blocks directly; it matches the input block file extension to a specialized renderer and runs it. See section renderer in the configuration.
Two input formats are supported in the distribution, Pod and Asciidoc. Other format can easily be added.
The default aggregator is implemented in App::Plog::Aggregator::Template::Inline. App::Plog::Aggregator::Template::Inline simply replaces user defined tags with the rendered HTML snippets in a template of you choosing. The template and tags are defined in the configuration in section aggregator.
If section feed is defined, the feed generator, Package App::Plog::Feed::Atom in the default configuration, generates an Atom feed file. The aggregator also checks for the generation of a feed and inserts a feed link and icon in the template.
The blog is published, made available to people other than the author, or just the author if you so wish, by a user defined script or perl sub defined in the blog configuration.
The subroutines and methods are listed below for each package
create_blog will parse the command line and execute the the plog command.
Arguments
@arguments - the arguments passed on the command line
Returns - Nothing
Exceptions - Croaks on bad commands
my ($command, $arguments, $configuration, $blog_id, $blog_directory, $blog_configuration_file, $blog_configuration, $temporary_directory) = parse_configuration(@arguments) ;
The global plog configuration is located in ~:.plog but can be overridden by the --configuration_path option. Arguments
@arguments - command line arguments passed to the plog script in the format
$> plog [--option[s]] command [argument] [argument] ...
Returns
$command - the command to execute
\@arguments - the arguments to the command to execute
\%configuration - the global plog configuration
$blog_id - the name of the blog to work on. extracted from the global configuration or passed through the --blog_id option
$blog_directory - the directory where the '$blog_id' data are
$blog_configuration_file - the file name of the '$blog_id' configuration
\%blog_configuration - the '$blog_id' plog configuration
$temporary_directory - a temporary directory created during the run of the script or the directory passed thought the --temporary_directory option
Exceptions
Invalid options
missing configuration files
errors in configuration files
Arguments - None
Returns - Exits the process with value 0 (zero).
Exceptions - Croaks on perldoc errors
\%options - the command section from the blog configuration file
Returns - a App::Plog::Command object
Exceptions -None
Arguments- string - command name
Returns - boolean -true if the command is available to run
Exceptions -
Arguments- see Returns in sub parse_configuration
Exceptions - command if the command is neither defined nor exists
For each argument passed to this command, a file will be created in the current directory based on the blog template. A blog template is a file that matches $blog_directory/entry_template*. The contents are of no importance to plog.
\@arguments Contains the list of files to create
Exceptions - Croaks if no template is found or more than a template is found
Each argument passed to this command is taken as a file or a directory and will be copied to <$blog_directory/$blog_configuration->{elements_directory}>. A line, for each argument, is output on STDOUT.
\@arguments Contains the list of files to copy
Exceptions - Croaks if the copy fails
Lists all the blog entry under version control in $blog_configuration-{rcs}{entry_directory}>.
Exceptions - Croaks if the RCS object can't be created
Prints, on stdout, the list of blogs available to plog. where a blog is a directory within $configuration-{plog_root_directory}/>.
Handles the creation of the blog and its feed, including the creation of the objects defined in the plog configuration.
Exceptions - Croaks if object needed to generate the blog can't be created
Generates the blog and runs the update script defined in $blog_configuration-{update_script}>. The update script usually publishes the blog by copying the necessary data to a web server.
The update script is either a script in the language of your choosing, in which case the following arguments are passed on the command line
$blog_configuration_file
$blog_directory
$temporary_directory
or a perl sub in which case the following arguments are passed to the sub
$blog_configuration
\%options - the rcs section from the blog configuration file
Returns - a App::Plog::RCS::Git object
$self -
$blog_directory - the path to the blog directory
$temporary_directory - directory where temporary data can be saved
\%options - the renderer section from the blog configuration file
Returns - an App::Plog::Renderer::Extension object
exit(0) ;
\%entries - entries parsed by the rcs object
Exceptions - confess if called. This class serves a base class to derived classes
$date - string in format "2009-10-05 14:53:24 +0200"
Returns - $date in HTML format in three columns
2009-10-05 14:53:24 +0200
Exceptions - None
\%options - the section from the blog configuration file where a App::Plog::Renderer::HTML::Pod object was required
Returns - an App::Plog::Renderer::HTML::Pod object
$version - number - the version of the blog entry
$commit - the commit id of the blog entry
$text - the text of the entry as it was found by the version control system
Returns - the pod text rendered to HTML
\%options - the section from the blog configuration file where a App::Plog::Renderer::HTML::Asciidoc object was required
Returns - an App::Plog::Renderer::HTML::Asciidoc object
Returns - the asciidoc text rendered to HTML
\%options - the aggregator section from the blog configuration file
Returns - an App::Plog::Aggregator::Template::Inline object
$entries - the entries created by the rcs object and rendered
Exceptions - croaks if template doesn't exist or doesn't contain the tags defined in the configuration.
\%options - the feed section from the blog configuration file
Returns - an App::Plog::Feed::Atom object
$temporary_directory/rss.xml
None so far.
Nadim ibn hamouda el Khemir CPAN ID: NKH mailto: nadim@cpan.org
Copyright 2009 Nadim Khemir.
This program is free software; you can redistribute it and/or modify it under the terms of either:
the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
the Artistic License version 2.0.
You can find documentation for this module with the perldoc command.
perldoc App::Plog
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/App-Plog
RT: CPAN's request tracker
Please report any bugs or feature requests to L <bug-app-plog@rt.cpan.org>.
We will be notified, and then you'll automatically be notified of progress on your bug as we make changes.
Search CPAN
http://search.cpan.org/dist/App-Plog
http://search.cpan.org/~dcantrell/Bryar-3.1/lib/Bryar.pm
http://search.cpan.org/~jrockway/Angerwhale-0.062/lib/Angerwhale.pm
http://search.cpan.org/~lgoddard/Blog-Simple-HTMLOnly-0.04/HTMLOnly.pm
http://search.cpan.org/~gilad/Blog-Simple-0.03/Simple.pm
nanoblogger
To install App::Plog, copy and paste the appropriate command in to your terminal.
cpanm
cpanm App::Plog
CPAN shell
perl -MCPAN -e shell install App::Plog
For more information on module installation, please visit the detailed CPAN module installation guide.