package Rinci; # just to make PodWeaver happy

1;
# ABSTRACT: Language-neutral metadata for your code


__END__
=pod

=head1 NAME

Rinci - Language-neutral metadata for your code

=head1 VERSION

version 1.1.7

=head1 SPECIFICATION VERSION

 1.1

=head1 ABSTRACT

This document describes B<Rinci>, a set of extensible, language-neutral metadata
specifications for your code (functions/methods, variables, packages, classes,
and so on). Rinci allows various helper tools, from code generator to web
middleware to documentation generator to other protocols, to act on your code,
making your life easier as a programmer. Rinci also allows better
interoperability between programming languages. Rinci is geared towards dynamic
scripting languages like Perl, Python, Ruby, PHP, JavaScript, but is not limited
to those languages.

=head1 STATUS

The 1.1 series does not guarantee full backward compatibility between revisions,
so caveat implementor. However, major incompatibility will bump the version to
1.2 or 2.0.

=head1 WHAT IS RINCI? (TERMINOLOGIES)

B<Rinci> is a set of specifications of metadata for your code entities. Each
different type of code entity, like function/method, variable, namespace, etc,
has its own metadata specification.

B<Metadata> is a set of name/value pairs stored in a regular mapping variable
(a.k.a. hash in Perl/Ruby, or dictionary in Python, or array in PHP, or object
in JavaScript/JSON; but from here on the term I<hash> will be used). Each
specification will describe what metadata B<property names> (a.k.a. hash keys)
are known and what value should each property contain. So the L<Rinci::function>
specification will describe metadata for functions/methods, L<Rinci::package>
will describe metadata for namespace/package, and so on.

Rinci defines properties pertaining to documentation (like C<summary>,
C<description>, C<examples>, C<links>), function argument and return value
validation (C<args> and C<result>), dependencies (C<deps>), standardized feature
description (C<features>), also a few conventions/protocols for doing stuffs
like undo (others like callback/progress report will follow). Basically anything
that can describe the code entity. The specification is extensible: you can
define more properties, or more deps, or more features.

=head1 WHAT ARE THE BENEFITS OF RINCI?

By adding Rinci metadata to your code, you can write/use tools to do various
things to your program. Rinci is designed with code generation and function
wrapping in mind. At the time of this writing, in Perl there exists several
tools (mostly modules under L<Perinci> namespace) to do the following:

=over 4

=item * L<Perinci::Sub::Wrapper>

Wrap functions with a single generated function that can do the following:
validate input (using information from the C<args> property), validate return
value (the C<result> property), add execution time-limiting (C<timeout>), add
automatic retries (C<retry>), interactive confirmation, logging, and more.

=item * L<Perinci::Exporter>

A replacement for L<Exporter> or L<Sub::Exporter> if your functions are equipped
with Rinci metadata. Automatically provide export tags (using information in the
C<tags> property). Can automatically wrap functions using Perinci::Sub::Wrapper
when exporting.

=item * Perinci::Sub::To::* modules

Convert function metadata to user/API documentation in POD or other format.
Basically all they do is just arranging the various available properties like
C<summary>, C<description>, C<args>, C<result>, C<examples>, C<links> and so on
and format them to the final target.

=item * L<Perinci::CmdLine>

L<Riap> command-line client. Call local/remote functions. Automatically convert
command-line options/arguments to function arguments. Generate help/usage
message (for C<--help>). Check dependencies (e.g. you can specify that in order
to run your functions, you need some executables/other functions to exist, an
environment variable being set, and so on), perform bash shell completion (using
L<Perinci::BashComplete>).

=item * L<Perinci::Access::HTTP::Server> (a.k.a. L<Periuk>)

A L<PSGI> application (a set of PSGI middlewares, really) to serve metadata and
function call requests over HTTP, according to the L<Riap::HTTP> protocol.

=item * L<Serabi>

An alternative for L<Perinci::Access::HTTP::Server> for REST-style service.

=item * L<Perinci::Use>

Use remote packages and import their functions/variables transparently like you
would use local Perl modules. The remote server can be any Riap-compliant
service, even when implemented in other languages.

=item * C<Perinci::Sub::Gen::*>

Since Rinci metadata are just normal data structure, they can be easily
generated. The Perinci::Sub::Gen::* Perl modules can generate functions as well
as their metadata, for example to access table data (like from a regular array
or from a SQL database).

=back

More tools will be written in the future.

=head1 RINCI VS ...

Some features offered by Rinci (or Rinci tools) are undoubtedly already offered
by your language or existing language libraries. For example, for documentation
Perl already has POD and Python has docstrings. There are numerous libraries for
argument validation in every language. Python has decorators that can be used to
implement various features like argument validation and logging. Perl has
subroutine attributes to stick additional metadata to your subroutines and
variables. And so on.

The benefits that Rinci offer include richer metadata, language neutrality,
extensibility, and manipulability.

B<Richer metadata>. Rinci strives to provide enough metadata for tools to do
various useful things. For example, the C<description> and C<summary> properties
support translations. Argument specification is pretty rich, with a quite
powerful and flexible schema language.

B<Language neutrality>. You can share metadata between languages, including
documentation and rules for argument validation. Perl 6 allows very powerful
argument validation, for example, but it is language-specific. With Rinci you
can easily share validation rules and generate validators in Perl and JavaScript
(and other target languages).

B<Manipulability>. Being a normal data structure, your Rinci metadata is easier
to manipulate (clone, merge, modify, export, what have you) as well as access
(from your language and others). Perl's POD documentation is not accessible from
the language (but Perl 6's Pod and Python docstrings are, and there are
certainly tools to parse POD). On the other hand, Python docstrings are attached
in the same file with the function, while with Rinci you can choose to separate
the metadata into another file more easily.

B<Other things to consider>. If you stack multiple decorators in Python, for
example, it usually results in wrapping your Python function multiple times,
which can add overhead. A single wrapper like L<Perinci::Sub::Wrapper>, on the
other hand, uses a single level of wrapping to minimize subroutine call
overhead.

B<Working together>. There is no reason why Rinci metadata has to compete
against existing features from language/libraries. A code generator for Rinci
metadata can generate code that utilize those features. For example, the
C<timeout> property can be implemented in Python using decorator, if you want.
Rinci basically just provides a way for you to express desired
properties/constraints/behaviours, separate from the implementation. A tool is
free to implement those properties using whatever technique is appropriate.

=head1 SPECIFICATION

Note: Examples are usually written in Perl, but this does not mean they only
apply to a particular language.

=head2 Terminologies

B<Code entities>, or just B<entities> for short, are elements in your code that
can be given metadata. Currently supported entities are function/method,
namespace/package, and variable. Other entities planned to be supported: class,
object, library, application.

=head2 Specification common to all metadata

This section describes specification common to all kinds of Rinci metadata.

B<Metadata>. Metadata is just a normal hash. Each hash key is called a property.
Any hash key in the metadata that starts with C<_> (underscore) is ignored, this
can be used to store extra data, implementation-specific properties, or
experimental (not yet standardized) properties. Otherwise, the property must be
known and valid. A property is valid if the property name matches the regex
pattern /\A[A-Za-z][A-Za-z0-9_]*([A-Za-z][A-Za-z0-9_]*)*\z/ (in other words, a
word or a dotted word like "foo" or "foo.bar") and the name is known (listed in
the specification), and the property values conform to the specification for
that property.

Metadata should be written in Unicode (UTF-8).

B<Custom properties>. The specification is extensible: you can add properties of
your own. Currently the mechanism to formally add a custom property to the
specification is unspecified, but at least in Perl it is recommended that the
distribution which does this updates the schema in C<Rinci::METATYPE::Schema>.
Popular custom properties might make it into core specification in later
revision or version.

B<Where to put the metadata>. The specification does not specify where to put
metadata in: it might be put alongside the code, separated in another source
code, encoded in YAML/JSON, put in database, or whatever. It is up to the
tools/implementations to provide the mechanism. If you use L<Perinci> in Perl,
there is a great deal of flexibility, you basically can do all of the above,
even split the metadata in several files. See its documentation for more
details.

B<Common properties>. Below are properties common to all metadata:

