Merge pull request #2516 from ugexe/distribution-basics

Add basic Distribution docs
This is in a branch, so no test has passed; I guess we'll check it more thoroughly when it's merged.

Author: JJ

doc/Type/Distribution.pod6

@@ -0,0 +1,33 @@
+=begin pod
+
+=TITLE role Distribution
+
+=SUBTITLE Distribution
+
+    role Distribution { }
+
+Interface for objects that provide API access mapping META6 data to the files its represents.
+Objects that fulfill the C<Distribution> role can be read by e.g. L<CompUnit::Repository::Installation>.
+Generally a C<Distribution> provides read access to a set of modules and meta data. These
+may be backed by the file system (L<Distribution::Path>, L<Distribution::Hash>) but could
+also read from a e.g. tar file or socket.
+
+=head1 Required Methods
+
+=head2 method meta
+
+    method meta(--> Hash:D) { ... }
+
+Returns a Hash with the representation of the meta data. Please note that an actual META6.json
+file does not need to exist, just a representation in that format.
+
+=head2 method content
+
+    method content($name-path --> IO::Handle:D) { ... }
+
+Returns an C<IO::Handle> to the file represented by C<$name-path>. C<$name-path> is a relative
+path as it would be found in the meta data such as C<lib/Foo.pm6> or C<resources/foo.txt>.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6

doc/Type/Distribution/Hash.pod6

@@ -0,0 +1,36 @@
+=begin pod
+
+=TITLE class Distribution::Hash
+
+=SUBTITLE Distribution::Hash
+
+    class Distribution::Hash does Distribution::Locally { }
+
+A L<Distribution> implementation backed by the file system. It does not require a
+a C<META6.json> file, essentially providing a lower level C<Distribution::Path>.
+
+=head1 Methods
+
+=head2 method new
+
+    method new($hash, :$prefix)
+
+Creates a new C<Distribution::Hash> instance from the meta data contained in C<$hash>.
+All paths in the meta data will be prefixed with C<:$prefix>.
+
+=head2 method meta
+
+    method meta()
+
+Returns a Hash with the representation of the meta data.
+
+=head2 method content
+
+L<Distribution::Locally#method_content>
+
+Returns an C<IO::Handle> to the file represented by C<$name-path>. C<$name-path> is a relative
+path as it would be found in the meta data such as C<lib/Foo.pm6> or C<resources/foo.txt>.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6

doc/Type/Distribution/Locally.pod6

@@ -0,0 +1,29 @@
+=begin pod
+
+=TITLE class Distribution::Locally
+
+=SUBTITLE Distribution::Locally
+
+    role Distribution::Locally does Distribution { }
+
+Provides read access to specific files pointed at by a distributions meta data,
+providing the L<Distribution#method_content> method for L<Distribution::Path>
+and L<Distribution::Hash>.
+
+=head1 Methods
+
+=head2 method prefix
+
+A prefix path to be used in conjuncture with the paths found in the meta data.
+
+=head2 method content
+
+Provides L<Distribution#method_content>
+
+Returns an C<IO::Handle> to the file represented by C<$name-path>. C<$name-path> is a relative
+path as it would be found in the meta data such as C<lib/Foo.pm6> or C<resources/foo.txt>, and
+these paths will be prefixed with L<Distribution#method_prefix>.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6

doc/Type/Distribution/Path.pod6

@@ -0,0 +1,37 @@
+=begin pod
+
+=TITLE class Distribution::Path
+
+=SUBTITLE Distribution::Path
+
+    class Distribution::Path does Distribution::Locally { }
+
+A L<Distribution> implementation backed by the file system. It requires a
+C<META6.json> file at its root.
+
+=head1 Methods
+
+=head2 method new
+
+    method new(IO::Path $prefix, IO::Path :$meta-file = IO::Path)
+
+Creates a new C<Distribution::Path> instance from the C<META6.json> file found at the given
+C<$prefix>, and from which all paths in the meta data will be prefixed with. C<:$meta-file>
+may optionally be passed if a filename other than C<META6.json> needs to be used.
+
+=head2 method meta
+
+    method meta()
+
+Returns a Hash with the representation of the meta data.
+
+=head2 method content
+
+L<Distribution::Locally#method_content>
+
+Returns an C<IO::Handle> to the file represented by C<$name-path>. C<$name-path> is a relative
+path as it would be found in the meta data such as C<lib/Foo.pm6> or C<resources/foo.txt>.
+
+=end pod
+
+# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6