File Coverage

blib/lib/Rubric/Config.pm

Criterion	Covered	Total	%
statement	21	21	100.0
branch	6	6	100.0
condition			n/a
subroutine	9	9	100.0
pod	1	1	100.0
total	37	37	100.0

use strict;
use warnings;
# ABSTRACT: the configuration data for a Rubric

use parent qw(Class::Accessor);

#pod =head1 DESCRIPTION
#pod
#pod Rubric::Config provides access to the configuration data for a Rubric.  The
#pod basic implementation stores its configuration in YAML in a text file in the
#pod current working directory.  By default, Rubric::Config looks for C<rubric.yml>,
#pod but an alternate filename may be passed when using the module:
#pod
#pod  use Rubric::Config ".rubric_yml";
#pod
#pod =cut

use YAML::XS ();

my $config_filename = $ENV{RUBRIC_CONFIG_FILE} || 'rubric.yml';

	my ($class) = shift;
	$config_filename = shift if @_;
}

#pod =head1 SETTINGS
#pod
#pod These configuration settings can all be retrieved by methods of the same name.
#pod
#pod =over 4
#pod
#pod =item * dsn
#pod
#pod the DSN to be used by Rubric::DBI to connect to the Rubric's database
#pod
#pod =item * db_user
#pod
#pod the username to be used by Rubric::DBI to connect to the Rubric's database
#pod
#pod =item * db_pass
#pod
#pod the password to be used by Rubric::DBI to connect to the Rubric's database
#pod
#pod =item * dbi_trace_level
#pod
#pod level of debug output for DBI
#pod
#pod =item * dbi_trace_file
#pod
#pod Where to send DBI debug output if dbi_trace_level
#pod
#pod =item * session_cipher_key
#pod
#pod The key to use to encrypt sessions, which are stored in user cookies.  This
#pod must be set.
#pod
#pod =item * cookie_secure
#pod
#pod If true, secure cookie are used. Defaults to false.
#pod
#pod =item * cookie_httponly
#pod
#pod If true, HTTP only cookies are used.  Defaults to false.
#pod
#pod =item * secure_login
#pod
#pod If true, login should only be done via secure means.  The login URI will be
#pod https, and loading the login page on an insecure connection will redirect.
#pod
#pod =item * uri_root
#pod
#pod the absolute URI for the root of the Rubric::WebApp install
#pod
#pod =item * css_href
#pod
#pod the absolute URI for the stylesheet to be used by Rubric::WebApp pages
#pod
#pod =item * basename
#pod
#pod This is the text to display as the name of this Rubric instance.  It defaults
#pod to "Rubric".
#pod
#pod =item * template_path
#pod
#pod the INCLUDE_PATH passed to Template when creating the template renderers
#pod
#pod =item * email_from
#pod
#pod the email address from which Rubric will send email
#pod
#pod =item * smtp_server
#pod
#pod the SMTP server used to send email
#pod
#pod =item * entries_query_class
#pod
#pod This is the class used to process the C<entries> run method.  It defaults to
#pod C<Rubric::WebApp::Entries>.
#pod
#pod =item * login_class
#pod
#pod This is the class used to check for logins; it should subclass
#pod Rubric::WebApp::Login.  If not supplied, the default is
#pod Rubric::WebApp::Login::Post.
#pod
#pod =item * skip_newuser_verification
#pod
#pod If true, users will be created without verification codes, and won't get
#pod verification emails.
#pod
#pod =item * registration_closed
#pod
#pod true if registration new users can't register for accounts via the web
#pod
#pod =item * private_system
#pod
#pod true value if users must have an account to view entries
#pod
#pod =item * private_tag
#pod
#pod A tag which, if attached to an entry, makes it private.  The default value is
#pod C<@private>, and I strongly advise against changing it, since I may change the
#pod way these "system tags" work in the future.
#pod
#pod =item * markup_formatter
#pod
#pod This entry, if given, should be a mapping of markup names to formatter plugins.
#pod For example:
#pod
#pod   markup_formatter:
#pod     kwid: Rubric::Entry::Formatter::Kwid
#pod     tex:  Rubric::Entry::Formatter::TeX
#pod
#pod (No.  Neither of those exist.)
#pod
#pod If it is not specified in the config file, an entry for C<_default> is set to
#pod the built-in, extremely simple entry formatter.
#pod
#pod =item * one_entry_per_link
#pod
#pod if true, each user can have only one entry per link (default: true)
#pod
#pod =item * allowed_schemes
#pod
#pod If undef, all URI schemes are allowed in entries.  If it's an array reference,
#pod it's the list of allowed schemes.
#pod
#pod =item * display_localtime
#pod
#pod If true, the local time (of the server) will be displayed for entry
#pod create/modify times.  Otherwise, all times will be UTC.  (This option is
#pod probably temporary, until per-user timezones are implemented.)
#pod
#pod =item * default_page_size
#pod
#pod The number of entries that are displayed on a page of entries, by default.
#pod
#pod =item * max_page_size
#pod
#pod The maximum number of entries that will be displayed on a page of entries.  If
#pod more are requested, this many will be displayed.
#pod
#pod =back
#pod
#pod =head1 METHODS
#pod
#pod These methods are used by the setting accessors, internally:
#pod
#pod =head2 _read_config
#pod
#pod This method returns the config data, if loaded.  If it hasn't already been
#pod loaded, it finds and parses the configuration file, then returns the data.
#pod
#pod =cut

my $config;
	return $config if $config;

	my $config_file = $config_filename;
	$config = YAML::XS::LoadFile($config_file);
}

#pod =head2 _default
#pod
#pod This method returns the default configuration has a hashref.
#pod
#pod =cut

