Difference between revisions of "API:EPrints/DataObj"

From EPrints Documentation
Jump to: navigation, search
Line 8: Line 8:
 
'''EPrints::DataObj''' - Base class for records in EPrints.
 
'''EPrints::DataObj''' - Base class for records in EPrints.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_synopsis -->
 
<!-- Pod2Wiki=head_synopsis -->
 
==SYNOPSIS==
 
==SYNOPSIS==
Line 49: Line 46:
 
$dataobj = $dataobj-&gt;create_subobject( $fieldname, $epdata );
 
$dataobj = $dataobj-&gt;create_subobject( $fieldname, $epdata );
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
 
 
<!-- Pod2Wiki=head_description -->
 
<!-- Pod2Wiki=head_description -->
 
==DESCRIPTION==
 
==DESCRIPTION==
Line 62: Line 56:
 
It is ABSTRACT - its methods should not be called directly.
 
It is ABSTRACT - its methods should not be called directly.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
* $success = $dataobj-&gt;delete
<!-- Pod2Wiki=item_delete -->
+
: Delete this data object from the database and any sub-objects or related files.
===$success = $dataobj-&gt;delete===
 
  
Delete this data object from the database and any sub-objects or related files.  
+
: Return true if successful.
  
Return true if successful.
+
* $dataobj-&gt;empty()
 +
: Remove all of this object's values that may be imported.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* $dataobj-&gt;update( $epdata [, %opts ] )
<span style='display:none'>User Comments</span>
+
: Update this object's values from $epdata. Ignores any values that do not exist in the dataset or do not have the 'import' property set.
<!-- Edit below this comment -->
 
  
 +
<pre>  include_subdataobjs - replace sub-dataobjs if given
 +
 
 +
  # replaces all documents in $dataobj
 +
  $dataobj->update( {
 +
    title => "Wombats on Fire",
 +
    documents => [{
 +
      main => "wombat.pdf",
 +
      ...
 +
    }],
 +
  }, include_subdataobjs => 1 );</pre>
  
<!-- Pod2Wiki= -->
+
* $success = $dataobj-&gt;commit( [$force] )
</div>
+
: Write this object to the database and reset the changed fields.
<!-- Pod2Wiki=item_empty -->
 
===$dataobj-&gt;empty()===
 
  
Remove all of this object's values that may be imported.
+
: If $force isn't true then it only actually modifies the database if one or more fields have been changed.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: Commit may also queue indexer jobs or log changes, depending on the object.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
* $value = $dataobj-&gt;value( $fieldname )
 +
: Get a the value of a metadata field. If the field is not set then it returns undef unless the field has the property multiple set, in which case it returns  [] (a reference to an empty array).
  
<!-- Pod2Wiki= -->
+
* $dataobj-&gt;set_value( $fieldname, $value )
</div>
+
: Set the value of the named metadata field in this record.
<!-- Pod2Wiki=item_commit -->
 
===$success = $dataobj-&gt;commit( [$force] )===
 
  
Write this object to the database and reset the changed fields.
+
* @values = $dataobj-&gt;get_values( $fieldnames )
 +
: Returns a list of all the values in this record of all the fields specified by $fieldnames. $fieldnames should be in the format used by browse views - slash seperated fieldnames with an optional .id suffix to indicate the id part rather than the main part.  
  
If $force isn't true then it only actually modifies the database if one or more fields have been changed.
+
: For example "author.id/editor.id" would return a list of all author and editor ids from this record.
  
Commit may also queue indexer jobs or log changes, depending on the object.
+
* $bool = $dataobj-&gt;is_set( $fieldname )
 +
: Returns true if the named field is set in this record, otherwise false.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: Warns if the field does not exist.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
* $bool = $dataobj-&gt;exists_and_set( $fieldname )
 +
: Returns true if the named field is set in this record, otherwise false.
  
<!-- Pod2Wiki= -->
+
: If the field does not exist, just return false.
</div>
 
<!-- Pod2Wiki=item_value -->
 
===$value = $dataobj-&gt;value( $fieldname )===
 
  
Get a the value of a metadata field. If the field is not set then it returns undef unless the field has the property multiple set, in which case it returns  [] (a reference to an empty array).
+
: This method is useful for plugins which may operate on multiple  repositories, and the fact a field does not exist is not an issue.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* $id = $dataobj-&gt;id
<span style='display:none'>User Comments</span>
+
: Returns the value of the primary key of this record.
<!-- Edit below this comment -->
 
  
 +
* $uuid = $dataobj-&gt;uuid( [ $fragment ] )
 +
