The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Xcruciate::UnitConfig - OO API for reading xacerbate/xteriorize unit config files.

SYNOPSIS

my $config=Xcruciate::UnitConfig->new('unit.conf');

my $cm=$config->chime_multiplier;

my @mdf=$config->modifiable_data_files;

DESCRIPTION

Xcruciate::UnitConfig is part of the Xcruciate project (http://www.xcruciate.co.uk). It provides an OO interface to an xacerbate/xteriorize unit configuration file.

Accessor functions return scalars for <scalar/> entry types and lists for <list/> entry types. The values returned are those found in the config file, with the exception of yes_no datatypes which are converted into perlish boolean values (1 or 0).

All xte*() methods will return an undefined value unless the xte_start entry is set.

The entry() method can be used to access any entry including unofficial extensions. However, it is safer to use the named methods where possible, to avoid inventing unofficial extensions through typos.

AUTHOR

Mark Howe, <melonman@cpan.org>

EXPORT

None

CREATOR METHODS

new(config_file_path,verbose,stop_only [,lax])

Creates and returns an Xcruciate::UnitConfig object which can then be queried. If the optional verbose argument is perlishly true it will show its working to STDOUT. If the stop_only argument is perlishly true it will only bother about the information needed to stop processes (ie hosts and ports).

By default it looks for configuration errors and die noisily if it finds any. This is useful behaviour for management scripts - continuing to set up server daemons on the basis of broken configurations is not best practice. If the fourth argument (lax) is perlishly true, errors will be signalled but the possibly broken object will be created anyway. This is useful behaviour for development purposes, especially when changing config options, but should not be used in a production setting. Note that even the lax version of new() will die if the config file does not look anything like a config file.

UTILITY METHODS

xac_file_format_description()

Returns multi-lined human-friendly description of the xac config file

ACCESSOR METHODS

accept_from()

Returns the ip range from which connections are accepted.

access_log_path()

Returns the path to the access log.

backup_path()

Returns the path to which the backup zip file should be written.

boot_log_path()

Returns the path to the boot log.

chime_multiplier()

Returns the number of ticks per chime

clean_states_path()

Returns the path to the directory containing clean versions of modifiable files.

config_type()

Returns the type of config file, which in this case should always be 'unit'.

current_states_path()

Returns the path to the directory containing current versions of modifiable files.

debug_level()

Returns the xacerbate debug level.

debug_log_path()

Returns the path to the xacerbate debug log.

entry(name)

Returns the entry called name. Lists will be returned by reference. Use named methods in preference to this one where possible.

error_log_path()

Returns the path to the xacerbate error log.

log_file_paths()

Returns a list of locations to which xacerbate application code can write logs.

max_buffer_size()

Returns the maximum buffer size allowed for any one connection.

max_connections()

Returns the maximum number of connections accepted by xacerbate.

max_input_length()

Returns the maximum character length of each XML document.

modifiable_data_files()

Returns a list of modifiable data filenames.

modifiable_transform_files()

Returns a list of modifiable XSL filenames.

path()

Returns the path that is prefixed by xacerbate to various other settings.

peel_multiplier()

Returns the number of chimes per peel.

port()

Returns the port used by xacerbate.

persistent_modifiable_files()

Returns a list of modifiable files that should persist from session to session, ie they are not overwritten from clean on startup.

prepend_to_path(path)

Expects an absolute or relative path. If the path is relative, and if there was a path entry in the config file, the path entry is prepended to the relative path. Otherwise the supplied path is returned unchanged.

server_ip()

Returns the address on which xacerbate listens.

start_xte()

Returns start_xte value (true or false), ie whether xteriorize should be started alongside xacerbate.

startup_commands()

Returns a list of startup command filenames.

startup_files_path()

Returns the path to the startup command files.

tick_interval()

Returns the interval between ticks (or twice the interval between a tick and a tock).

transform_xsl()

Returns the name of the main transform file used by xacerbate.

very_persistent_modifiable_files()

Returns a list of modifiable files that should persist from session to session, even when xcruciate is reset (they will still be reinitialised by a factory reset).

xca_captcha_timeout()

Returns the time limit after which captchas time out

xca_castes()

Returns a list of site-specific castes, in ascending order of rights.

xca_confirmation_timeout()

Returns the time limit after which confirmation codes time out.

xca_date_formats()

Returns a list of date formats.

xca_datetime_formats()

Returns a list of datetime formats.

xca_default_email_contact()

Returns a flag signifying whether, by default, users accept contact via email.

xca_default_pm_contact()

Returns a flag signifying whether, by default, users accept contact via pm.

xca_failed_login_lockout()

Returns the number of failed logins after which an account will be locked.

xca_failed_login_lockout_reset()

Returns the time delay after which a locked account will be unlocked.

xca_favicon()

Returns the url of the site favicon (either a fully-qualified url or a local, absolute url).

xca_from_address()

Returns the email address used for outgoing mail.

xca_gateway_authenticate_timeout()

Returns the timeout for Xteriorize gateways authenticating with Xcathedra.

xca_http_domain()

Returns the website domain.

xca_manual_registration_activation()

Returns a flag signifying whether manual admin approval of new user accounts is currently activated.

xca_path()

Returns the path to the directory containing xcathedra (if defined).

xca_profile_template_path()

Returns the path to the site-specific template for user profiles.

xca_script_debug_caste()

Returns the minimum caste which will see extended script error diagnostics.

xca_session_timeout()

Returns the delay after which a session will time out.

xca_site_path()

Returns the path to the directory containing the site-specific files.

xca_time_offset()

Returns the default time zone offset.

xca_unique_registration_email()

Returns a flag signifying whether each user must use a unique email to register.

xte_captcha_bgcolors()

Returns a list of hex bytes (00 to FF) to be used to construct captcha background RGB values.

xte_captcha_colors()

Returns a list of hex bytes (00 to FF) to be used to construct captcha foreground RGB values.

xte_captcha_height()

Returns the pixel height of captchas.

xte_captcha_max_angle()

Returns the maximum angle by which TrueType text will be rotated in a captcha.

xte_captcha_max_line_thickness()

Returns the maximum thickness of captcha lines.

xte_captcha_max_lines()

Returns the maximum number of lines to draw on a captcha.

xte_captcha_min_line_thickness()

Returns the minimum line thickness to use in captchas.

xte_captcha_min_lines()

Returns the minimum number of lines to draw on a captcha.

xte_captcha_particle_count()

Returns the number of particles to add to a captcha.

xte_captcha_particle_size()

Returns the size of particles added to a captcha.

xte_captcha_styles()

Returns a list of GD:SecurityImage captcha styles.

xte_captcha_ttfont_size()

Returns the point size for TrueType captcha text.

xte_captcha_ttfonts()

Returns a list of TrueType fonts for captchas.

xte_captcha_width()

Returns the pixel width of captchas.

xte_check_for_waiting()

Returns the xte_check_for_waiting value (time to wait before revising number of child processes).

xte_cidr_allow()

Returns a list of allowed ip ranges for xteriorize

xte_cidr_deny()

Returns a list of denied ip ranges for xteriorize

xte_docroot()

Returns the docroot used by xteriorize.

xte_enable_captcha()

Returns true if captcha serving is enabled.

xte_enable_email()

Returns true if is email sending is enabled.

xte_enable_file_writing()

Returns true if is writing and deleting files is enabled.

xte_enable_fop()

Returns true if PDF output via Apache FOP is enabled.

xte_enable_json()

Returns true if output via XML::GenericJSON is enabled.

xte_enable_mxmlc()

Returns true if output via the Flex 3 compiler mxmlc is enabled.

xte_enable_static_serving()

Returns true if direct static file serving (ie without xacerbate) is enabled.

xte_enable_uploads()

Returns true if HTTP file uploading is enabled.

xte_enable_xmlroff()

Returns true if PDF output via xmlroff is enabled.

xte_from_address()

Returns the from address for emails sent by xteriorize

xte_gateway_auth()

Returns the from code expected by xacerbate to authorize gateway connections.

xte_group()

Returns the un*x group to use for xteriorize child processes. May be undefined.

xte_i18n_list()

Returns a list of i18n files.

xte_image_sizes()

Returns a list of sizes (eg 123x456) to which images will be scaled/cropped.

xte_log_file()

Returns the path to the xte log file.

xte_log_level()

Returns the xteriorize log level.

xte_max_image_size()

Returns the maximum dimensions (eg 123x456) beyond which an uploaded image will be cropped.

xte_max_servers()

Returns the Net::Prefork max_servers value for xteriorize.

xte_max_requests()

Returns the Net::Prefork max_requests value for xteriorize.

xte_max_spare_servers()

Returns the Net::Prefork max_spare_servers value for xteriorize.

xte_max_upload_size()

Returns the maximum permitted size in kb of file uploads.

xte_mimetype_path()

Returns the path to the mimetype lookup table for direct static file serving.

xte_min_servers()

Returns the Net::Prefork min_servers value for xteriorize.

xte_min_spare_servers()

Returns the Net::Prefork min_spare_servers value for xteriorize.

xte_port()

Returns the port used by xteriorize.

xte_post_max()

Returns the maximum character size of an http request received by xteriorize.

xte_report_benchmarks()

Returns true if timings for various aspects of Xcruciate processing are being output.

xte_server_ip()

Returns the ip on which xteriorize will listen.

xte_site_language()

Returns the site language in 2-character format.

xte_smtp_charset()

Returns the charset used for smtp by xteriorize.

xte_smtp_encoding()

Returns the encoding used for smtp by xteriorize.

xte_smtp_host()

Returns the host used for smtp by xteriorize.

xte_smtp_port()

Returns the port used for smtp by xteriorize.

xte_splurge_input()

Returns true if xte_splurge_input is enabled (copies XML sent from xteriorize to xacerbate to STDERR).

xte_splurge_output()

Returns true if xte_splurge_output is enabled (copies XML sent from xacerbate to xteriorize to STDERR).

xte_static_directories()

Returns a list of directories under docroot from which files will be served directly by Xteriorized.

xte_temporary_file_path()

Returns a directory to be used for temporary files, eg for output filters

xte_user()

Returns the un*x user to use for xteriorize child processes. May be undefined.

xte_use_xca()

Returns a flag according to whether or not xcathedra is used.

xte_xac_timeout()

Returns the delay for a response to xteriorize by xacerbate, after which xteriorize will issue a 504 ('gateway time-out') error.

local_croak()

Function for croaking

BUGS

The best way to report bugs is via the Xcruciate bugzilla site (http://www.xcruciate.co.uk/bugzilla).

PREVIOUS VERSIONS

    0.01: First upload

    0.03: First upload including module

    0.04: Changed minimum perl version to 5.8.8

    0.05: Added debug_list data type. Warn about unknown entries

    0.06: Added stop_only option to new(), added some comments

    0.07: Revised config file entry names. Check server_ip as well as port on start/stop. Attempt to put all Xcruciate modules in one PAUSE tarball.

    0.08: Added xte_temporary_file_path. Added lax option to proceed despite config errors.

    0.09: Use Carp for errors.

    0.10: Prepend path entry to relative paths

    0.11: Remove transform_xsl_path

    0.12: Resolve modifiable file paths, attempt to parse XML and XSLT files

    0.14: Global update

    0.15: Added xte_splurge_output

    0.16: Added support for xca entries. Added very_persistent_modifiable_files and xte_i18n_files. Distinquish warnings and errors in output.

    0.17: use warnings.

    0.18: Removed xca_time_display_function. Made v0.16 additions optional. Added nine new xca entries. Added new types to file format reporting.

    0.19: Use duration type for durations. Added xca_gateway_authenticate_timeout (previously a global in Xcathedra code). Got name of xte_use_xca right. Got missing xca entry testing in right loop.

    0.20: Added backup_path, xte_site_language, xte captcha entries and xte_enable entries, xca_image_sizes entries.

COPYRIGHT AND LICENSE

Copyright (C) 2007 - 2009 by SARL Cyberporte/Menteith Consulting

This library is distributed under the BSD licence (http://www.xcruciate.co.uk/licence-code).