General¶

Do I need to 'use Sub::Spec'?

No. Sub::Spec is just a specification. And your sub spec is just data structure (with some coderefs, for some clauses). There are modules that do stuffs using information from the sub spec, and you 'use' those.

Where should I put the specs?

Sub::Spec::URI::pm expects them to be in %SPEC package variables. Most other subroutine uses Sub::Spec::URI::pm to locate local specs.

I have created a spec, now what happens? What can it do for my sub?

Nothing. Just creating the spec won't magically change your sub, the spec is just a piece of data. You need one or more modules that do stuffs to your sub using the spec. Sub::Spec::Wrapper and Sub::Spec::Exporter should be the first one to see; they implement many of the basic clauses like 'args' for argument validation, 'timeout', etc. For the rest, browse Sub::Spec::* on CPAN to see a growing list of modules. Here's a partial list:

• Run subroutine from command line (see Sub::Spec::CmdLine)
• Create an API service (Sub::Spec::HTTP::Server)
• Use remote modules and call remote functions transparently (Sub::Spec::Use, Sub::Spec::URI::http)
• Generate documentation from spec (Sub::Spec::To::*)

Extending¶

Should I add a new feature clause, or a new spec clause?

For a fast rule, if your clause only describes what the sub does and does not include any wrapper code, then it probably goes into "features". Otherwise, it should go into a new spec clause.

For example, "reverse" is a feature clause, because it just states that if we pass "-reverse" => 1 argument to a sub, it will do a reverse operation. It doesn't include any wrapper code. On the other hand, 'timeout' is a spec clause because it involves the wrapping code doing an eval() and alarm() checking.