====== 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: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]]''
    ? from extension:
    : [[:external_software|bundled:polydb]]
    ? 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 section, default: all available sections
    :: ''[[..: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''
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{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, may not be used with filter_sections or filter_collections
    :: ''[[..:common#String |String]]'' ''filter_sections'': filter for sections containing given substring, no regular expression, may not be used with filter
    :: ''[[..:common#String |String]]'' ''filter_collections'': filter for collections containing given substring, no regular expression, may not be used with filter
    :: ''[[..:common#String |String]]'' ''section'': only list collections below section
    :: ''[[..:common#Bool |Bool]]'' ''recursive'': recursively list all collections   Think of correct escaping of special characters: \\. for a literal dot, \\w for a name character.
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{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, may not be used with filter_sections 
    :: ''[[..:common#String |String]]'' ''filter_sections'': filter for sections containing given substring, no regular expression, may not be used with filter
    :: ''[[..:common#String |String]]'' ''section'': only list sections below section
    :: ''[[..:common#Bool |Bool]]'' ''recursive'': recursively list all collections in subsections  Think of correct escaping of special characters: \\. for a literal dot, \\w for a name character.
    ? from extension:
    : [[:external_software|bundled:polydb]]


----

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


----
{{anchor:change_password:}}
  ?  **''change_password([[..:common#String |String]] password)''**
  :: change own password
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''password'': the new password
    ? Returns:
    :''[[..:common#Bool |Bool]]''
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:collection_exists:}}
  ?  **''collection_exists([[..:common#String |String]] collection)''**
  :: checks if a collection with the given name exists in the database this tests for the corresponding roles,  as the collection is only defined in the database if at least one object is inserted
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''collection'': the name of the collection
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:create_user:}}
  ?  **''create_user([[..:common#String |String]] user, [[..:common#String |String]] password)''**
  :: add a user to the database
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''user'': the username
    :: ''[[..:common#String |String]]'' ''password'': the password
    ? Options:
    : 
    :: ''[[..:common#Bool |Bool]]'' ''public_read_access'': whether the new user should have access to all public collections, default true
    :: ''[[..:common#Bool |Bool]]'' ''canChangeOwnAccount'': whether the user can change his/her password and custom data 
    :: ''[[..:common#Array |Array]]<[[..:common#String |String]]>'' ''collections'': a list of collections the user should have read access to
    :: ''[[..:common#Array |Array]]<[[..:common#String |String]]>'' ''admin_collections'': a list of collections the user should have read and write access to
    : option list ''[[..:common#create_user_options |create_user_options]]''
    ? Returns:
    :''[[..:common#Bool |Bool]]''
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:get_user_names:}}
  ?  **''get_user_names''**
  :: get a list of all user names return ARRAY the user names
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:get_users:}}
  ?  **''get_users(ARRAY usernames)''**
  :: get all users
    ? Parameters:
    :: ''ARRAY'' ''usernames'': list of usernames return HASH
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:make_user_database_admin:}}
  ?  **''make_user_database_admin()''**
  :: create a database administrator
    ? Options:
    : 
    :: ''[[..:common#String |String]]'' ''user'': the username
    ? Returns:
    :''[[..:common#Bool |Bool]]''
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:new_collection:}}
  ?  **''new_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]]'' ''collection'': fully qualified collection name
    :: ''[[..:common#Bool |Bool]]'' ''public'': whether the collection can be read by the default polymake user, default true
    :: ''ARRAY'' ''users'': an array of users that can read the collection (not necessary if collection is public)
    :: ''ARRAY'' ''admin_users'': an array of users that can edit the collection
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{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
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{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 
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:remove_user:}}
  ?  **''remove_user([[..:common#String |String]] user)''**
  :: remove a user from the database
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''user'': the username
    ? Returns:
    :''[[..:common#Bool |Bool]]''
    ? from extension:
    : [[:external_software|bundled:polydb]]


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


----
{{anchor:section_exists:}}
  ?  **''section_exists([[..:common#String |String]] section)''**
  :: checks if a section with the given name exists in the database this tests whether there is dicumentation for the section inserted into the database
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''section'': the name of the section
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:set_section_doc:}}
  ?  **''set_section_doc([[..:common#String |String]] section, HASH doc)''**
  :: Set documentation for a section
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''section'': the section
    :: ''HASH'' ''doc'': the documentation
    ? Options:
    : 
    :: ''[[..:common#Bool |Bool]]'' ''update'': default false
    ? from extension:
    : [[:external_software|bundled:polydb]]


----
{{anchor:user_exists:}}
  ?  **''user_exists([[..:common#String |String]] username)''**
  :: checks whether a user is already defined
    ? Parameters:
    :: ''[[..:common#String |String]]'' ''username'': return Bool true on success
    ? from extension:
    : [[:external_software|bundled:polydb]]


----

==== no category ====
{{anchor:get_client_id:}}
  ?  **''get_client_id''**
  ::UNDOCUMENTED
    ? from extension:
    : [[:external_software|bundled:polydb]]


----