<refentry id="class-database">
  <refnamediv>
    <refname>Base.DataBase</refname>
    <refpurpose>Represents a bibliographic database</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <programlisting>
class <classname>Base.DataBase</classname>:
    <link linkend="mem-database-key"><varname>self.key</varname></link>
    <link linkend="mem-database-id"><varname>self.id</varname></link>

    def <link linkend="meth-database-init">__init__</link>     (self, url):
    def <link linkend="meth-database-has-property">has_property</link> (self, prop):
    def <link linkend="meth-database-new-entry">new_entry</link>    (self, type):
    def <link linkend="meth-database-add">add</link>          (self, entry):
    def <link linkend="meth-database-keys">keys</link>         (self):
    	    return <returnvalue>list (Keys)</returnvalue>
    def <link linkend="meth-database-has-key">has_key</link>      (self, key):
    	    return <returnvalue>boolean</returnvalue>
    def <link linkend="meth-database-getitem">__getitem__</link>  (self, key):
    def <link linkend="meth-database-setitem">__setitem__</link>  (self, key, value):
    def <link linkend="meth-database-get-native">get_native</link>   (self, key):
    def <link linkend="meth-database-set-native">set_native</link>   (self, value):
    def <link linkend="meth-database-delitem">__delitem__</link>  (self, key):
    def <link linkend="meth-database-len">__len__</link>      (self):
    	    return <returnvalue>integer</returnvalue>
    def <link linkend="meth-database-iterator">iterator</link>     (self):
    	    return <returnvalue>Iterator ()</returnvalue>
    def <link linkend="meth-database-update">update</link>       (self):
</programlisting>
  </refsynopsisdiv>

  <refsect1>
    <title>Usage</title>  

    <para>This class provides access to a full bibliographic database.
    It  basically   behaves  like  a  dictionnary:   given  the  <link
    linkend="class-key">key</link>          of         a         <link
    linkend="class-entry">entry</link>, this  object returns the entry
    itself.</para>
    <warning>
      <para>The  database  does  <emphasis>not</emphasis> ensure  that
      modifying the returned entry  actually modifies the database. It
      does  not  ensure  the  opposite  too. So,  to  commit  changes,
      explicitely set the modified entry in the database. And to avoid
      unexpected modifications, explicitely copy  an entry that has to
      be modified.</para>
    </warning>
    </refsect1>

    <refsect1>
      <title>Members</title>
      <refsect2 id="mem-database-key">
	<title>self.key</title>
	<para>Holds the <link linkend="class-url">URL</link>
	identifying the database.</para>
      </refsect2>

      <refsect2 id="mem-database-id">
	<title>self.id</title>
	<para>Holds the type of the database, as a string.</para>
      </refsect2>
    </refsect1>
    
    <refsect1>
    <title>Methods</title>
    
    <refsect2 id="meth-database-init">
      <title>__init__ (self, url)</title>

      <para>The    database    is    constructed    from    a    <link
      linkend="class-url">URL</link> object. Usually, the invocation of
      the constructor is not done directly by the user but rather through
      a higher level function like bibopen.</para>
      
    </refsect2>

    <refsect2 id="meth-database-has-property">
      <title></title>
      <para></para>
    </refsect2>

    <refsect2 id="meth-database-new-entry">
      <title>new_entry (self, type)</title>

      <para>This method returns a new empty entry which is native for
      the current database. (it is always possible to use a generic
      Base.Entry instead, but the one returned here can avoid internal
      conversions)</para>

    </refsect2>

    <refsect2 id="meth-database-add">
      <title>add (self, entry)</title>

      <para>This method inserts a new entry in the database. If the
      entry has no key yet, a unique key is generated.</para>

    </refsect2>

    <refsect2 id="meth-database-keys">
      <title>keys (self)</title>

      <para>Returns a list of entry keys.</para>
    </refsect2>

    <refsect2 id="meth-database-has-key">
      <title>has_key (self, key)</title>

      <para>Returns true if the database holds the specified key.</para>
    </refsect2>

    <refsect2 id="meth-database-getitem">
      <title>__getitem__ (self, key)</title>
      <programlisting>
entry = database [key]
</programlisting>

      <para>Returns an entry according to its key, like a dictionnary.</para>
    </refsect2>

    <refsect2 id="meth-database-setitem">
      <title>__setitem__ (self, key, entry)</title>
      <programlisting>
database [key] = entry
</programlisting>

      <para>Stores an entry under a given key in a database.</para>
    </refsect2>

    <refsect2 id="meth-database-get-native">
      <title>get_native (self, key)</title>

      <para>Returns a textual representation of the entry in its
      native format</para>
    </refsect2>

    <refsect2 id="meth-database-set-native">
      <title>set_native (self, value)</title>

      <para>Parses an entry in its native format, and stores it in the
      database.</para>
    </refsect2>

    <refsect2 id="meth-database-delitem">
      <title>__delitem__ (self, key)</title>
      <programlisting>
del database [key]
</programlisting>

      <para>Removes the entry corresponding to the key.</para>
    </refsect2>

    <refsect2 id="meth-database-len">
      <title>__len__ (self)</title>
      <programlisting>
l = len (database)
</programlisting>

      <para>Returns the number of entries stored in the database.</para>
    </refsect2>

    <refsect2 id="meth-database-iterator">
      <title>iterator (self)</title>
      <para>Returns an iterator that will loop over all the entries of
      the database. This method should be preferred to an explicit
      loop over database.keys (), as it can eventually access the
      entries in a more efficient manner.</para>
    </refsect2>

    <refsect2 id="meth-database-update">
      <title>update (self)</title>
      <para>Updates the URL content so that it reflects the current database.</para>
    </refsect2>

  </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-namecase-general:t
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:nil
sgml-parent-document:("pyblio.sgml" "reference" "refentry")
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
-->
