Hello Aldebaran,

I thought that I would emulate the syntax in source listing for Translate.pm. (Is this well-written?)

Not entirely — see below.

With this syntax, I believe that $param_hr is to be understood as an existing reference to a hash of parameters. I believe that this is the main data structure for this object.

Correct in both cases.

I've been looking at the rest of the code for new here. What does this do?

The for loop iterates through the keys of %self (in no particular order) — i.e., "key", "format", "model", etc. — assigning each in turn to $property. The if condition checks whether the current property is an entry in the user-supplied hash referenced by $param_hr:

• If not, the property keeps its default value assigned previously in my %self = (...);
• If so, the line $self{$property} = delete $param_hr->{$property}; deletes the entry from the user-supplied hash and assigns (overwrites) it to $self.

But first, there is a check to ensure that the data type of the user-supplied entry matches the type expected by new(). This check is performed using the built-in function ref, which is documented as follows:

ref EXPR
...
Examines the value of EXPR, expecting it to be a reference, and returns a string giving information about the reference and the type of referent....

If the operand is not a reference, then the empty string will be returned. An empty string will only be returned in this situation. ref is often useful to just test whether a value is a reference, which can be done by comparing the result to the empty string. It is a common mistake to use the result of ref directly as a truth value: this goes wrong because 0 (which is false) can be returned for a reference.

— which is why I said above that the code is not entirely well-written: instead of testing directly against the empty string, the code first changes an empty string into the string 'String', which is not only unnecessary, but in fact is the “common mistake” mentioned in the documentation.

It would seem to check whether certain values are strings, but I don't understand the right hand side with

ref something  || something else
[download]

No, it’s not checking whether values are strings, it’s checking whether values are references. (In this case, only the value associated with the headers key will actually be a reference.) The || (logical OR) operator checks its LHS first and returns it if it is true; otherwise, it returns the RHS. So in the lines:

my $type          = ref $param_hr->{$property} || 'String';
my $expected_type = ref $self{$property}       || 'String';
[download]

the first line assigns 'String' to $type if, and only if, the expression ref $param_hr->{$property} evaluates to a value which Perl considers “false.” If $param_hr->{$property} is not a reference, ref returns the empty string (""), which Perl does consider false, so the || operator evaluates to 'String'.

Hope that helps,