Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Move CompUnitRepo API description from S11 to S22
  • Loading branch information
lizmat committed Mar 16, 2014
1 parent 48fdab6 commit 37bf0dc
Show file tree
Hide file tree
Showing 2 changed files with 51 additions and 46 deletions.
49 changes: 3 additions & 46 deletions S11-modules.pod
Expand Up @@ -64,6 +64,9 @@ compunits as files in directories. Of course, one is free to devise any
other way of storing and searching for compunits, as long as C<API> is the
same.

See L<S22/"Distributions, Recommendations, Delivery and Installation"> for
more information about the C<CompUnitRepo> interface.

=head1 Modules

As in Perl 5, a C<module> is just a kind of package. Unlike in Perl 5, modules
Expand Down Expand Up @@ -714,50 +717,4 @@ profile of the interface. It must be possible to extract out the
language tweaking part of this profile for use in tools that wish to
know how to parse the current language variant deterministically.

=head1 CompUnitRepo

Base class (interface, really) for the object living in the @*INC array. Used
both for installing compunits, as well as finding a certain compunit by way
of its from, longname, auth and ver information.

=head2 new

my $repo = CompUnitRepo.new( $location );

Create a new CompUnitRepo object, either for inclusion in C<@*INC>, or to
install a compilation unit.. The parameter indicates the location in
which compunits are supposed to be located for this object. This could be a
local directory (as in the case of L<CompUnitRepo::Local::File> and
L<CompUnitRepo::Local::Installation>). Or it could be anything that indicates
a remote repository, such as a connect string to a database, or a URL to a
an authority (such as CPAN or Github). Returns the instantiated object.

=head2 install

my $installed = $repo.install(...);

Install a compilation unit in the appropriate way for this object. May cause
a fatal exception if this repository does not support installing. The first
parameter contains the actual source-code of the compilation unit to be
installed. The named parameters indicate the other meta-information to be
associated with the compunit. Returns whether compilation unit was installed.

Of course, any implementation of L<CompUnitRepo>'s C<install> interface, may
decide to accept additional meta-information and store this and make available
for later introspection.

=head2 candidates

my @candidates = $repo.candidates( $longname, $auth?, $ver?, $from? );

Return L<CompUnit> candidates given the matching credentials.

=head1 CompUnit

The object that describes a compilation unit.

=head2 load

my $loaded = @candidates[0].load;

=for vim:set expandtab sw=4:
48 changes: 48 additions & 0 deletions S22-package-format.pod
Expand Up @@ -449,4 +449,52 @@ select the C<CompUnitRepo> in which the distribution should be installed, and
the recommendation manager that should be used to convert requests for a
compilation unit into an identity of a distribution to be downloaded.

=head2 Classes

=head3 CompUnitRepo

Base class (interface, really) for the object living in the @*INC array. Used
both for installing compunits, as well as finding a certain compunit by way
of its from, longname, auth and ver information.

=head3 new

my $repo = CompUnitRepo.new( $location );

Create a new CompUnitRepo object, either for inclusion in C<@*INC>, or to
install a compilation unit.. The parameter indicates the location in
which compunits are supposed to be located for this object. This could be a
local directory (as in the case of L<CompUnitRepo::Local::File> and
L<CompUnitRepo::Local::Installation>). Or it could be anything that indicates
a remote repository, such as a connect string to a database, or a URL to a
an authority (such as CPAN or Github). Returns the instantiated object.

=head3 install

my $installed = $repo.install(...);

Install a compilation unit in the appropriate way for this object. May cause
a fatal exception if this repository does not support installing. The first
parameter contains the actual source-code of the compilation unit to be
installed. The named parameters indicate the other meta-information to be
associated with the compunit. Returns whether compilation unit was installed.

Of course, any implementation of L<CompUnitRepo>'s C<install> interface, may
decide to accept additional meta-information and store this and make available
for later introspection.

=head3 candidates

my @candidates = $repo.candidates( $longname, $auth?, $ver?, $from? );

Return L<CompUnit> candidates given the matching credentials.

=head2 CompUnit

The object that describes a compilation unit.

=head3 load

my $loaded = @candidates[0].load;

=for vim:set expandtab sw=4:

0 comments on commit 37bf0dc

Please sign in to comment.