#  Copyright (c) 1997-2021
#  Ewgenij Gawrilow, Michael Joswig, and the polymake team
#  Technische Universität Berlin, Germany
#  https://polymake.org
#
#  This program is free software; you can redistribute it and/or modify it
#  under the terms of the GNU General Public License as published by the
#  Free Software Foundation; either version 2, or (at your option) any
#  later version: http://www.gnu.org/licenses/gpl.txt.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#-------------------------------------------------------------------------------
#
#  This file is part of the polymake database interface polyDB.
#
#   @author Silke Horn, Andreas Paffenholz
#   http://www.mathematik.tu-darmstadt.de/~paffenholz
#

require PolyDB::Completion;

# @topic category any/Database Access
# Core methods for connecting to the database and retrieving metadata.

# @topic category any/Database Query Operations
# Methods that provide query operations for the database or
# manipulate the result stream of a query.

# @topic category any/Database Administration
# Methods to manipulate the database sections or users.

# @topic category any/Database Collection Administration
# Methods to manipulate a given collection.



# @topic objects/PolyDB::Client
# @category Database Access
# A live connection to a PolyDB server.
# This is a starting point for all operations on the database.

# @topic objects/PolyDB::Client/methods/get_collection (;$)
# @category Database Access
# Get an object representing a PolyDB collection.
# See [[http://polydb.org|here]] or [[info]] for available sections and collections.
#
# Please be aware that some collections may have restricted access rights.
# The permission is not checked immediately in this function but when real data are accessed first time.
#
# @param [complete PolyDB::Collection] String name collection name
#  If there are several collections with equal names in different sections, the full name including the section name must be given.
#  Custom variable $PolyDB::default::db_section_name can be set to the most frequently used section name, then it will be
#  taken into account for disambiguation.
#  Custom variable $PolyDB::default::db_collection_name can be set as a default value for this parameter.
# @return PolyDB::Collection
#
# @example [notest]
# Get a collection specified by a full name
# > $coll_smooth = $polyDB->get_collection("Polytope.Lattice.SmoothReflexive");
# Get a collection specified by a short name, as long as it's unambiguous
# > $coll_fano = $polyDB->get_collection("Fano");


# @topic objects/PolyDB::Collection
# @category Database Access
# Represents a collection in PolyDB

# @category Database Query Operations
# @topic objects/PolyDB::Collection/methods/aggregate
# Run an aggregation pipeline on the collection.
# See [[https://docs.mongodb.com/manual]] for available operations.
# Return a DB cursor over the resulting documents.  No automatic conversion to big objects is done.


# @topic objects/PolyDB::Cursor
# @category Database Query Operations
# Database cursor over the results of a query operation.
# Objects can be retrieved in a loop, fetching one at a time, or all at once.
# @example [notest]
# Process results of a query in a loop
# > for (my $cursor = $collection->find({}); $cursor->has_next; ) {
# >   my $object = $cursor->next;
# >   do_something($object);
# > }
# Retrieve all objects at once
# > @with_100_vertices = $collection->find({ N_VERTICES => 100 })->all;

# @category Database Query Operations
# @topic objects/PolyDB::Cursor/methods/has_next
# Check whether there are more objects in the result stream
# @return Bool

# @category Database Query Operations
# @topic objects/PolyDB::Cursor/methods/next
# Get the next object from the result stream or //undef// if it's exhausted

# @category Database Query Operations
# @topic objects/PolyDB::Cursor/methods/all
# Get all remaining objects from the result stream

# @category Database Query Operations
# @topic objects/PolyDB::Cursor/methods/reset
# Reset a database cursor to the beginning of the query. Also query limiters like sort can then be applied.


# Local Variables:
# mode: perl
# cperl-indent-level:3
# indent-tabs-mode:nil
# End:
