NAME

Params::Validate::Dependencies::Extending - how to extend Params::Validate::Dependencies

DESCRIPTION

How to extend Params::Validate::Dependencies, and a discussion of its internals.

PRE-REQUISITES

Before even thinking about extending this module you should understand references, in particular code-references and closures, and also understand objects in perl.

WHAT THE *_of FUNCTIONS REALLY DO

If you've read the documentation for Params::Validate::Dependencies, then you'd think that it returns a code-ref which is a closure over the original arguments, and that they're implemented something like this:

  sub any_of {
    my @options = @_;
    return sub {
      my $hashref = shift;
      ... do stuff with @options and $hashref ...
    }
  }

In version 1, that was exactly what was happening. But then I wanted to make them self-documenting.

Now, they still return a code-ref, but that code-ref is blessed into a class - Params::Validate::Dependencies::any_of in the case of the closures generated by any_of - so that I can attach a little bit of extra metadata. They now look something like this:

  sub any_of {
    my @options = @_;
    bless sub {
      ... some extra stuff ...
      my $hashref = shift;
      ... do stuff with @options and $hashref ...
    }, 'Params::Validate::Dependencies::any_of';
  }

There are four such classes, one for each of the *_of functions.

HOW THE AUTO-DOCUMENTATION WORKS

Each of those four classes is a sub-class of Params::Validate::Dependencies::Documenter. When you call Params::Validate::Dependencies::document() and pass it one of those objects, it calls the object's _document method. That puts P::V::D into "documentation mode" by setting a global variable to the object itself, and then executes the object's underlying code-ref.

In the example above, where it says "... some extra stuff ...", we actually have this:

  if($Params::Validate::Dependencies::DOC) {
    return $Params::Validate::Dependencies::DOC->_doc_me(list => \@options);
  }

so, now that <$DOC> has a value, the code-ref doesn't bother validating anything, it instead calls its _doc_me method, and passes it the options that the closure was originally created with.

Finally, _doc_me, which now has both the data that was originally closed over, and the object itself, it can construct a useful string of documentation. To do this it gets the name of the original factory function by calling the object's name method - in the case of a Params::Validate::Dependencies::any_of object this returns 'any_of' - and, so that it can use 'and' or 'or' when constructing lists, it gets that by calling the join_with method.

It then iterates over the original list of options, scalars first followed by code-reffy objects, recursing into objects and getting them to document themselves.

The end result of that, given a code-ref created thus:

  any_of(
    qw(alpha beta),
    all_of(
      qw(foo bar),
      none_of('barf')
    ),
    one_of(qw(quux garbleflux))
  )

You will get back documentation like this:

  any of ('alpha', 'beta', all of ('foo', 'bar' and none of ('barf')) or one of ('quux' or 'garbleflux'))

which is admittedly not perfect but is better than having to write the blasted stuff yourself.

ADDING YOUR OWN VALIDATORS WITHOUT DOCUMENTATION

If you can't be bothered with making your validators self-documenting, then you can just have them return a closure and be done with it:

  sub two_of {
    my @options = @_;
    return sub {
      my $hashref = shift;
      my $count = 0;
      foreach my $option (@options) {
        $count++ if(
          (!ref($option) && exists($hashref->{$option})) ||
          (ref($option) && $option->($hashref))
        );
      }
      return ($count == 2);
    }
  }

There is an example of this in t/05-extra-validator-without-doco.t. In fact it's this very example.

ADDING YOUR OWN VALIDATORS WITH AUTO-DOCUMENTATION

If you want to do the full-fat implementation complete with auto-doc, then you will need to implement one teeny-tiny class, as well as modify your factory function to return an object of that class and to look out for "documentation mode" being turned on. The example above would be modifed thus:

  sub two_of {
    my @options = @_;
    return bless sub {
      if($Params::Validate::Dependencies::DOC) {
        return $Params::Validate::Dependencies::DOC->_doc_me(list => \@options);
      }
      ...
    }, 'Params::Validate::Dependencies::two_of'
  }

and the corresponding class would look like:

  package Params::Validate::Dependencies::two_of;
  use base qw(Params::Validate::Dependencies::Documenter);
  sub join_with { return 'or'; }
  sub name { return 'two_of'; }

It is suggested that you combine class and function together, and have it export the function, as can be seen in the example in t/lib/Params/Validate/Dependencies/two_of.pm, which is used in t/06-extra-validator-with-doco.t.

CUSTOM AUTO-DOCUMENTATION

If the _doc_me method described above can't cope with your new validation function then your class need not bother implementing the name or join_with methods, but your function must, when <$Params::Validate::Dependencies::DOC> is set, return a string. Anything that you want the exclusively() validator to pay attention to needs to be single quoted, with any embedded single quotes preceded by a back-slash.

Best practice is to return something that looks very similar to how your function was invoked in the first place.

For an example see how the exclusively() function documents itself.

RESERVED CLASSES

You may not write your own validators or classes for the following, as they are implemented by Params::Validate::Dependencies itself. If you try implementing them, strange things may happen:

none_of

one_of

any_of

all_of

exclusively

SEE ALSO

Params::Validate::Dependencies

SOURCE CODE REPOSITORY

git://github.com/DrHyde/perl-modules-Params-Validate-Dependencies.git

https://github.com/DrHyde/perl-modules-Params-Validate-Dependencies/

COPYRIGHT and LICENCE

Copyright 2024 David Cantrell <david@cantrell.org.uk>

This documentation is free-as-in-speech software. It may be used, distributed, and modified under the terms of the Creative Commons Attribution-Share Alike 2.0 UK: England & Wales License, whose text you may read at http://creativecommons.org/licenses/by-sa/2.0/uk/.

CONSPIRACY

This documentation is also free-as-in-mason.

cpanm Params::Validate::Dependencies

perl -MCPAN -e shell
install Params::Validate::Dependencies