=encoding utf8

=for syntax specification:
https://perldoc.perl.org/perlpod

=head1 NAME

F<epgsearchuservars.conf> – user-defined variables

=head1 DESCRIPTION

This file defines variables that can be used in EPGSearch wherever
variables are applicable. This, for example, applies for the default
recording directory of a manually created timer, the recording
directory of a search timer, or a customized EPG menu.

=head1 SYNTAX

A variable has the syntax C<%VariableName%>. Its name can comprise all
alphanumeric characters, but no spaces or other special characters.

Examples for possible names:

=over 4

    %Series%
    %DocuVar1%
    %ThemesSubtitleDate%

=back

Variable names are case-insensitive.

=head2 Assignment

Variables always get assigned strings whose spaces are retained.
This is illustrated by the following examples:

=over 4

    %Series%=New series~Thrillers

=back

The variable C<%Series%> will be assigned the string "New series~Thrillers".
This can be used arbitrarily:

=over 4

    %Path%=%Series%

=back

The variable C<%Path%> gets the content of the variable C<%Series%> assigned.

=over 4

    %Path%=%Series%~Lost

=back

The variable C<%Path%> contains the string "New series~Thrillers~Lost".

=head2 Conditional assignment

Simple if-then-else constructs for assignments are supported by means of
conditional expressions C<I<if> ? I<then> : I<else>>. Conditional expressions
cannot contain strings, only variables; spaces are ignored.

=over 4

    %Foo%=Other
    %Variable%=%Path% ? %Path% : %Foo%

=back

For the ternary operator C<?:>, the expression C<%Path% ?> means
"path not empty?". If this is true, C<%Variable%> gets assigned
the content of C<%Path%>, else the content of C<%Foo%>.

Other checks are supported as well:

=over 4

=over 4

=item == equal

=item != not equal

=back

=back

Thus, for example:

=over 4

    %Variable%=%Path%!=5 ? %Path% : %Foo%

=back

The condition C<%Path%!=5 ?> means "is C<%Path%> not equal 5?".

Comparing variables is also feasible:

=over 4

    %Five%=5
    %Variable%=%Path%!=%Five% ? %Path% : %Foo%

=back

=head2 Calling a system command

External commands can be called during variable evaluation as well.
The returned string will be assigned to the respective variable:

=over 4

    %UserVar%=system(<script-name>[, <parameters>])

=back

Calls the script F<script-name> with the parameters supplied in the optional list
C<parameters>. Such a parameter can be an arbitrary expression, optionally containing
other variables, but no system call or conditional expression.

Example:

=over 4

    %Result%=system(/usr/local/bin/my-script.sh, -t %Title% -s %Subtitle% -u %MyOtherVar%)

=back

Variables used as parameters will be enclosed in single quotes
(apostrophes), if needed.

The script should return a string B<without line feeds>, since their
removal may cause undesired results.
If the script does not return anything, an empty string will be assigned to the
variable C<%Result%>.

=head2 Calling a TCP service

A TCP service can be called with the following syntax:

=over 4

    %Result%=connect(<address>, <port>, [<data>])

=back

This will connect to C<address> through the given C<port> and pass the optional
C<data>. The parameter C<address> can be an IP address or the domain name of a
TCP service. The result returned by the service must be terminated B<with a
line feed>.

=head2 Getting the length of an argument

When passing values to the connect or system command, it can be helpful to have
the length of an argument for simple parsing. The length can be retrieved by:

=over 4

    %Result%=length(<any arguments>)

=back

Example:

=over 4

    %TitleLength%=length(%title%)

=back

=head2 Other variables

Refer to B<epgsearchmenu.conf>(5) for a list of built-in variables.
Furthermore, every variable defined in F<epgsearchcats.conf> can be used;
see B<epgsearchcats.conf>(5) for details.

=head1 Example

    # Weekday, Date, Time
    %DateStr%=%time_w% %date% %time%

    # Themes or Subtitle or Date
    %SubtitleDate%=%Subtitle% ? %Subtitle% : %DateStr%
    %ThemesSubtitleDate%=%Themes% ? %Themes% : %SubtitleDate%

    # Calls a script to get a recording path
    %DocuScript%=system(docu.pl, -t %Title% -s %Subtitle% -e %Episode% -th %Themes% -c %Category% -g %Genre%)
    %Docu%=%DocuScript%

=head1 AUTHORS (man pages)

Originally provided by Mike Constabel <epgsearch (at) constabel (dot) net>.

Revised and adapted to recent plugin features by the current maintainers.

=head1 PROJECT SITE

The plugin is maintained as GitHub project:

L<https://github.com/vdr-projects/vdr-plugin-epgsearch/>

=head1 REPORTING BUGS

Issues can be reported, and features be suggested, through the project's
bug tracker:

L<https://github.com/vdr-projects/vdr-plugin-epgsearch/issues/>

=head1 COPYRIGHT and LICENSE

Copyright (C) 2004-2010 Christian Wieninger

Copyright © 2011-2025 TomJoad (VDR-Portal), et al.

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Or, point your browser to L<https://www.gnu.org/licenses/old-licenses/gpl-2.0.html>

The original author can be reached via L<cwieninger@gmx.de>.

Current maintainers can be reached via the project's GitHub site (see above).

The MD5 code has been derived from the MD5 Message-Digest Algorithm of RSA Data Security, Inc.

=head1 SEE ALSO

B<epgsearch>(1), B<epgsearch>(4), B<epgsearchcats.conf>(5), B<epgsearchmenu.conf>(5)
