/ 
Sys-Facter-1.00
River stage zero No dependents
/ Sys::Facter

NAME

Sys::Facter - collect facts about operating system

SYNOPSIS

use Sys::Facter;
use Data::Dumper;

my $facter = new Sys::Facter(modules => ["/some/where"]);

# load some facts manually and print them
$facter->load("kernel", "lsbrelease", "lsbid");
print Dumper $facter->facts;

# print some facts (they'll be loaded automatically)
print $facter->hostname;
print $facter->get("memorytotal");

DESCRIPTION

This module is a wrapper over Pfacter. Pfacter is a Facter (http://puppetlabs.com/puppet/related-projects/facter/) port to Perl.

The idea is to have a set of modules that detect various things about the host operating system, but also to easily extend this set by new, possibly user-written, modules. This is achieved through defining an API for additional plugins.

Pfacter specifies some API for plugins, but completely lacks documentation, and usage in Perl code is troublesome. This module simplifies Pfacter usage while preserving its API (somebody could already have some plugins written).

You can find a plugin API specification in this document, in "FACT PLUGIN API" section.

METHODS

Following methods are available:

new(%opts)

Constructor.

Following options are honoured:

modules => [...] (optional)

List of directories to be searched additionally to @INC for Pfacter modules.

These directories have the precedence over @INC and are searched in the order of appearance.

Plugins in these directories should be placed under Pfacter subdirectory, as it would be for @INC directories.

load(@facts)

Load and cache specified facts.

If you don't specify any facts at all, Sys::Facter will load all of them.

facts()

Return currently loaded facts as a %hashmap.

get($fact)

Return the value of specified fact, loading it if necessary.

${fact_name}()

For convenience, facts can be accessed with methods named by their names. For example, $facter->get("kernel") is equivalent to $facter->kernel.

Of course, facts called "get", "new", "facts" and "load" can't be fetched this way, but from these only "load" could be useful name.

FACT PLUGIN API

Pfacter doesn't provide an API documentation, so this is a short reference.

Pfacter plugin is a separate Perl module of name Pfacter::${plugin_name}. ${plugin_name} is all-lowercase with numbers and underscore (it should match regexp /^[a-z0-9_]+$/).

The module needs to have pfact() function defined. This function has two arguments provided: package name and a %hash-like object that contains "pfact" key with facts hashmap. This can be used to determine way of collecting facts about the system.

pfact() function is expected to return a single-line string. If it returns non-TRUE value, the fact is considered to be loaded but non-applicable to this system and will not be listed in $facter->facts().

Example module:

package Pfacter::example;

sub pfact {
  my ($pkg, $facter) = @_;
  my $facts = $facter->{pfact};

  if ($facts->{kernel} eq "Linux") {
    return "single-line";
  } else {
    return undef;
  }
}

# remember to return TRUE
1;

Note that while $facter in code above will be Sys::Facter reference, the plugin should not use anything except $facter->{pfact} field. This is to keep compatibility with original pfacter command line tool.

Modules may assume that following facts are pre-loaded:

- kernel

Under Linux it will be "Linux"

- operatingsystem

Under Linux it could be "Debian", "RedHat", "Gentoo", "SuSE" or similar.

- hostname

Host name, up to (but not including) first dot, if any.

- domain

Domain name. If output of uname -n contains dots, everything after first dot. Otherwise, autodetected.

AUTHOR

Stanislaw Klekot, <cpan at jarowit.net>

BUGS

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

LICENSE AND COPYRIGHT

Copyright 2012 Stanislaw Klekot.

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.

SEE ALSO

pffacter(1), Sys::Info(3)