=head3 Property: v => FLOAT (required)

Declare specification version. This property is required. It should have the
value of 1.1. If C<v> is not specified, it is assumed to be 1.0 and metadata is
assumed to be the old, Sub::Spec 1.0.x metadata.

Example:

 v => 1.1

=head3 Property: default_lang => STR

Specify default language used in the text properties like C<summary> and
C<description>. Default is 'en_US'.

To specify translation texts in other languages, you can use
C<PROPERTY.alt.lang.CODE>, e.g.:

 summary => "Perform the foo ritual",
 "summary.alt.lang.id_ID" => "Laksanakan ritual foo",

=head3 Property: name => STR

The name of the entity. Useful when aliasing entity (and reusing the metadata)
and wanting to find out the canonical/original entity.

Examples:

 name => 'foo'
 name => '$var'  # only in languages where variables have prefix

=head3 Property: summary => STR

A one-line summary. It should be plain text without any markup. Please limit to
around 72 characters. It is like the C<summary> clause in L<Data::Sah>.

Example:

 # in variable metadata for $Answer
 summary => 'The answer to the question: what is the meaning of life'

 # in function metadata foo
 summary => 'Perform the foo ritual',

For variable metadata, it should describe what the variable contain. You do not
need to say "Contains ..." or "A variable that ..." since that is redundant;
just say directly the content of the variable (noun). You also do not need to
say what kinds of values the variable should contain, like "An integer, answer
to the ..." or "..., should be between 1..100" since that should go to the
C<schema> property.

For function metadata, it should describe what the function does. Suggestion:
use active, bare infinitive verb like in the example (not "Performs ..."). Avoid
preamble like "This function ..." since that is redundant. Also avoid describing
the arguments and its values like "..., accepts a single integer argument" as
that should go to the C<args> property.

To specify translations in other language, use the L<summary.alt.lang.CODE>.
Or change the C<default_lang> property. Examples:

 # default language is 'en_US'
 summary => 'Perform the foo ritual',
 "summary.alt.lang.id_ID" => 'Laksanakan ritual foo',

 # change default language to id_ID, so all summaries are in Indonesian, except
 # when explicitly set otherwise
 default_lang => 'id_ID',
 summary => 'Laksanakan ritual foo',
 "summary.alt.lang.en_US" => 'Perform the foo ritual',

=head3 Property: tags => ARRAY OF STR

A list of tags, useful for categorization. Can also be used by tools, e.g.
L<Perinci::Exporter> in Perl uses the C<tags> property of the function metadata
as export tags.

Example:

 # tag a function as beta
 tags => ['beta']

=head3 Property: description => STR

A longer description text. The text should be in marked up in format specified
by C<text_markup> and is suggested to be formatted to 78 columns. It is like the
C<description> Data::Sah clause.

To avoid redundancy, you should mentioning things that are already expressed as
properties, for example: return value of function (specify it in C<result>
property instead), arguments that the function accepts (C<args>), examples
(C<examples>), function's features (C<features>) and dependencies/requirements
(C<deps>).

For function, description should probably contain a more detailed description of
what the function does (steps, algorithm used, effects and other things of
note).

