=encoding utf8

=head1 NAME

Couch::DB::Design - handle design documents

=head1 INHERITANCE

 Couch::DB::Design
   is a Couch::DB::Document

=head1 SYNOPSIS

  my $ddoc = Couch::DB::Design->new(id => 'myname', db => $db);
  my $ddoc = $db->design('myname');          # same
  my $ddoc = $db->design('_design/myname');  # same
  my $ddoc = $db->design;  # id generated

  my $results = $db->design('d')->search('i', ...) or die;
  my $results = $db->search(d => 'i', ...); # same
  my $results = $db->search($ddoc => 'i', ...); # same

=head1 DESCRIPTION

In CouchDB, design documents provide the main interface for building
a CouchDB application. The design document defines the views used to
extract information from CouchDB through one or more views.

Design documents behave just like your own documents, but occupy the
C<_design/> namespace in your database.  A bunch of the methods are
therefore exactly the same as the methods in base-class
L<Couch::DB::Document|Couch::DB::Document>.

Extends L<"DESCRIPTION" in Couch::DB::Document|Couch::DB::Document/"DESCRIPTION">.
 
=head1 METHODS

Extends L<"METHODS" in Couch::DB::Document|Couch::DB::Document/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in Couch::DB::Document|Couch::DB::Document/"Constructors">.
 
=over 4

=item Couch::DB::Design-E<gt>B<fromResult>($result, $data, %options)

Inherited, see L<Couch::DB::Document/"Constructors">

=item Couch::DB::Design-E<gt>B<new>(%options)

If no id is passed, then one gets generated: a UUID is requested from
the server.  You may also use a local generator via UUID::URandom
or Data::UUID, which is (of course) more efficient.

 -Option --Defined in         --Default
  batch    Couch::DB::Document  from database
  content  Couch::DB::Document  undef
  db       Couch::DB::Document  undef
  id       Couch::DB::Document  generated
  local    Couch::DB::Document  false
  row      Couch::DB::Document  undef

=over 2

=item batch => BOOLEAN

=item content => DATA

=item db => L<Couch::DB::Database|Couch::DB::Database>-object

=item id => ID

=item local => BOOLEAN

=item row => L<Couch::DB::Row|Couch::DB::Row>-object

=back

=back

=head2 Accessors

Extends L<"Accessors" in Couch::DB::Document|Couch::DB::Document/"Accessors">.
 
=over 4

=item $obj-E<gt>B<batch>()

Inherited, see L<Couch::DB::Document/"Accessors">

=item $obj-E<gt>B<couch>()

Inherited, see L<Couch::DB::Document/"Accessors">

=item $obj-E<gt>B<db>()

Inherited, see L<Couch::DB::Document/"Accessors">

=item $obj-E<gt>B<id>()

Inherited, see L<Couch::DB::Document/"Accessors">

=item $obj-E<gt>B<idBase>()

Various calls need the C<id> without the C<_design>.  Whether the
full document id for the design document or only the unique part
is required/given is confusing.  This method returns the unique
part.

=item $obj-E<gt>B<row>( [$row] )

Inherited, see L<Couch::DB::Document/"Accessors">

=item Couch::DB::Design-E<gt>B<setIdGenerator>(CODE)

When a design document is created without explicit C<id>, that will
get generated.  By default, this is done by requesting a fresh UUID
from the server.  You may change this into some local random collission
free id generator for better performance.

The CODE is called with the daabase object as only parameter.

=back

=head2 Content

Extends L<"Content" in Couch::DB::Document|Couch::DB::Document/"Content">.
 
=over 4

=item $obj-E<gt>B<isDeleted>()

Inherited, see L<Couch::DB::Document/"Content">

=item $obj-E<gt>B<isLocal>()

Inherited, see L<Couch::DB::Document/"Content">

=item $obj-E<gt>B<latest>()

Inherited, see L<Couch::DB::Document/"Content">

=item $obj-E<gt>B<rev>()

Inherited, see L<Couch::DB::Document/"Content">

=item $obj-E<gt>B<revision>($rev)

Inherited, see L<Couch::DB::Document/"Content">

=item $obj-E<gt>B<revisions>()

