NAME

Sub::Spec::FAQ - Frequently asked questions about Sub::Spec

VERSION

version 1.0.7

QUESTIONS

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.

AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Steven Haryanto.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.