view release on metacpan or  search on metacpan

Wyrd/Interfaces/Setter.pm  view on Meta::CPAN

    $wyrd->_data($wyrd->_set());

    #interpret enclosed text and set the item placemarker.
    $wyrd->_data($wyrd->_set({item => 'this is the item'}));

    #interpret given template and set enclosed text to the result.
    $wyrd->_data($wyrd->_set(
      {item => 'this is the item'},
      'This is the item: $:item'
    ));

=head1 DESCRIPTION

The Setter interface give Wyrds a small templating "language" for
placing variables into HTML:  In short summary, there are two kinds of
tokens interpreted by the Setter: a placemarker and a conditional.  For
placemarkers, any valid perl variable name preceded by dollar-colon
("$:") is replaced by the value of that variable.  For conditionals, any
valid perl variable name preceded by an exclamation or question mark
and followed by curly braces enclosing text shows the enclosed text
conditionally if the variable is true ("?:") or false ("!:").  These
conditionals can be nested.

The Setter interface provides several "flavors" of Set-ting functions
depending on their purpose.  In general, however, they all accept two
optional variables, one being the hashref of variables to set with, the
second being the text which will be interpreted.  If the second variable
is not provided, it is assumed that the enclosed text is the text to be
processed.  If neither the first or the second is provided, it is also
assumed the CGI environment is the source for the variable substitution.

If the CGI environment is used, the Setter will use the minimum
necessary, only using the items it can clearly find in placemarkers.

=head1 METHODS

I<(format: (returns) name (arguments after self))>

=over

=item (scalar) C<_set> ([hashref], [scalar])

Simplest flavor.  If a place-marked variable doesn't exist as a key in the
hashref which is the first argument (or in the CGI environment if the hashref is
not provided), then the placemarker is not interpreted, and remains untouched.

=cut

sub _set {
	my ($self, $hash, $temp) = @_;
	($hash, $temp) = $self->_setter_defaults($hash, $temp);
	$temp = $self->_regexp_conditionals($hash, $temp);
	$temp = $self->_setter_replacements($hash, $temp);
	return $temp;
}

=pod

=item (scalar) C<_clear_set> ([hashref], [scalar])

Same as _set, but wipes anything remaining that looks like a placemarker.

=cut

sub _clear_set {#clear out any unset values.
	my ($self, $hash, $temp) = @_;
	($hash, $temp) = $self->_setter_defaults($hash, $temp);
	$temp = $self->_clear_regexp_conditionals($hash, $temp);
	$temp = $self->_setter_replacements($hash, $temp);
	$temp =~ s/\$:[a-zA-Z_0-9]+//g;
	return $temp;
}

=pod

=item (scalar) C<_clean_set> ([hashref], [scalar])

More perl-ish.  If the placemarker is undefined OR false, it is not
interpreted.

=cut

sub _clean_set {
	#For making "set" more perl-ish and handling conditionals as if ''/null/undef value == undefined
	my ($self, $hash, $temp) = @_;
	($hash, $temp) = $self->_setter_defaults($hash, $temp);
	my %newhash = %$hash;
	foreach my $key (keys(%newhash)) {
		delete $newhash{$key} unless ($newhash{$key});#undefine missing bits for setter
	}
	$temp = $self->_regexp_conditionals($hash, $temp);
	return $self->_setter_replacements(\%newhash, $temp);
}

=pod

=item (scalar) C<_text_set> ([hashref], [scalar])

More text-ish and perl-ish.  If the placemarker is undefined OR false,
it is not interpreted.  Anything else that looks like a placemarker
after interpretation is finished is wiped out.  Generally safe for output
directly to web pages.

=cut

sub _text_set {
	#Like "_clean_set", but also interprets arrays and uses the _clear_set.
	#used for outputting directly to web pages
	my ($self, $hash, $temp) = @_;
	($hash, $temp) = $self->_setter_defaults($hash, $temp);
	$temp = $self->_regexp_conditionals($hash, $temp);
	my %newhash = %$hash;
	foreach my $key (keys(%newhash)) {
		$newhash{$key} = join ', ' , @{$newhash{$key}} if (ref($newhash{$key}) eq 'ARRAY');
		$newhash{$key} = '' unless ($newhash{$key} or ($newhash{$key} eq '0'));
	}
	return $self->_clear_set($hash, $temp);
}

=pod

=item (scalar) C<_quote_set> ([hashref], [scalar])

More SQL-ish, but not CGI-ish.  A blank hashref is used in place of the
CGI environment when passed no parameters.  Placemarkers are replaced
with the quote function of DBI via the Wyrd->dbl->quote function so as
to be used in SQL queries.

=cut

sub _quote_set {
	my ($self, $hash, $temp) = @_;
	#if a target ($temp) is provided, use it instead of the data
	$temp = $self->{'_data'} unless ($temp);
	$hash = {} unless (ref($hash) eq 'HASH');
	#first do conditionals
	$temp = $self->_regexp_conditionals($hash, $temp);
	#then do quotations, altering a copy, not the original
	my %hash = %$hash;
	foreach my $i (keys(%hash)) {
		$hash{$i}=$self->dbl->dbh->quote($hash{$i});
		$hash{$i}='NULL' if ($hash{$i} eq q(''));
	}
	#then do replacements
	foreach my $i (sort {length($b) <=> length($a)} keys(%hash)) {
		next unless ($i);#this is to prevent strange tied hashes from creating iloops
		$self->_verbose("temp is $temp, i is $i and hash is $$hash{$i}");
		$temp =~ s/\$:$i/$hash{$i}/gi;
	}
	return $temp;
}

=item (scalar) C<_cgi_quote_set> ([scalar])

same as C<_quote_set>, but with the CGI environment option forced and no
interpreted hash option.

=cut

sub _cgi_quote_set {