my $default = {
	basename    => 'Rubric',
	css_href    => undef,
	db_user     => undef,
	db_pass     => undef,
	dsn         => undef,
	cookie_httponly => 0,
	cookie_secure   => 0,
	dbi_trace_level => 0,
	dbi_trace_file  => undef,
	secure_login    => 0,
	email_from  => undef,
	login_class => 'Rubric::WebApp::Login::Post',
	smtp_server => undef,
	uri_root    => '',
	private_tag => '@private',
	private_system => undef,
	template_path  => undef,
	allowed_schemes     => undef,
	default_page_size   => 25,
	display_localtime   => 0,
	entries_query_class => 'Rubric::WebApp::Entries',
	max_page_size       => 100,
  markup_formatter    => {},
	one_entry_per_link  => 1,
	registration_closed => undef,
  session_cipher_key  => undef,
	skip_newuser_verification => undef,
};

#pod =head2 make_ro_accessor
#pod
#pod Rubric::Config isa Class::Accessor, and uses this sub to build its setting
#pod accessors.  For a given field, it returns the value of that field in the
#pod configuration, if it exists.  Otherwise, it returns the default for that field.
#pod
#pod =cut

	my ($class, $field) = @_;
	sub {
		exists $class->_read_config->{$field}
			? $class->_read_config->{$field}
			: $class->_default->{$field}
	}
}

__PACKAGE__->mk_ro_accessors(keys %$default);

1;


=pod

=encoding UTF-8

=head1 NAME

Rubric::Config - the configuration data for a Rubric

=head1 VERSION

version 0.157

=head1 DESCRIPTION

Rubric::Config provides access to the configuration data for a Rubric.  The
basic implementation stores its configuration in YAML in a text file in the
current working directory.  By default, Rubric::Config looks for C<rubric.yml>,
but an alternate filename may be passed when using the module:

 use Rubric::Config ".rubric_yml";

=head1 PERL VERSION

This code is effectively abandonware.  Although releases will sometimes be made
to update contact info or to fix packaging flaws, bug reports will mostly be
ignored.  Feature requests are even more likely to be ignored.  (If someone
takes up maintenance of this code, they will presumably remove this notice.)
This means that whatever version of perl is currently required is unlikely to
change -- but also that it might change at any new maintainer's whim.

=head1 SETTINGS

These configuration settings can all be retrieved by methods of the same name.

=over 4

=item * dsn

the DSN to be used by Rubric::DBI to connect to the Rubric's database

=item * db_user

the username to be used by Rubric::DBI to connect to the Rubric's database

=item * db_pass

the password to be used by Rubric::DBI to connect to the Rubric's database

=item * dbi_trace_level

level of debug output for DBI

=item * dbi_trace_file

Where to send DBI debug output if dbi_trace_level

=item * session_cipher_key

The key to use to encrypt sessions, which are stored in user cookies.  This
must be set.

=item * cookie_secure

If true, secure cookie are used. Defaults to false.

=item * cookie_httponly

If true, HTTP only cookies are used.  Defaults to false.

=item * secure_login

If true, login should only be done via secure means.  The login URI will be
https, and loading the login page on an insecure connection will redirect.

=item * uri_root

the absolute URI for the root of the Rubric::WebApp install

=item * css_href

the absolute URI for the stylesheet to be used by Rubric::WebApp pages

=item * basename

This is the text to display as the name of this Rubric instance.  It defaults
to "Rubric".

=item * template_path

the INCLUDE_PATH passed to Template when creating the template renderers

=item * email_from

the email address from which Rubric will send email

=item * smtp_server

the SMTP server used to send email

=item * entries_query_class

This is the class used to process the C<entries> run method.  It defaults to
C<Rubric::WebApp::Entries>.

=item * login_class

This is the class used to check for logins; it should subclass
Rubric::WebApp::Login.  If not supplied, the default is
Rubric::WebApp::Login::Post.

=item * skip_newuser_verification

If true, users will be created without verification codes, and won't get
verification emails.

=item * registration_closed

true if registration new users can't register for accounts via the web

=item * private_system

true value if users must have an account to view entries

=item * private_tag

A tag which, if attached to an entry, makes it private.  The default value is
C<@private>, and I strongly advise against changing it, since I may change the
way these "system tags" work in the future.

=item * markup_formatter

This entry, if given, should be a mapping of markup names to formatter plugins.
For example:

  markup_formatter:
    kwid: Rubric::Entry::Formatter::Kwid
    tex:  Rubric::Entry::Formatter::TeX

(No.  Neither of those exist.)

If it is not specified in the config file, an entry for C<_default> is set to
the built-in, extremely simple entry formatter.

=item * one_entry_per_link

if true, each user can have only one entry per link (default: true)

=item * allowed_schemes

If undef, all URI schemes are allowed in entries.  If it's an array reference,
it's the list of allowed schemes.

=item * display_localtime

If true, the local time (of the server) will be displayed for entry
create/modify times.  Otherwise, all times will be UTC.  (This option is
probably temporary, until per-user timezones are implemented.)

=item * default_page_size

The number of entries that are displayed on a page of entries, by default.

=item * max_page_size

The maximum number of entries that will be displayed on a page of entries.  If
more are requested, this many will be displayed.

=back

=head1 METHODS

These methods are used by the setting accessors, internally:

=head2 _read_config

This method returns the config data, if loaded.  If it hasn't already been
loaded, it finds and parses the configuration file, then returns the data.

=head2 _default

This method returns the default configuration has a hashref.

=head2 make_ro_accessor

Rubric::Config isa Class::Accessor, and uses this sub to build its setting
accessors.  For a given field, it returns the value of that field in the
configuration, if it exists.  Otherwise, it returns the default for that field.

=head1 AUTHOR

Ricardo SIGNES <[e-mail]>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2004 by Ricardo SIGNES.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

=cut