+ $o1 = new ZOOM::Options();
+ $o1->option(user => "alf");
+ $o2 = new ZOOM::Options();
+ $o2->option(password => "fruit");
+ $opts = new ZOOM::Options($o1, $o2);
+ $conn = create ZOOM::Connection($opts);
+ $conn->connect($host); # Uses the specified username and password
+
+Several classes of ZOOM objects carry their own sets of options, which
+can be manipulated using their C<option()> method. Sometimes,
+however, it's useful to deal with the option sets directly, and the
+C<ZOOM::Options> class exists to enable this approach.
+
+Option sets are B<not currently described> in the ZOOM
+Abstract API at
+http://zoom.z3950.org/api/zoom-current.html
+They are an extension to that specification.
+
+=head3 Methods
+
+=head4 new()
+
+ $o1 = new ZOOM::Options();
+ $o1and2 = new ZOOM::Options($o1);
+ $o3 = new ZOOM::Options();
+ $o1and3and4 = new ZOOM::Options($o1, $o3);
+
+Creates and returns a new option set. One or two (but no more)
+existing option sets may be passed as arguments, in which case they
+become ``parents'' of the new set, which thereby ``inherits'' their
+options, the values of the first parent overriding those of the second
+when both have a value for the same key. An option set that inherits
+from a parent that has its own parents also inherits the grandparent's
+options, and so on.
+
+=head4 option() / option_binary()
+
+ $o->option(preferredRecordSyntax => "usmarc");
+ $o->option_binary(iconBlob => "foo\0bar");
+ die if length($o->option_binary("iconBlob") != 7);
+
+These methods are used to get and set options within a set, and behave
+the same way as the same-named C<Connection> methods - see above. As
+with the C<Connection> methods, values passed to and retrieved using
+C<option()> are interpreted as NUL-terminated, while those passed to
+and retrieved from C<option_binary()> are binary-clean.
+
+=head4 bool()
+
+ $o->option(x => "T");
+ $o->option(y => "F");
+ assert($o->bool("x", 1));
+ assert(!$o->bool("y", 1));
+ assert($o->bool("z", 1));
+
+The first argument is a key, and the second is a default value.
+Returns the value associated with the specified key as a boolean, or
+the default value if the key has not been set. The values C<T> (upper
+case) and C<1> are considered true; all other values (including C<t>
+(lower case) and non-zero integers other than one) are considered
+false.
+
+This method is provided in ZOOM-C because in a statically typed
+language it's convenient to have the result returned as an
+easy-to-test type. In a dynamically typed language such as Perl, this
+problem doesn't arise, so C<bool()> is nearly useless; but it is made
+available in case applications need to duplicate the idiosyncratic
+interpretation of truth and falsehood and ZOOM-C uses.
+
+=head4 int()
+
+ $o->option(x => "012");
+ assert($o->int("x", 20) == 12);
+ assert($o->int("y", 20) == 20);
+
+Returns the value associated with the specified key as an integer, or
+the default value if the key has not been set. See the description of
+C<bool()> for why you almost certainly don't want to use this.
+
+=head4 set_int()
+
+ $o->set_int(x => "29");
+
+Sets the value of the specified option as an integer. Of course, Perl
+happily converts strings to integers on its own, so you can just use
+C<option()> for this, but C<set_int()> is guaranteed to use the same
+string-to-integer conversion as ZOOM-C does, which might occasionally
+be useful. Though I can't imagine how.
+
+=head4 set_callback()
+
+ sub cb {
+ ($udata, $key) = @;
+ return "$udata-$key-$udata";
+ }
+ $o->set_callback(\&cb, "xyz");
+ assert($o->option("foo") eq "xyz-foo-xyz");
+
+This method allows a callback function to be installed in an option
+set, so that the values of options can be calculated algorithmically
+rather than, as usual, looked up in a table. Along with the callback
+function itself, an additional datum is provided: when an option is
+subsequently looked up, this datum is passed to the callback function
+along with the key; and its return value is returned to the caller as
+the value of the option.
+
+B<Warning.>
+Although it ought to be possible to specify callback function using
+the C<\&name> syntax above, or a literal C<sub { code }> code
+reference, the complexities of the Perl-internal memory management
+system mean that the function must currently be specified as a string
+containing the fully-qualified name, e.g. C<"main::cb">.>
+
+B<Warning.>
+The current implementation of the this method leaks memory, not only
+when the callback is installed, but on every occasion that it is
+consulted to look up an option value.
+
+=head4 destroy()
+
+ $o->destroy()
+
+Destroys an Options object, freeing its resources. It is an error to
+reuse an Options object that has been C<destroy()>ed.
projects / ZOOM-Perl-moved-to-github.git / blobdiff