: Generates a version 5 UUID for this object e.g.
  
<!-- Pod2Wiki= -->
+
<pre>  f70ef731-be66-50f4-8e72-8b8de36778b5</pre>
</div>
 
<!-- Pod2Wiki=item_set_value -->
 
===$dataobj-&gt;set_value( $fieldname, $value )===
 
  
Set the value of the named metadata field in this record.
+
: The UUID is generated from the SHA1 hash of the concantenation of <code>uuid_namespace</code>, the {{API:PodLink|file=|package_name=|section=internal_uri|text=object's uri}} and, if defined, '''$fragment'''.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: <code>uuid_namespace</code> is a configuration variable. If <code>uuid_namespace</code> is undefined uses <code>base_url</code>:
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
<pre>  # Note: deliberate typo to prevent copy-and-paste
 +
  $c-&gt;{uuid_namespace} = "http://your-repository's url"";</pre>
  
<!-- Pod2Wiki= -->
+
: Returns the formatted UUID.
</div>
 
<!-- Pod2Wiki=item_get_values -->
 
===@values = $dataobj-&gt;get_values( $fieldnames )===
 
  
Returns a list of all the values in this record of all the fields specified by $fieldnames. $fieldnames should be in the format used by browse views - slash seperated fieldnames with an optional .id suffix to indicate the id part rather than the main part.  
+
* $xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )
 +
: Returns the rendered version of the value of the given field, as appropriate for the current session. If $showall is true then all values are rendered -  this is usually used for staff viewing data.
  
For example "author.id/editor.id" would return a list of all author and editor ids from this record.
+
* $xhtml = $dataobj-&gt;render_citation( [$style], [%params] )
 +
: Renders the record as a citation. If $style is set then it uses that citation style from the citations config file. Otherwise $style defaults to the type of this record. If $params{url} is set then the citiation will link to the specified URL.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
* $xhtml = $dataobj-&gt;render_citation_link( [$style], %params )
<span style='display:none'>User Comments</span>
+
: Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of an eprint.
<!-- Edit below this comment -->
 
  
 +
* $xhtml = $dataobj-&gt;render_export_bar( [ $staff ] )
 +
: Render a drop-down list of exports.
  
<!-- Pod2Wiki= -->
+
* $url = $dataobj-&gt;uri
</div>
+
: Returns a unique URI for this object. Not certain to resolve as a  URL.
<!-- Pod2Wiki=item_is_set -->
 
===$bool = $dataobj-&gt;is_set( $fieldname )===
 
  
Returns true if the named field is set in this record, otherwise false.
+
: If $c-&gt;{dataobj_uri}-&gt;{eprint} is a function, call that to work it out.
  
Warns if the field does not exist.
+
* $path = $dataobj-&gt;path
 +
: Returns the relative path to this object from the repository's base URL, if the object has a URL.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
: Does not include any leading slash.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
* $url = $dataobj-&gt;url
 +
: Returns the URL for this record, for example the URL of the abstract page of an eprint.
  
<!-- Pod2Wiki= -->
+
* $plugin_output = $dataobj-&gt;export( $plugin_id, %params )
</div>
+
: Apply an output plugin to this items. Return the results.
<!-- Pod2Wiki=item_exists_and_set -->
 
===$bool = $dataobj-&gt;exists_and_set( $fieldname )===
 
  
Returns true if the named field is set in this record, otherwise false.
+
* $rc = $dataobj-&gt;permit( $priv [, $user ] )
 +
<pre>  # current user can edit via editorial role
 +
  if( $dataobj-&gt;permit( "xxx/edit", $user ) &amp; 8 )
 +
  {
 +
    ...
 +
  }
 +
  # anyone can view this object
 +
  if( $dataobj-&gt;permit( "xxx/view" ) )
 +
  {
 +
  }</pre>
  
If the field does not exist, just return false.
+
: Returns true if the current user (or 'anybody') can perform this action.
  
This method is useful for plugins which may operate on multiple  repositories, and the fact a field does not exist is not an issue.
+
: Returns a bit mask where:
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
<pre>  0 - not permitted
<span style='display:none'>User Comments</span>
+
  1 - anybody
<!-- Edit below this comment -->
+
  2 - logged in user
 +
  4 - user as owner
 +
  8 - user as editor</pre>
  
 +
: See also [[API:EPrints/Repository#allow_anybody|EPrints::Repository/allow_anybody]] and [[API:EPrints/DataObj/User#allow|EPrints::DataObj::User/allow]].
  
<!-- Pod2Wiki= -->
+
* $list = $dataobj-&gt;duplicates()
</div>
+
: Return a conservative list of other objects that look like this one.
<!-- Pod2Wiki=item_id -->
 
===$id = $dataobj-&gt;id===
 
  
Returns the value of the primary key of this record.
+
<!-- Pod2Wiki=head_copyright -->
 +
==COPYRIGHT==
 +
Copyright 2000-2011 University of Southampton.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
+
This file is part of EPrints http://www.eprints.org/.
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
  
 +
EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
  
<!-- Pod2Wiki= -->
+
EPrints 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 Lesser General Public License for more details.
</div>
 
<!-- Pod2Wiki=item_render_value -->
 
===$xhtml = $dataobj-&gt;render_value( $fieldname, [$showall] )===
 
  
Returns the rendered version of the value of the given field, as appropriate for the current session. If $showall is true then all values are rendered -  this is usually used for staff viewing data.
+
You should have received a copy of the GNU Lesser General Public License along with EPrints.  If not, see http://www.gnu.org/licenses/.
  
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
  
  
 
<!-- Pod2Wiki= -->
 
<!-- Pod2Wiki= -->
</div>
+
<!-- Pod2Wiki=_postamble_ -->
<!-- Pod2Wiki=item_render_citation -->
 
===$xhtml = $dataobj-&gt;render_citation( [$style], [%params] )===
 
 
 
Renders the record as a citation. If $style is set then it uses that citation style from the citations config file. Otherwise $style defaults to the type of this record. If $params{url} is set then the citiation will link to the specified URL.
 
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
 
<!-- Edit below this comment -->
 
<!-- Edit below this comment -->
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_render_citation_link -->
 
===$xhtml = $dataobj-&gt;render_citation_link( [$style], %params )===
 
 
Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of an eprint.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_render_export_bar -->
 
===$xhtml = $dataobj-&gt;render_export_bar( [ $staff ] )===
 
 
Render a drop-down list of exports.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_uri -->
 
===$url = $dataobj-&gt;uri===
 
 
Returns a unique URI for this object. Not certain to resolve as a  URL.
 
 
If $c-&gt;{dataobj_uri}-&gt;{eprint} is a function, call that to work it out.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_path -->
 
===$path = $dataobj-&gt;path===
 
 
Returns the relative path to this object from the repository's base URL, if the object has a URL.
 
 
Does not include any leading slash.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_url -->
 
===$url = $dataobj-&gt;url===
 
 
Returns the URL for this record, for example the URL of the abstract page of an eprint.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=item_export -->
 
===$plugin_output = $dataobj-&gt;export( $plugin_id, %params )===
 
 
Apply an output plugin to this items. Return the results.
 
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=head_copyright -->
 
==COPYRIGHT==
 
<div style='background-color: #e8e8f; margin: 0.5em 0em 1em 0em; border: solid 1px #cce;  padding: 0em 1em 0em 1em; font-size: 80%; '>
 
<span style='display:none'>User Comments</span>
 
<!-- Edit below this comment -->
 
 
 
<!-- Pod2Wiki= -->
 
</div>
 
<!-- Pod2Wiki=_postamble_ --><!-- Edit below this comment -->
 

Revision as of 09:56, 22 January 2013

EPrints 3 Reference: Directory Structure - Metadata Fields - Repository Configuration - XML Config Files - XML Export Format - EPrints data structure - Core API - Data Objects


API: Core API

Latest Source Code (3.4, 3.3) | Revision Log | Before editing this page please read Pod2Wiki


NAME

EPrints::DataObj - Base class for records in EPrints.


SYNOPSIS

$dataobj = $dataset->dataobj( $id );

$dataobj->delete;

$dataobj->commit( $force );

$dataset = $dataobj->dataset;

$repo = $dataobj->repository;

$id = $dataobj->id;

$dataobj->set_value( $fieldname, $value );

$value = $dataobj->value( $fieldname );

\@value = $dataobj->value( $fieldname ); # multiple

$boolean = $dataobj->is_set( $fieldname );

$xhtml = $dataobj->render_value( $fieldname );

$xhtml = $dataobj->render_citation( $style, %opts );

$uri = $dataobj->uri;

$url = $dataobj->url;

$string = $dataobj->export( $plugin_id, %opts );

$dataobj = $dataobj->create_subobject( $fieldname, $epdata );


DESCRIPTION

This module is a base class which is inherited by EPrints::DataObj::EPrint, EPrints::DataObj::User, EPrints::DataObj::Subject and EPrints::DataObj::Document and several other classes.

It is ABSTRACT - its methods should not be called directly.


  • $success = $dataobj->delete
Delete this data object from the database and any sub-objects or related files.
Return true if successful.
  • $dataobj->empty()
Remove all of this object's values that may be imported.
  • $dataobj->update( $epdata [, %opts ] )
Update this object's values from $epdata. Ignores any values that do not exist in the dataset or do not have the 'import' property set.
  include_subdataobjs - replace sub-dataobjs if given
  
  # replaces all documents in $dataobj
  $dataobj->update( {
    title => "Wombats on Fire",
    documents => [{
      main => "wombat.pdf",
      ...
    }],
  }, include_subdataobjs => 1 );
  • $success = $dataobj->commit( [$force] )
Write this object to the database and reset the changed fields.
If $force isn't true then it only actually modifies the database if one or more fields have been changed.
Commit may also queue indexer jobs or log changes, depending on the object.
  • $value = $dataobj->value( $fieldname )
Get a the value of a metadata field. If the field is not set then it returns undef unless the field has the property multiple set, in which case it returns [] (a reference to an empty array).
  • $dataobj->set_value( $fieldname, $value )
Set the value of the named metadata field in this record.
  • @values = $dataobj->get_values( $fieldnames )
Returns a list of all the values in this record of all the fields specified by $fieldnames. $fieldnames should be in the format used by browse views - slash seperated fieldnames with an optional .id suffix to indicate the id part rather than the main part.
For example "author.id/editor.id" would return a list of all author and editor ids from this record.
  • $bool = $dataobj->is_set( $fieldname )
Returns true if the named field is set in this record, otherwise false.
Warns if the field does not exist.
  • $bool = $dataobj->exists_and_set( $fieldname )
Returns true if the named field is set in this record, otherwise false.
If the field does not exist, just return false.
This method is useful for plugins which may operate on multiple repositories, and the fact a field does not exist is not an issue.
  • $id = $dataobj->id
Returns the value of the primary key of this record.
  • $uuid = $dataobj->uuid( [ $fragment ] )
Generates a version 5 UUID for this object e.g.
  f70ef731-be66-50f4-8e72-8b8de36778b5
The UUID is generated from the SHA1 hash of the concantenation of uuid_namespace, the object's uri and, if defined, $fragment.
uuid_namespace is a configuration variable. If uuid_namespace is undefined uses base_url:
  # Note: deliberate typo to prevent copy-and-paste
  $c->{uuid_namespace} = "http://your-repository's url"";
Returns the formatted UUID.
  • $xhtml = $dataobj->render_value( $fieldname, [$showall] )
Returns the rendered version of the value of the given field, as appropriate for the current session. If $showall is true then all values are rendered - this is usually used for staff viewing data.
  • $xhtml = $dataobj->render_citation( [$style], [%params] )
Renders the record as a citation. If $style is set then it uses that citation style from the citations config file. Otherwise $style defaults to the type of this record. If $params{url} is set then the citiation will link to the specified URL.
  • $xhtml = $dataobj->render_citation_link( [$style], %params )
Renders a citation (as above) but as a link to the URL for this item. For example - the abstract page of an eprint.
  • $xhtml = $dataobj->render_export_bar( [ $staff ] )
Render a drop-down list of exports.
  • $url = $dataobj->uri
Returns a unique URI for this object. Not certain to resolve as a URL.
If $c->{dataobj_uri}->{eprint} is a function, call that to work it out.
  • $path = $dataobj->path
Returns the relative path to this object from the repository's base URL, if the object has a URL.
Does not include any leading slash.
  • $url = $dataobj->url
Returns the URL for this record, for example the URL of the abstract page of an eprint.
  • $plugin_output = $dataobj->export( $plugin_id, %params )
Apply an output plugin to this items. Return the results.
  • $rc = $dataobj->permit( $priv [, $user ] )
  # current user can edit via editorial role
  if( $dataobj->permit( "xxx/edit", $user ) & 8 )
  {
    ...
  }
  # anyone can view this object
  if( $dataobj->permit( "xxx/view" ) )
  {
  }
Returns true if the current user (or 'anybody') can perform this action.
Returns a bit mask where:
  0 - not permitted
  1 - anybody
  2 - logged in user
  4 - user as owner
  8 - user as editor
See also EPrints::Repository/allow_anybody and EPrints::DataObj::User/allow.
  • $list = $dataobj->duplicates()
Return a conservative list of other objects that look like this one.

COPYRIGHT

Copyright 2000-2011 University of Southampton.

This file is part of EPrints http://www.eprints.org/.

EPrints is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

EPrints 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 Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with EPrints. If not, see http://www.gnu.org/licenses/.