<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<refentry id="appstream-as-spdx">
<refmeta>
<refentrytitle role="top_of_page" id="appstream-as-spdx.top_of_page">as-spdx</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>APPSTREAM Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>as-spdx</refname>
<refpurpose>Helper functions to work with SPDX license descriptions.</refpurpose>
</refnamediv>

<refsect1 id="appstream-as-spdx.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="as-is-spdx-license-id">as_is_spdx_license_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="as-is-spdx-license-expression">as_is_spdx_license_expression</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
</entry><entry role="function_name"><link linkend="as-spdx-license-tokenize">as_spdx_license_tokenize</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="as-spdx-license-detokenize">as_spdx_license_detokenize</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="as-license-to-spdx-id">as_license_to_spdx_id</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="as-license-is-metadata-license">as_license_is_metadata_license</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="appstream-as-spdx.includes"><title>Includes</title><synopsis>#include &lt;appstream.h&gt;
</synopsis></refsect1>

<refsect1 id="appstream-as-spdx.description" role="desc">
<title role="desc.title">Description</title>

</refsect1>
<refsect1 id="appstream-as-spdx.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="as-is-spdx-license-id" role="function" condition="since:0.9.8">
<title>as_is_spdx_license_id&#160;()</title>
<indexterm zone="as-is-spdx-license-id" role="0.9.8"><primary>as_is_spdx_license_id</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
as_is_spdx_license_id (<parameter>const <link linkend="gchar"><type>gchar</type></link> *license_id</parameter>);</programlisting>
<para>Searches the known list of SPDX license IDs.</para>
<refsect3 id="as-is-spdx-license-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>license_id</para></entry>
<entry role="parameter_description"><para>a single SPDX license ID, e.g. "GPL-3.0"</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="as-is-spdx-license-id.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the icon is a valid "SPDX license ID"</para>
</refsect3><para role="since">Since: <link linkend="api-index-0.9.8">0.9.8</link></para></refsect2>
<refsect2 id="as-is-spdx-license-expression" role="function" condition="since:0.9.8">
<title>as_is_spdx_license_expression&#160;()</title>
<indexterm zone="as-is-spdx-license-expression" role="0.9.8"><primary>as_is_spdx_license_expression</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
as_is_spdx_license_expression (<parameter>const <link linkend="gchar"><type>gchar</type></link> *license</parameter>);</programlisting>
<para>Checks the licence string to check it being a valid licence.
NOTE: SPDX licences can't typically contain brackets.</para>
<refsect3 id="as-is-spdx-license-expression.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>license</para></entry>
<entry role="parameter_description"><para>a SPDX license string, e.g. "CC-BY-3.0 and GFDL-1.3"</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="as-is-spdx-license-expression.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the icon is a valid "SPDX license"</para>
</refsect3><para role="since">Since: <link linkend="api-index-0.9.8">0.9.8</link></para></refsect2>
<refsect2 id="as-spdx-license-tokenize" role="function" condition="since:0.9.8">
<title>as_spdx_license_tokenize&#160;()</title>
<indexterm zone="as-spdx-license-tokenize" role="0.9.8"><primary>as_spdx_license_tokenize</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;**
as_spdx_license_tokenize (<parameter>const <link linkend="gchar"><type>gchar</type></link> *license</parameter>);</programlisting>
<para>Tokenizes the SPDX license string (or any simarly formatted string)
into parts. Any licence parts of the string e.g. "LGPL-2.0+" are prefexed
with "@", the conjunctive replaced with "&amp;" and the disjunctive replaced
with "|". Brackets are added as indervidual tokens and other strings are
appended into single tokens where possible.</para>
<refsect3 id="as-spdx-license-tokenize.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>license</para></entry>
<entry role="parameter_description"><para>a license string, e.g. "LGPLv2+ and (QPL or GPLv2) and MIT"</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="as-spdx-license-tokenize.returns" role="returns">
<title>Returns</title>
<para> array of strings, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for invalid. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-0.9.8">0.9.8</link></para></refsect2>
<refsect2 id="as-spdx-license-detokenize" role="function" condition="since:0.9.8">
<title>as_spdx_license_detokenize&#160;()</title>
<indexterm zone="as-spdx-license-detokenize" role="0.9.8"><primary>as_spdx_license_detokenize</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
as_spdx_license_detokenize (<parameter><link linkend="gchar"><type>gchar</type></link> **license_tokens</parameter>);</programlisting>
<para>De-tokenizes the SPDX licenses into a string.</para>
<refsect3 id="as-spdx-license-detokenize.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>license_tokens</para></entry>
<entry role="parameter_description"><para>license tokens, typically from <link linkend="as-spdx-license-tokenize"><function>as_spdx_license_tokenize()</function></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="as-spdx-license-detokenize.returns" role="returns">
<title>Returns</title>
<para> string, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> for invalid. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para role="since">Since: <link linkend="api-index-0.9.8">0.9.8</link></para></refsect2>
<refsect2 id="as-license-to-spdx-id" role="function" condition="since:0.9.8">
<title>as_license_to_spdx_id&#160;()</title>
<indexterm zone="as-license-to-spdx-id" role="0.9.8"><primary>as_license_to_spdx_id</primary></indexterm>
<programlisting language="C"><link linkend="gchar"><returnvalue>gchar</returnvalue></link>&#160;*
as_license_to_spdx_id (<parameter>const <link linkend="gchar"><type>gchar</type></link> *license</parameter>);</programlisting>
<para>Converts a non-SPDX license into an SPDX format string where possible.</para>
<refsect3 id="as-license-to-spdx-id.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>license</para></entry>
<entry role="parameter_description"><para>a not-quite SPDX license string, e.g. "GPLv3+"</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="as-license-to-spdx-id.returns" role="returns">
<title>Returns</title>
<para> the best-effort SPDX license string</para>
</refsect3><para role="since">Since: <link linkend="api-index-0.9.8">0.9.8</link></para></refsect2>
<refsect2 id="as-license-is-metadata-license" role="function">
<title>as_license_is_metadata_license&#160;()</title>
<indexterm zone="as-license-is-metadata-license"><primary>as_license_is_metadata_license</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
as_license_is_metadata_license (<parameter>const <link linkend="gchar"><type>gchar</type></link> *license</parameter>);</programlisting>
<para>Check if the metadata license is suitable for mixing with other
metadata and redistributing the bundled result (this means we
prefer permissive licenses here, to not require people shipping
catalog metadata to perform a full license review).</para>
<para>This method checks against a hardcoded list of permissive licenses
commonly used to license metadata under.</para>
<para>Retrurns: <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the license contains only permissive licenses suitable
as metadata license.</para>
<refsect3 id="as-license-is-metadata-license.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>license</para></entry>
<entry role="parameter_description"><para>The SPDX license string to test.</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="appstream-as-spdx.other_details" role="details">
<title role="details.title">Types and Values</title>

</refsect1>

</refentry>
