/ 
XML-Debian-ENetInterfaces-0.03
River stage zero No dependents
/ XML::Debian::ENetInterfaces

NAME

XML::Debian::ENetInterfaces - Work with Debian's /etc/network/interfaces in XML.

VERSION

Version 0.03

SYNOPSIS

Import/Export Debian /etc/network/interfaces from/to XML.

    use XML::Debian::ENetInterfaces;
    XML::Debian::ENetInterfaces::lock(); # Optionally takes a Fcntl/flock
	# constant like LOCK_SH
    my $xmlstr = XML::Debian::ENetInterfaces::read();
    XML::Debian::ENetInterfaces::write('XML String'||IO::File->new('file','r'));
    XML::Debian::ENetInterfaces::unlock();

SUBROUTINES/METHODS

new

Just returns an object.

lock

By default, no arguments, creates an exclusive semaphoric lock on at least the two files written to by this application. Can be used to create a shared semaphoric lock, like so:

use Fcntl qw(:flock);
XML::Debian::ENetInterfaces::lock(LOCK_SH);

relock

Used internally to detect in proper Round Trip locking. May also be useful to you. Takes the same arguments as lock above.

unlock

Close the existing lock.

read

Takes no arguments and returns a string containing XML.

write

Takes either a string or a file handle, per IO::file understanding of what a file handle is, and passes this to XML::Parser::PerlSAX as a string. Current versions of XML::Parser::PerlSAX treat this identically to an IO::file, though I guess one couldn't count on that continually being the case.

EXAMPLE

#!perl
use XML::Debian::ENetInterfaces;
if ($writing) {
  $ENV{INTERFACES} = $outputfile;
  XML::Debian::ENetInterfaces::lock();
}
$ENV{INTERFACES} = $inputfile;
my $xmlstr = XML::Debian::ENetInterfaces::read();
# Cool XML reading/mangling code here.

# Only if writing code run above should you call write after a read.
$ENV{INTERFACES} = $outputfile;
XML::Debian::ENetInterfaces::write(SOURCE);

The SOURCE parameter should either be a string containing the whole XML document, or it should be an open IO::Handle.

XML

The XML produced/expected is of a schema developed and designed by me specifically for this purpose. IT MAY CHANGE in the future, though I wouldn't expect any changes to be significant if not drastic.

Comments on the schema are most welcome, I'd rather make changes sooner then later.

LOCKING

Locking in some cases is automatic, however in the Round Trip case (read/modify/write) that I needed when I wrote this and therefore might be the most common use of this module, the locking is not automatic. See usage for help and see Round Trip for an explanation.

Only does advisory locks on a semaphore file. This lock is intended to protect the interfaces file and the temporary file used on writes. A temp file is used to avoid problems where ifup/down might try and read the file while it's being written out, remember these locks do nothing to prevent ifup/down or any other program from accessing/changing the interfaces file directly. You must ensure that, other then the ifup/down applications, any other user of the interfaces file makes use of the semaphore used by this module, you can use this modules API or duplicate the concept in your own way.

ROUND TRIP

For this module this has two distinct meanings. Firstly it's a goal of this module to round trip with no change to the file, in most cases the file will be identical(have the same md5/sha1) as the original. The inode number is changed as a result of using a temporary file.

The second meaning is read/modify/write. In this case the contents will not be identical. You should make sure to lock the interfaces file exclusivity(just call this module's lock function with no parameters) prior to the read, this is because there is a race condition during changing the lock type where another writer can get over written.

XML::Debian::ENetInterfaces::Handler

Document this? meh, it's a lot of complicated code for taking XML and turning it into a file that represents the idea expressed in the XML as a /etc/network/interfaces file.

...In other words if you have to ask you can read it for yourself, other wise leave this alone.

AUTHOR

Michael Mestnik, <cheako+cpan at mikemestnik.net>

BUGS

I had put together a short list of these in my head, but I believe I've corrected most of them ;)

One note is that the source code remarks several locations where white-space could be altered during a round trip. Most notably the "non-repeating" child options share a single indentation whitespace, the first non-repeating child's indentation is authoritative.

The DTD is not complete with regard to add-on modules, like wireless, bridges, ect. I'm unsure of how modular a DTD can be, but I suspect the best way is for each add-on extend the DTD on there own... However I will take additions to the module included DTD for most if not all the add-on modules that submit to me there DTD.

Please report any bugs or feature requests to bug-xml-debian-enetinterfaces at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=XML-Debian-ENetInterfaces. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc XML::Debian::ENetInterfaces

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2011 Michael Mestnik.

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; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.