====== BigObject PolyDB::Client ======
//from application [[..:common|common]]//\\
\\
 A live connection to a PolyDB server. This is a starting point for all operations on the database.

===== Methods =====

==== Database Access ====
 Core methods for connecting to the database and retrieving metadata.
----
{{anchor:change_password:}}
  ?  **''change_password''**
  ::


----
{{anchor:get_collection:}}
  ?  **''get_collection([[..:common#String |String]] name)''**
  :: Get an object representing a PolyDB collection. See [[http://polydb.org|here]] or ''[[..:common:PolyDB_Client#info |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.
    ? Parameters:
    :: ''[[..:common#String |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.
    ? Returns:
    :''[[..:common:PolyDB_Collection |PolyDB::Collection]]''
    ? Example:
    :: Get a collection specified by a full name
    :: <code perl> > $coll_smooth = $polyDB->get_collection("Polytope.Lattice.SmoothReflexive");
</code>
    ::  Get a collection specified by a short name, as long as it's unambiguous
    :: <code perl> > $coll_fano = $polyDB->get_collection("Fano");
</code>


----
{{anchor:info:}}
  ?  **''info()''**
  :: Print information about available databases and collections.
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''section'': name of the database, default: all available databases
    :: ''[[..:common#String |String]]'' ''collection'': name of the collection, default: all available collections
    :: ''[[..:common#Int |Int]]'' ''info_level'': 0: only names,                         1: short description (default if no collection is given),                        2: description,                         3: description, authors, maintainers,                         4: full info
    :: ''[[..:common#Bool |Bool]]'' ''colored''


----
{{anchor:list_collections:}}
  ?  **''list_collections([[..:common#String |String]] section)''**
  :: Get a list of all collection names
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''section'': only return names of collections from the given section
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''filter'': regular expression for more complex filtering of collection names  Think of correct escaping of special characters: \\. for a literal dot, \\w for a name character.


----
{{anchor:list_sections:}}
  ?  **''list_sections([[..:common#String |String]] section)''**
  :: Get a list of section names
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''section'': return names of sub-sections of the given section;   by default, names of top-level sections are returned
    ? Options:
    : 
    :: ''[[..:common#Bool |Bool]]'' ''recursive'': return names of sub-sections  on all levels
    :: ''[[..:common#String |String]]'' ''filter'': regular expression for more complex filtering of section names  Think of correct escaping of special characters: \\. for a literal dot, \\w for a name character.


----

==== Database Administration ====
 Methods to manipulate the database sections or users.
----
{{anchor:add_user_to_collection:}}
  ?  **''add_user_to_collection()''**
  :: add a user to a collection
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''user'': the username
    :: ''[[..:common#String |String]]'' ''collection'': the collection
    :: ''[[..:common#Bool |Bool]]'' ''admin'': whether the user should get write access, default false


----
{{anchor:create_database_admin:}}
  ?  **''create_database_admin()''**
  :: create a database administrator
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''user'': the username
    :: ''[[..:common#String |String]]'' ''password'': the password


----
{{anchor:create_user:}}
  ?  **''create_user()''**
  :: create a new user
    ? Options:
    : option list ''[[..:common#create_user_options |create_user_options]]''


----
{{anchor:delete_user:}}
  ?  **''delete_user([[..:common#String |String]] user)''**
  :: delete a user
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''user'': the username


----
{{anchor:get_users:}}
  ?  **''get_users(ARRAY usernames)''**
  :: get all users
    ? Parameters:
    :: ''ARRAY'' ''usernames'': list of usernames return HASH


----
{{anchor:initiate_collection:}}
  ?  **''initiate_collection()''**
  :: Starts a new collection by creating the necessary roles  and distributing them to the appropriate users  and adding it to the default polymakeUser role if the  collection is public
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''section'': section
    :: ''[[..:common#String |String]]'' ''collection'': collection
    :: ''[[..:common#Bool |Bool]]'' ''public'': whether the collection can be read by the default polymake user, default true
    :: ''ARRAY'' ''admin_users'': an array of users that can edit the collection
    :: ''ARRAY'' ''users'': an array of users that can read the collection (not necessary if collection is public)


----
{{anchor:remove_collection:}}
  ?  **''remove_collection()''**
  :: Remove a collection toegther with its documentation and the associated rules
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''section'': section
    :: ''[[..:common#String |String]]'' ''collection'': collection
    :: ''[[..:common#Bool |Bool]]'' ''verbose'': default false


----
{{anchor:remove_section:}}
  ?  **''remove_section()''**
  :: Remove a section toegther with its documentation The section must be empty, i.e. no subsections and no collections
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''section'': section
    :: ''[[..:common#Bool |Bool]]'' ''verbose'': default true 


----
{{anchor:remove_user_from_collection:}}
  ?  **''remove_user_from_collection()''**
  :: remove a user to a collection note: access to public collections is not removed by this
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''user'': the username
    :: ''[[..:common#String |String]]'' ''collection'': the collection


----
{{anchor:set_section_doc:}}
  ?  **''set_section_doc(HASH doc)''**
  :: Set documentation for a section
    ? Parameters:
    :: ''HASH'' ''doc'': the documentation
    ? Options:
    : option list ''[[..:common#doc_options |doc_options]]''


----