Example:

 {
     name => 'foo',
     summary => 'Perform the foo ritual',
     description => <<EOT,

 Foo ritual can be performed by humans or machines. This program will perform a
 machine-based ritual using [the best available
 algorithm](http://example.org/foo-with-bar-algo.html).

 Note that you still have to perform foo ritual manually from time to time, just
 to be safe.

 EOT
 }

Like in C<summary>, to specify translations in other language, use the
L<description.alt.lang.CODE> property.

=head3 Property: links => ARRAY OF HASHES

List to related entities or resources. Can be used to generate a SEE ALSO and/or
LINKS sections in documentation. Each link is a hash with the following keys:

=over 4

=item * uri => STR (required)

URI is used as a common syntax to refer to resources. If URI scheme is not
specified, tools can assume that it is a C<riap> URI (see L<Riap>).

=item * title => STR

A short plaintext title for the link.

=item * description => STR

A longer marked up text description for the link. Suggested to be formatted to
76 columns.

=item * tags => ARRAY OF STR

Can be used to categorize or select links. For generating SEE ALSO sections, use
the tag 'see'.

=back

Example:

 # links in the Bar::foo function metadata
 links => [
     {
         url   => "http://example.org/foo-with-bar-algo.html",
         title => "Article describing foo using Bar algorithm",
     },
     {
         url   => "../Bar2/",
         title => "Another implementation of the Bar algorithm",
         tags  => ['see'],
     },
 ],

=head3 Property: text_markup => STR

Specify text markup format for the content of properties which contain marked-up
text, like C<description>. The default is C<markdown>
(http://en.wikipedia.org/wiki/Markdown) and other valid values include C<org>
(http://orgmode.org/) and C<none>.

NOTE: Other popular text markup formats might be added in the future. Text
format should be readable as-is (so-called "plain text markup format") as some
tools, like L<Perinci::CmdLine> in Perl will just dump the content
C<description> as text help message instead of going through the trouble of
passing the content through some formatters.

 # use Org format for all marked up text
 text_markup => 'org'

NOTE: Supporting different markup format for different properties, e.g.
C<markdown> for C<description> but C<org> for other properties (or perhaps
different format between arg's description and link's description) might be
considered in the future if necessary, but for now such practice is not
recommended.

=head2 Entity-specific specifications

Each entity-specific specification is described on a separate subdocument.
Currently these specifications are defined:

=over 4

=item * L<Rinci::function> - Metadata for functions/methods

=item * L<Rinci::package> - Metadata for namespaces/packages

=item * L<Rinci::variable> - Metadata for variables

=back

These specifications are planned or considered, but not yet defined:

=over 4

=item * L<Rinci::class> - Metadata for classes

=item * L<Rinci::object> - Metadata for objects

=item * L<Rinci::application> - Metadata for applications

=item * L<Rinci::library> - Metadata for libraries

=item * L<Rinci::distribution> - Metadata for software distribution

=item * L<Rinci::language> - Metadata for programming languages

=item * L<Rinci::author> - Metadata for software authors

=item * L<Rinci::project> - Metadata for software projects

=item * L<Rinci::repository> - Metadata for code repository (like git, svn)

=back

=head1 FAQ

=head2 What does Rinci mean?

Rinci is taken from Indonesian word B<perincian> or B<rincian>, meaning:
specification, detail.

=head2 Why use Sah for data schema?

Sah is a flexible and extensible schema language, while still not being
language-specific, making it easy for code generator tools to generate validator
code in various target languages (Perl, Ruby, etc).

=head1 HISTORY

Below is the general history of the project and major changes to the
specifications. For more detailed changes between releases, see the B<Changes>
file in the distribution.

=head1 1.1 (Jan 2012)

To clearly separate specification from implementation, rename specification from
C<Sub::Spec> to C<Rinci> (the namespace C<Perinci> is now used for the Perl
implementation). Support code entities other than functions/methods. Bump
specification version from 1.0 to 1.1 due to several incompatibilities like
changed C<args> and C<result> properties, terminologies, defaults. Versioning
property (C<v>) now required.

=head2 1.0 (Aug 2011)

First release version of Sub::Spec.

=head2 0.x (Feb-Aug 2011)

Series of Sub::Spec drafts.

=head2 Spanel project (2009-2010)

I started using some metadata for API functions, calling them spec and putting
them in %spec instead of in POD, so I can list and grab all the summaries easily
as a single dump for API catalog (instead of having to parse POD from my source
code files). Later on I kept adding more and more stuffs to this, from argument
specification, requirements, and so on.

=head1 SEE ALSO

=head2 Related specifications

Sah schema language, L<Data::Sah>

L<Rinci::HTTP>

=head2 Related ideas/concepts

B<.NET attributes>, http://msdn.microsoft.com/en-us/library/z0w1kczw.aspx

B<Python Decorators>, http://www.python.org/dev/peps/pep-0318/ ,
http://wiki.python.org/moin/PythonDecorators

=head2 Other related links

B<Acmeism>, http://www.acmeism.org/

=head1 AUTHOR

Steven Haryanto <stevenharyanto@gmail.com>

=head1 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.

=cut

