PerlWrapper is a tool for creating analysis components using the Perl programming language for scripting. It automatically wraps a Perl program so that the Analysis Server can interact with it. The complexity of the components created using PerlWrapper is theoretically limited only by the complexity of the Perl language.
However, PerlWrapper restricts Perl's input and output operations for the sake of simplicity. Therefore, the utility is best used when creating simple components.This chapter discusses how to build a PerlWrapper utility by taking the user through a simple example.
In order to create Analysis Server components with PerlWrapper, the user must have the following:
No new Analysis Server-specific terms will be presented in this section. For further information on the Perl specific terms, consult a Perl programmer's guide.
In order for the component to execute properly, it must be a working Perl file. The utility transforms the Perl script to a component using the following simple rules: all variables initialized from standard input (for example, $input1 = <STDIN> ;) are recorded as inputs to the component, and all values printed to standard output (for example, print $output1 ;) are recorded as outputs from the component. The Perl script becomes the component's execute function.
In that sense, the PerlWrapper does not have a unique set of commands; Perl functions provide this. PerlWrapper provides further restrictions on Perl's input and output syntax. It also supplements basic Perl with tags for filling the component's descriptive fields.
All inputs must have the following form to be properly established as component input properties:
$var_name = <STDIN>; # comments permissible afterwards
The following input lines are valid for Perl executables, but are not allowed in PerlWrapper components:
chop ($var_name = <STDIN>); # a common Perl # trick $var1 = <STDIN>; $var2 = <STDIN>; # Each input # must be on a # new line. print "Input a value: "; $var = <STDIN>; # Prompt not # permitted.
Each input variable in the component must be entered on its own line in the form of a simple assignment to standard input. Input variables can only be given a value once from standard input, but their values can be changed inside of the Perl program after they are assigned:
$current_employee = <STDIN>; $Hal = $current_employee; $current_employee = <STDIN>;
is NOT permissible, but
$current_employee = <STDIN>; $Hal = $current_employee; $current_employee = $Bob;
IS permissible.
Finally, comments are permissible after input variable assignments. There is a special case in which PerlWrapper obtains additional information from a comment string found on the same line as an input assignment. If the first word in the comment string is a number, then PerlWrapper will assume that the number is the default value for the input variable. If the user runs the PerlWrapper component in the Analysis Server without explicitly setting the value of an input, the Analysis Server will use the input's default value to run the component. An input with a default value looks like this:
$Value = <STDIN>; # 5.0 variable description
The Analysis Server will initially set $Value to 5.0 when creating an object based upon the PerlWrapper component that owns $Value . $Value will remain set to 5.0 until the user explicitly changes it with a set function. Any words appearing on the same comment line will become a part of the variable's description.
Output variables must be simple print statements with the form:
print $varname; print "\n" # Comments are permitted # here .
or
print $varname; # Comments are also print "\n"; # permitted here.
They cannot contain any formatting or additional printed information in the print statement. The following valid Perl output statements will all lead to errors in PerlWrapper components:
print "The value = $value.\n"; # No additional formatting # is permitted. print FILE $value; # File output is not # permitted. print $bob; print $hal; # Each output must be on # its own line of code. print $value; print "\n"; # Outputs cannot be # printed twice. print $value; print "\n"; # They can be assigned # multiple times before # printout, however.
This example shows how to write a PerlWrapper component that computes the area of a circle given a radius. The program is simple yet is sufficient to demonstrate the basic principles.
# # @author: Phoenix Integration # @helpURL: http://www.phoenix-int.com # @version: 1.0 # @description: Computes a circle's area given a radius. # # This is an example of a PerlWrapper component. The # Analysis Server will recognize radius as an input # with initial value of 1, and will recognize area # as an output. # $radius = <STDIN>; # 1.0 $pi = 3.1415926; $area = $pi * $radius * $radius; print $area; print "\n";
A header is not really required to make a component. However, it is good practice to document components thoroughly. PerlWrapper naturally ignores Perl comment lines, so the component author can write any comments that he would normally write into Perl code.
PerlWrapper searches through comments looking for special tags, and uses these tags to document the component. Lines one through four all contain tags that PerlWrapper will use when writing the descriptive fields of the component . Lines six through ten are plain Perl comments that PerlWrapper ignores. They further explain the purpose of the component to future maintainers of the code. Additional information about header tags can be found in the components section.
As mentioned above, the component's input variables are those that take assignments from standard input, and the output variables are those that get written directly to standard output followed by another print statement containing a carriage return. The analysis can have any number of internal variables and can perform an unrestricted number of non-I/O operations. This example simply returns an area based upon the formula A = pi(r2), where A is the area and r is the radius of the circle.
In order to compute the area, the component must first get the radius from the user in line twelve. Line 12 establishes the variable $radius as a component input, and assigns it a default value of 1.0. Lines thirteen and fourteen compute the area. The variable $pi was not assigned from standard input, and therefore is an internal variable that will remain hidden to Analysis Server users who run the PerlCircle component. $area , the output variable, is written to standard output in line sixteen.
In order to publish the component on the Analysis Server, the author must place the Perl file in the Analysis Server's designated "analyses" directory or in one of the designated "public_aserver" directories with the suffix ".aspl".
Despite PerlWrapper's additional syntax, a PerlWrapper component is a functional Perl executable. It can therefore be fully tested and debugged outside of the Analysis Server prior to publishing it as a component.
See also Analysis Server