=pod

=head1 NAME

Text::Placeholder - simple placeholder system for text

=head1 SYNOPSIS

	use Text::Placeholder;
	my $placeholder = Text::Placeholder->new(
		my $counter = '::Counter');
	$placeholder->compile('Counter: [=counter=]');

	print ${$placeholder->execute()}, "<-\n";
	print ${$placeholder->execute()}, "<-\n";
	$counter->reset;
	print ${$placeholder->execute()}, "<-\n";

=head1 WARNINGS

This is an experimental module. It hasn't been thoroughly tested, making the probability of fatal bugs quite high. The sole goal of the release is to document the current development.


=head1 DESCRIPTION

Text::Placeholder substitutes symbolic placeholders in a text with actual values. The core package is less than 120 lines of Perl code. There is hardly intelligence or convenience in the core, because work is delegated to special objects. Thus the approach stays small and extensible.

Text::Placeholder can produce SQL statements, directory listings or parts of HTML pages. It is normally used in a multi-layer concept for assembling larger texts, e.g. a HTML page.

=head2 Template Systems

The term template commonly refers to mixtures of languages. The most advanced and widely used template system is probably PHP, which mixes HTML with a straightforward programming language. There is no point in trying to re-invent or imitate PHP. Thus Text::Placeholder only provides simple placeholders and not a language of its own. For example, there are no variables and no conditionals. Once you understand Text::Placeholder, you will see the alternative to language mixing.

::Perl_Inlined is a proof-of-concept module only, which over-stretches Text::Placeholder to deal with wildcards. There are no plans to maintain it or develop it further. Outside the formatting text a non-linear effect can be handled much better.

=head1 METHOD REFERENCE (API)

The design goal was a simple and robust API with a straightforward implementation, respecting all limitations of Perl 5.

=over 8

=item new([$specification], [$group, ...])

The constructor. For convenience it takes two types of optional arguments: a placeholder parser and/or placholder groups. If a placeholder parser (see below) is passed, then it's used instead of the default parser. Placeholder groups are passed to add_groups (see below).

=item compile($text)

Parses a given string and stores a representation suitable for fast execution. Work is delegated to placeholder groups.

=item execute

Returns a string ref with all placeholders substituted by actual values. Work is delegated to placeholder groups. Calling it multiple times makes sense if the data of a placeholder group is modified in between two calls.

=item parser($specification) or parser

Sets or gets the parser used to recognize and substitute the placeholders in the text. The specification can be given as a code reference or as a regular expression, which is automatically turned into a suitable code reference.

=item default_parser($specification) or default_parser

Like parser above, but sets the default parser, which is used from here onwards.

=item add_groups($group, ...)

Add placeholder groups. In order to do something useful, you need to have placeholder groups. The group can be referred to as a package/class name relative to Text::Placeholder or as a fully qualified package/class name or as a ready-made object.

The order in which groups are given is preserved. This is important for groups matching any placeholder.

=back

=head1 PLACEHOLDER GROUPS

The following is an overview of the groups shipped with Text::Placeholder.

=over 8

=item L<::Aggregator|Text::Placeholder::Aggregator>

Groups placeholder groups, which share the same subject. For example, the subject is the file name for OS::Unix::File::Name/Properties.

=item L<::Counter|Text::Placeholder::Counter>

Provides the placeholder symbol 'counter'. Increments the counter each time 'execute' is called.

=item L<::URI|Text::Placeholder::URI>

Provides the placeholder symbols uri_(scheme|opaque|host|path|full). A proof-of-concept module.

=item L<::Perl_Inlined|Text::Placeholder::Perl_Inlined>

Provides no specific placeholder symbols. Instead any symbol is treated as perl code. A proof-of-concept module.

=item L<::OS::Unix::File::Name|Text::Placeholder::OS::Unix::File::Name>

Provides the placeholder symbols file_(name_full|name_path|name_only|name_extension). The file doesn't needs to exists.

=item L<::OS::Unix::File::Properties|Text::Placeholder::OS::Unix::File::Properties>

Provides the placeholder symbols file_(owner_id|owner_name|group_id|group_name|size|timestamp_creation|timestamp_modification|timestamp_status). The file needs to exists. Can be used together with ::OS::Unix::File::Name via ::Aggregator for the name.

=item L<::SQL::Result|Text::Placeholder::SQL::Result>

Provides placeholder symbols based on a configurable RE, which needs one capture group. Placeholders substituted by the captured pattern. A list of captures can be obtained. In between two calls to execute the row data is changed.

=item L<::SQL::Statement|Text::Placeholder::SQL::Statement>

Provides placeholder symbols based on a configurable RE. All placeholders matching the RE are substituted by question marks. A list of matches can be obtained.

=back

You might want to search CPAN for placeholder groups, which are distributed separately.

=head1 KNOWN BUGS AND LIMITATIONS

This is the first public release.

Text::Placeholder was part of a bigger software project and has recently been separated. However, the quality of the code should be good enough for an initial release.


=head1 AUTHOR

Winfried Trumper E<lt>pub+perl(a)wt.tuxomania.netE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2011 Winfried Trumper

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

=cut