Inherited, see L<Couch::DB::Document/"Content">

=back

=head2 Document details

Extends L<"Document details" in Couch::DB::Document|Couch::DB::Document/"Document details">.
 
=over 4

=item $obj-E<gt>B<conflicts>()

Inherited, see L<Couch::DB::Document/"Document details">

=item $obj-E<gt>B<deletedConflicts>()

Inherited, see L<Couch::DB::Document/"Document details">

=item $obj-E<gt>B<revisionInfo>($revision)

Inherited, see L<Couch::DB::Document/"Document details">

=item $obj-E<gt>B<revisionsInfo>()

Inherited, see L<Couch::DB::Document/"Document details">

=item $obj-E<gt>B<updateSequence>()

Inherited, see L<Couch::DB::Document/"Document details">

=back

=head2 Document in the database

All methods below are inherited from standard documents.  Their call URI
differs, but their implementation is the same.  On the other hand: they
add interpretation on fields which do not start with '_'.

Extends L<"Document in the database" in Couch::DB::Document|Couch::DB::Document/"Document in the database">.
 
=over 4

=item $obj-E<gt>B<appendTo>($doc, %options)

 [CouchDB API "COPY /{db}/_design/{ddoc}"]

=item $obj-E<gt>B<cloneInto>($doc, %options)

 [CouchDB API "COPY /{db}/_design/{ddoc}"]

=item $obj-E<gt>B<create>(\%data, %options)

 [CouchDB API "POST /{db}/_index", UNTESTED]
Create a new design document.

In Couch::DB, the client-side, not the server, generates ids.  Therefore,
this method is equivalent to L<update()|Couch::DB::Design/"Document in the database">.

 -Option--Defined in         --Default
  batch   Couch::DB::Document  new(batch)

=over 2

=item batch => BOOLEAN

=back

=item $obj-E<gt>B<delete>(%options)

 [CouchDB API "DELETE /{db}/_design/{ddoc}"]

=item $obj-E<gt>B<details>(%options)

 [CouchDB API "GET /{db}/_design/{ddoc}/_info", UNTESTED]

Obtains information about the specified design document, including the
index, index size and current status of the design document and associated
index information.

=item $obj-E<gt>B<exists>(%option)

 [CouchDB API "HEAD /{db}/_design/{ddoc}"]

Returns the HTTP Headers containing a minimal amount of information about the
specified design document.

=item $obj-E<gt>B<get>(%options)

 [CouchDB API "GET /{db}/_design/{ddoc}"]

=item $obj-E<gt>B<update>(\%data, %options)

 [CouchDB API "PUT /{db}/_design/{ddoc}"]

Options C<filters>, C<lists>, C<shows>, and C<updates> are HASHes which
map names to fragments of code written in programming language C<language>
(usually erlang or javascript).

Options C<lists>, C<show>, and C<rewrites> (query redirection) are
deprecated since 3.0, and are removed from 4.0.

 -Option--Defined in         --Default
  batch   Couch::DB::Document  new(batch)

=over 2

=item batch => BOOLEAN

=back

=back

=head2 Attachments

Extends L<"Attachments" in Couch::DB::Document|Couch::DB::Document/"Attachments">.
 
=over 4

=item $obj-E<gt>B<attDelete>($name, %options)

 [CouchDB API "DELETE /{db}/_design/{ddoc}/{attname}" ]

=item $obj-E<gt>B<attExists>($name, %options)

 [CouchDB API "HEAD /{db}/_design/{ddoc}/{attname}"]

=item $obj-E<gt>B<attInfo>($name)

Inherited, see L<Couch::DB::Document/"Attachments">

=item $obj-E<gt>B<attLoad>($name, %options)

 [CouchDB API "GET /{db}/_design/{ddoc}/{attname}" ]

=item $obj-E<gt>B<attSave>($name, $data, %options)

 [CouchDB API "PUT /{db}/_design/{ddoc}/{attname}" ]

 -Option--Defined in         --Default
  type    Couch::DB::Document  application/octet-stream

=over 2

=item type => IANA-MediaType

=back

=item $obj-E<gt>B<attachment>($name)

