—

              
use 5.008001;
use strict;
use warnings;
package BSON::DBRef;
# ABSTRACT: BSON type wrapper for MongoDB DBRefs
use version;
our $VERSION = 'v0.999.3'; # TRIAL
use Tie::IxHash;
use Moo;
use namespace::clean -except => 'meta';
#pod =attr id
#pod
#pod Required. The C<_id> value of the referenced document. If the
#pod C<_id> is an ObjectID, then you must use a L<BSON::OID> object.
#pod
#pod =cut
# no type constraint since an _id can be anything
has id => (
    is        => 'ro',
    required  => 1
);
#pod =attr ref
#pod
#pod Required. The name of the collection in which the referenced document
#pod lives.  Either a L<MongoDB::Collection> object or a string containing the
#pod collection name. The object will be coerced to string form.
#pod
#pod This may also be specified in the constructor as C<'$ref'>.
#pod
#pod =cut
has _ref => (
    is        => 'ro',
    required  => 1,
    init_arg  => 'ref',
    coerce    => sub { CORE::ref($_[0]) eq 'MongoDB::Collection' ? $_[0]->name : $_[0] },
    isa       => sub { die "must be a non-empty string" unless defined($_[0]) && length($_[0]) },
);
#pod =attr db
#pod
#pod Optional. The database in which the referenced document lives. Either a
#pod L<MongoDB::Database> object or a string containing the database name. The
#pod object will be coerced to string form.
#pod
#pod Not all other language drivers support the C<$db> field, so using this
#pod field is not recommended.
#pod
#pod This may also be specified in the constructor as C<'$db'>.
#pod
#pod =cut
has db => (
    is        => 'ro',
    coerce    => sub { CORE::ref($_[0]) eq 'MongoDB::DataBase' ? $_[0]->name : $_[0] },
    isa       => sub { return if ! defined($_[0]); die "must be a non-empty string" unless length($_[0]) },
);
#pod =attr extra
#pod
#pod Optional.  A hash reference of additional fields in the DBRef document.
#pod Not all MongoDB drivers support this feature and you B<should not> rely on
#pod it.  This attribute exists solely to ensure DBRefs generated by drivers that
#pod do allow extra fields will round-trip correctly.
#pod
#pod B<USE OF THIS FIELD FOR NEW DBREFS IS NOT RECOMMENDED.>
#pod
#pod =cut
has extra => (
    is => 'ro',
    isa => sub { return if ! defined($_[0]); die "must be a hashref" unless eval { scalar %{$_[0]}; 1 } },
    default => sub { {} },
);
around BUILDARGS => sub {
    my $orig  = shift;
    my $class = shift;
    my $hr    = $class->$orig(@_);
    return {
        id => (
              exists( $hr->{'$id'} ) ? delete $hr->{'$id'}
            : exists( $hr->{id} )    ? delete $hr->{id}
            :                          undef
        ),
        'ref' => (
              exists( $hr->{'$ref'} ) ? delete $hr->{'$ref'}
            : exists( $hr->{'ref'})    ? delete $hr->{'ref'}
            :                           undef
        ),
        db => (
              exists( $hr->{'$db'} ) ? delete $hr->{'$db'}
            : exists( $hr->{db} )    ? delete $hr->{db}
            :                          undef
        ),
        extra => $hr,
    };
};
sub _ordered {
    my $self = shift;
    return Tie::IxHash->new(
        '$ref' => $self->ref,
        '$id'  => $self->id,
        ( defined($self->db) ? ( '$db' => $self->db ) : () ),
        %{ $self->extra },
    );
}
#pod =method TO_JSON
#pod
#pod If the C<BSON_EXTJSON> option is true, returns a hashref compatible with
#pod MongoDB's L<extended JSON|https://docs.mongodb.org/manual/reference/mongodb-extended-json/>
#pod format, which represents it as a document as follows:
#pod
#pod     { "$ref": "<collection name>", "$id": "<id>" }
#pod
#pod If the C<BSON_EXTJSON> option is false, an error is thrown, as this value
#pod can't otherwise be represented in JSON.
#pod
#pod =cut
sub TO_JSON {
    my $self = shift;
    if ( $ENV{BSON_EXTJSON} ) {
        return {
            '$ref' => $self->ref,
            '$id'  => $self->id,
            ( defined($self->db) ? ( '$db' => $self->db ) : () ),
            %{ $self->extra },
        };
    }
    Carp::croak( "The value '$self' is illegal in JSON" );
}
# Normally, Moo defers installation of the 'new' subroutine until first
# use.  We need force that to happen immediately to allow the compiler
# to correctly differentiate between 'ref' there and our accessor 'ref',
# aliased later.
__PACKAGE__->new(ref => "a", id => "0");
# Alias 'ref' to attribute '_ref' now that all other compilation is
# complete.
{
    no warnings 'once';
    *ref = \&_ref;
}
1;
HideShow 107 lines of Pod
=pod
=encoding UTF-8
=head1 NAME
BSON::DBRef - BSON type wrapper for MongoDB DBRefs
=head1 VERSION
version v0.999.3
=head1 SYNOPSIS
    use BSON::Types ':all';
    my $dbref = bson_dbref( $oid, $collection_name );
=head1 DESCRIPTION
This module provides a BSON type wrapper for L<MongoDB Database
References|http://docs.mongodb.org/manual/reference/database-references/>.
A DBRef is a special document format which references another document in
the database.  DBRefs are not the same as foreign keys and do not provide
any referential integrity or constraint checking. For example, a DBRef may
point to a document that no longer exists (or never existed.)
Use of DBRefs is discouraged, so this module is provided for backwards
compatibility.  L<"Manual
references"|https://docs.mongodb.com/manual/reference/database-references/#document-references>
are preferred when there is a need to reference other documents.
=head1 ATTRIBUTES
=head2 id
Required. The C<_id> value of the referenced document. If the
C<_id> is an ObjectID, then you must use a L<BSON::OID> object.
=head2 ref
Required. The name of the collection in which the referenced document
lives.  Either a L<MongoDB::Collection> object or a string containing the
collection name. The object will be coerced to string form.
This may also be specified in the constructor as C<'$ref'>.
=head2 db
Optional. The database in which the referenced document lives. Either a
L<MongoDB::Database> object or a string containing the database name. The
object will be coerced to string form.
Not all other language drivers support the C<$db> field, so using this
field is not recommended.
This may also be specified in the constructor as C<'$db'>.
=head2 extra
Optional.  A hash reference of additional fields in the DBRef document.
Not all MongoDB drivers support this feature and you B<should not> rely on
it.  This attribute exists solely to ensure DBRefs generated by drivers that
do allow extra fields will round-trip correctly.
B<USE OF THIS FIELD FOR NEW DBREFS IS NOT RECOMMENDED.>
=head1 METHODS
=head2 TO_JSON
If the C<BSON_EXTJSON> option is true, returns a hashref compatible with
MongoDB's L<extended JSON|https://docs.mongodb.org/manual/reference/mongodb-extended-json/>
format, which represents it as a document as follows:
    { "$ref": "<collection name>", "$id": "<id>" }
If the C<BSON_EXTJSON> option is false, an error is thrown, as this value
can't otherwise be represented in JSON.
=for Pod::Coverage BUILDARGS
=head1 AUTHORS
=over 4
=item *
David Golden <david@mongodb.com>
=item *
Stefan G. <minimalist@lavabit.com>
=back
=head1 COPYRIGHT AND LICENSE
This software is Copyright (c) 2016 by Stefan G. and MongoDB, Inc.
This is free software, licensed under:
  The Apache License, Version 2.0, January 2004
=cut
__END__
# vim: set ts=4 sts=4 sw=4 et tw=75: