software-versions-processor-lib/docs/index.rst

#############################
Software Artifact Processor
#############################

This library has been initially designed to deposit software artifacts programmatically in Zenodo.

It is actually a general-purpose library capable of analyzing a list of 
software artifacts (represented by the metadata) and process them.

The library currently offers two processors:

* **ZenodoExporter**: deposit the software artifact in Zenodo obtaining a DOI;
* **BibLaTeXExporter**: export the software artifact in a ``bib`` file using the BibLaTeX format.

Other processors can be easily added in the future by extending the ``SoftwareArtifactProcessor`` class.

The core class of the library is ``Analyser``, which must be initialized with:

* a configuration (JSON Object);
* a list of software artifacts described by their metadata (JSON Array).

The configuration must contain at least the list of exporters to be used and their configuration parameters. 
Exporter configuration requires at least the ``elaboration`` property, which can assume the following values 
(see ``ElaborationType`` enumerated):

* **ALL**: The exporter analyses all the software artifacts;
* **UPDATE_ONLY**: The exporter analyes only the software artifact to be updated in the target;
* **NEW**: The exporter analyses only the software artifact that does not yet exist in the target;
* **NONE**: Does not export the software artifact in the target, but each software artifact is elaborated for the exporting without effectively doing it. It is a dry run.

The processors are executed in the order they are defined. 
A processor could produce metadata itself (e.g., the obtained Zenodo DOI). 
The input metadata + the metadata generated by a processor are made available to the subsequent processor. 

At the end of the processing phase, the library produces the actualized output of all the software artifact metadata.

Moreover, the configuration can optionally include an arbitrary set of metadata used as default metadata for all software artifacts defined in the list.

The list of software artifacts contains an arbitrary set of metadata. 
It depends on the processor using certain metadata, among others.

While analyzing each software artifact, the ``Analyser`` link it with the previously elaborated software artifact. 
Relating an artifact with the previous one is helpful if a processor needs to link them in some way. 
It is in charge of the processor's logic of connecting them using specific metadata values used as conditions.

The library dynamically calculates the value of metadata of a software artifact using the following features:

* A property can contain the value of another property indicated as a variable using the referred property name;
* The library merges the metadata of the software artifact with the metadata defined in the configuration;
* The library calculates the final metadata values, replacing the variables only after merging the properties.

The following example show an example of configuration

.. literalinclude:: ../src/test/resources/gcat-test-sandbox.json
  :language: JSON


.. 
	The output of the elaboration is the following
  
	.. literalinclude:: ./gcat/gcat.json
  		:language: JSON


The output generated by ``BibLaTeXExporter`` is

.. literalinclude:: ./gcat/gcat.bib
  :language: bib