Inherited, see L<Couch::DB::Document/"Attachments">

=item $obj-E<gt>B<attachments>()

Inherited, see L<Couch::DB::Document/"Attachments">

=back

=head2 Indexes (indices)

=over 4

=item $obj-E<gt>B<createIndex>(\%config, %options)

 [CouchDB API "POST /{db}/_index", UNTESTED]

Create an index on the database.  If the name already exists and the
configuration is different, then the index be get regenerated.

=item $obj-E<gt>B<deleteIndex>($index, %options)

 [CouchDB API "DELETE /{db}/_index/{designdoc}/json/{name}", UNTESTED]

Remove an index from this design document.

=item $obj-E<gt>B<indexDetails>($index, %options)

 [CouchDB API "GET /{db}/_design/{ddoc}/_search_info/{index}", UNTESTED]

Returns metadata for the specified search index.

=item $obj-E<gt>B<search>( $index, [\%search, %options] )

 [CouchDB API "GET /{db}/_design/{ddoc}/_search/{index}", UNTESTED]

Executes a (text) search request against the named $index.  The default
C<%search> contains the whole index.  When the search contains
C<include_docs>, then full docs are made available.

(Of course) this command supports paging.

example: return full index all as rows

 my $d    = $db->design('d');
 my $rows = $d->search('i', {}, all => 1)->page;

 my $search = +{ include_docs => 1 };
 my @docs = $d->search('i', \%search, all => 1)->pageDocs;

=back

=head2 Views

=over 4

=item $obj-E<gt>B<viewDocs>( $view, [\%search|\@%search], %options] )

 [CouchDB API "GET /{db}/_design/{ddoc}/_view/{view}", UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_view/{view}", UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_view/{view}/queries", UNTESTED]
 [CouchDB API "GET /{db}/_partition/{partition}/_design/{ddoc}/_view/{view}", UNTESTED]

Executes the specified view function.

This work is handled in L<Couch::DB::Database::allDocs()|Couch::DB::Database/"Handling documents">.  See that method for
C<%options> and results.

example: 

  my %search;
  my $c = $db->design('people')->viewDocs(customers => \%search, all => 1);
  my $hits = $c->page;

  my %search = (design => 'people', view => 'customers');
  my $c = $db->allDocs(\%search, all => 1);

=back

=head2 Functions

=over 4

=item $obj-E<gt>B<applyUpdate>( $function, [$doc|$docid|undef, %options] )

 [CouchDB API "POST /{db}/_design/{ddoc}/_update/{func}", UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_update/{func}/{docid}", UNTESTED]

See what the update function would change.  The update C<$function> is run
on a document, specified by id or object.  By default or explicit undef,
a C<null> (missing) document will be used.

=item $obj-E<gt>B<list>($function, $view, %options)

 [CouchDB API "GET /{db}/_design/{ddoc}/_list/{func}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_list/{func}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
 [CouchDB API "GET /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}", deprecated 3.0, removed 4.0, UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_list/{func}/{other-ddoc}/{view}", deprecated 3.0, removed 4.0, UNTESTED]

Executes a list function against the C<$view>.

 -Option   --Default
  view_ddoc  undef

=over 2

=item view_ddoc => $ddoc|$ddocid

When the C<$view> resides in a different design.

=back

=item $obj-E<gt>B<show>( $function, [$doc|$docid|undef, %options] )

 [CouchDB API "GET /{db}/_design/{ddoc}/_show/{func}", deprecated 3.0, removed 4.0, UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_show/{func}", deprecated 3.0, removed 4.0, UNTESTED]
 [CouchDB API "GET /{db}/_design/{ddoc}/_show/{func}/{docid}", deprecated 3.0, removed 4.0, UNTESTED]
 [CouchDB API "POST /{db}/_design/{ddoc}/_show/{func}/{docid}", deprecated 3.0, removed 4.0, UNTESTED]

Apply show C<$function> on the document, as specified by C<$docid> or document object.  By
default or explicit C<undef>, a "null" document will be used.

=back

=head1 SEE ALSO

This module is part of Couch-DB distribution version 0.200,
built on June 18, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

Copyrights 2024-2025 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>

