blob: a54568042c3814bbdeaab592348acc8feab20ed1 [file] [log] [blame]
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.11.1 from src/site/apt/types.apt at 2024-04-28
| Rendered using Apache Maven Default Skin
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="generator" content="Apache Maven Doxia Site Renderer 1.11.1" />
<title>Apache Rat™ Task Library for Apache Ant &#x2013; Built-In Types</title>
<link rel="stylesheet" href="./css/maven-base.css" />
<link rel="stylesheet" href="./css/maven-theme.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<link href="https://creadur.apache.org/font/matesc.css" type="text/css" rel="stylesheet" />
</head>
<body class="composite">
<div id="banner">
<a href="https://www.apache.org/" id="bannerLeft"><img src="https://www.apache.org/img/asf_logo.png" alt="The Apache Software Foundation" title="The Apache Software Foundation"/></a> <div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xleft">
<span id="publishDate">Last Published: 2024-04-28</span>
| <span id="projectVersion">Version: 0.17-SNAPSHOT</span>
| <a href="https://www.apache.org/" class="externalLink" title="Apache">Apache</a> &gt;
<a href="https://creadur.apache.org/" class="externalLink" title="Creadur">Creadur</a> &gt;
<a href="https://creadur.apache.org/rat/" class="externalLink" title="Rat">Rat</a> &gt;
<a href="index.html" title="Apache Rat™ Task Library for Apache Ant">Apache Rat™ Task Library for Apache Ant</a> &gt;
Built-In Types
</div>
<div class="xright"> </div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>Parent Project</h5>
<ul>
<li class="none"><a href="../index.html" title="Apache Creadur Rat">Apache Creadur Rat</a></li>
</ul>
<h5>Overview</h5>
<ul>
<li class="none"><a href="index.html" title="Introduction">Introduction</a></li>
<li class="none"><a href="report.html" title="Report Task">Report Task</a></li>
<li class="none"><strong>Types</strong></li>
</ul>
<h5>Examples</h5>
<ul>
<li class="none"><a href="examples/basic.html" title="Basic Usage">Basic Usage</a></li>
<li class="none"><a href="examples/custom.html" title="Custom Types">Custom Types</a></li>
</ul>
<h5>Project Documentation</h5>
<ul>
<li class="collapsed"><a href="project-info.html" title="Project Information">Project Information</a></li>
<li class="collapsed"><a href="project-reports.html" title="Project Reports">Project Reports</a></li>
</ul>
<h5>Apache Rat™</h5>
<ul>
<li class="none"><a href="../index.html" title="Introducing Rat">Introducing Rat</a></li>
<li class="none"><a href="../apidocs/index.html" title="Javadocs">Javadocs</a></li>
<li class="none"><a href="../download_rat.cgi" title="Downloads">Downloads</a></li>
<li class="none"><a href="../RELEASE_NOTES.txt" title="Changes">Changes</a></li>
</ul>
<h5>Running Rat</h5>
<ul>
<li class="none"><a href="../apache-rat/index.html" title="From The Command Line">From The Command Line</a></li>
<li class="none"><a href="../apache-rat-tasks/index.html" title="With Ant">With Ant</a></li>
<li class="none"><a href="../apache-rat-plugin/index.html" title="With Maven">With Maven</a></li>
</ul>
<h5>Apache Creadur™</h5>
<ul>
<li class="none"><a href="https://creadur.apache.org" class="externalLink" title="Creadur Project Home">Creadur Project Home</a></li>
<li class="none"><a href="https://creadur.apache.org/tentacles" class="externalLink" title="Apache Tentacles">Apache Tentacles</a></li>
<li class="none"><a href="https://creadur.apache.org/whisker" class="externalLink" title="Apache Whisker">Apache Whisker</a></li>
<li class="none"><a href="https://www.apache.org/security/" class="externalLink" title="Security">Security</a></li>
<li class="none"><a href="https://www.apache.org/licenses/" class="externalLink" title="License">License</a></li>
<li class="none"><a href="https://privacy.apache.org/policies/privacy-policy-public.html" class="externalLink" title="Privacy">Privacy</a></li>
<li class="none"><a href="https://www.apache.org/foundation/sponsorship.html" class="externalLink" title="Sponsorship">Sponsorship</a></li>
<li class="none"><a href="https://www.apache.org/foundation/thanks.html" class="externalLink" title="Thanks">Thanks</a></li>
</ul>
<h5>The Apache Software Foundation</h5>
<ul>
<li class="none"><a href="https://www.apache.org/foundation" class="externalLink" title="About the Foundation">About the Foundation</a></li>
<li class="none"><a href="https://projects.apache.org" class="externalLink" title="The projects">The projects</a></li>
<li class="none"><a href="https://people.apache.org" class="externalLink" title="The people">The people</a></li>
<li class="none"><a href="https://www.apache.org/foundation/how-it-works.html" class="externalLink" title="How we work">How we work</a></li>
<li class="none"><a href="https://www.apache.org/foundation/how-it-works.html#history" class="externalLink" title="Our history">Our history</a></li>
<li class="none"><a href="https://blogs.apache.org/foundation/" class="externalLink" title="News">News</a></li>
</ul>
<h5>Contribute</h5>
<ul>
<li class="none"><a href="https://www.apache.org/foundation/getinvolved.html" class="externalLink" title="Get Involved">Get Involved</a></li>
</ul>
<h5>Committer Info</h5>
<ul>
<li class="none"><a href="https://www.apache.org/dev/committers.html" class="externalLink" title="ASF Committers' FAQ">ASF Committers' FAQ</a></li>
<li class="none"><a href="https://www.apache.org/dev/new-committers-guide.html" class="externalLink" title="New Committers Guide">New Committers Guide</a></li>
<li class="none"><a href="../site-publish.html" title="Howto publish this site">Howto publish this site</a></li>
<li class="none"><a href="https://community.apache.org/" class="externalLink" title="Community">Community</a></li>
<li class="none"><a href="https://www.apache.org/legal/" class="externalLink" title="Legal">Legal</a></li>
<li class="none"><a href="https://www.apache.org/foundation/marks/" class="externalLink" title="Branding">Branding</a></li>
<li class="none"><a href="https://www.apache.org/press/" class="externalLink" title="Media Relations">Media Relations</a></li>
</ul>
<a href="https://maven.apache.org/" title="Maven" class="poweredBy">
<img class="poweredBy" alt="Maven" src="https://maven.apache.org/images/logos/maven-feather.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<section>
<h2><a name="Built-In_Types"></a>Built-In Types</h2>
<p>The Rat Antlib defines a few Ant types that can be used as nested elements to the <a href="./report.html"> Report Task</a> as license matchers or license families.</p>
<p>In order to stay compatible with Ant 1.7.1 these types are defined via <a class="externalLink" href="https://ant.apache.org/manual/Tasks/typedef.html"> <code>typedef</code></a> rather than <a class="externalLink" href="https://ant.apache.org/manual/Tasks/componentdef.html"> <code>componentdef</code></a> which means they can be defined outside of the Report task as well - but they will be completely useless there.</p></section><section>
<h2><a name="License_Matchers">License Matchers</a></h2>
<p>The following types correspond to the built-in license matchers of Rat:</p>
<table border="1" class="bodyTable">
<tr class="a">
<td align="center">Typename</td>
<td align="left">Detected License</td>
<td align="left">Corresponding class</td></tr>
<tr class="b">
<td align="center">asl20</td>
<td align="left">Apache License 2.0</td>
<td align="left"><code>org.apache.rat.analysis.license.ApacheSoftwareLicense20</code></td></tr>
<tr class="a">
<td align="center">dojo <i>since Rat Antlib 0.8</i></td>
<td align="left"><a class="externalLink" href="http://dojotoolkit.org/community/licensing.shtml">License of the Dojo Toolkit</a></td>
<td align="left"><code>org.apache.rat.analysis.license.DojoLicenseHeader</code></td></tr>
<tr class="b">
<td align="center">generated</td>
<td align="left">Generated documents that don't need a license</td>
<td align="left"><code>org.apache.rat.analysis.generation.GeneratedLicenseNotRequired</code></td></tr>
<tr class="a">
<td align="center">gpl1 <i>since Rat Antlib 0.9</i></td>
<td align="left"><a class="externalLink" href="http://www.gnu.org/licenses/old-licenses/gpl-1.0.html">GNU General Public License, version 1</a></td>
<td align="left"><code>org.apache.rat.analysis.license.GPL1License</code></td></tr>
<tr class="b">
<td align="center">gpl2 <i>since Rat Antlib 0.9</i></td>
<td align="left"><a class="externalLink" href="http://www.gnu.org/licenses/old-licenses/gpl-2.0.html">GNU General Public License, version 2</a></td>
<td align="left"><code>org.apache.rat.analysis.license.GPL2License</code></td></tr>
<tr class="a">
<td align="center">gpl3 <i>since Rat Antlib 0.9</i></td>
<td align="left"><a class="externalLink" href="http://www.gnu.org/licenses/gpl.html">GNU General Public License, version 3</a></td>
<td align="left"><code>org.apache.rat.analysis.license.GPL3License</code></td></tr>
<tr class="b">
<td align="center">javadoc</td>
<td align="left">Javadocs that don't need a license</td>
<td align="left"><code>org.apache.rat.analysis.generation.JavaDocLicenseNotRequired</code></td></tr>
<tr class="a">
<td align="center">mit <i>since Rat Antlib 0.9</i></td>
<td align="left"><a class="externalLink" href="http://www.opensource.org/licenses/MIT">The MIT License</a></td>
<td align="left"><code>org.apache.rat.analysis.license.MITLicense</code></td></tr>
<tr class="b">
<td align="center">oasis <i>since Rat Antlib 0.8</i></td>
<td align="left">OASIS copyright claim plus derivative work clause</td>
<td align="left"><code>org.apache.rat.analysis.license.OASISLicense</code></td></tr>
<tr class="a">
<td align="center">w3c</td>
<td align="left"><a class="externalLink" href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231">W3C Software License</a></td>
<td align="left"><code>org.apache.rat.analysis.license.W3CLicense</code></td></tr>
<tr class="b">
<td align="center">w3c-doc</td>
<td align="left"><a class="externalLink" href="http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231">W3C Document License</a></td>
<td align="left"><code>org.apache.rat.analysis.license.W3CDocLicense</code></td></tr></table>
<p>While these types may technically provide attributes or nested elements you should use them as sole tags.</p><section>
<h3><a name="substringMatcher"><code>substringMatcher</code></a></h3>
<p><i>since Rat Antlib 0.8</i></p>
<p>For the simple case where a license can be detected by searching for a given string in a single line of the source code - in fact this is what many built-in implementations do - you can use the <code>substringMatcher</code> type.</p><section>
<h4><a name="Attributes_of_the_Type"></a>Attributes of the Type</h4>
<table border="1" class="bodyTable">
<tr class="a">
<td align="center">Name</td>
<td align="left">Description</td></tr>
<tr class="b">
<td align="center">licenseFamilyCategory</td>
<td align="left">Short name of the detected license. Should be at most five characters long if you want to keep the layout of the plain text report. This will be printed next to to the checked file inside the plain text report and creates <code>header-type</code> elements inside the XML report. <b>REQUIRED</b></td></tr>
<tr class="a">
<td align="center">licenseFamilyName</td>
<td align="left">Long name of the detected license. The value is checked against the list of approved licenses. This will not appear inside the plain text report and creates <code>license-family</code> elements inside the XML report. <b>REQUIRED</b></td></tr>
<tr class="b">
<td align="center">notes</td>
<td align="left">Additional notes you want to provide. This will not appear inside the plain text report and creates <code>header-sample</code> elements inside the XML report.</td></tr></table></section><section>
<h4><a name="Nested_Elements_Supported_by_the_Type"></a>Nested Elements Supported by the Type</h4>
<p>The substring(s) to look for are specified as nested <code>pattern</code> elements with a substring attribute. You can specifiy multiple <code>pattern</code> elements and the <code>substringMatcher</code> will claim the license matches if at least one substring can be found.</p>
<p>At least one pattern is required.</p></section><section>
<h4><a name="Example"></a>Example</h4>
<p>Taking the example of <a href="./examples/custom.html">the custom types page</a> in order to detect</p>
<div>
<pre> /**
* Yet Another Software License, 1.0
*
* Lots of text, specifying the users rights, and whatever ...
*/</pre></div>
<p>you could use</p>
<div>
<pre>&lt;rat:report&gt;
&lt;fileset dir=&quot;src&quot;/&gt;
&lt;rat:substringMatcher licenseFamilyCategory=&quot;YASL1&quot;
licenseFamilyName=&quot;Yet Another Software License, Version 1.0&quot;&gt;
&lt;pattern substring=&quot;Yet Another Software License, 1.0&quot;/&gt;
&lt;/rat:substringMatcher&gt;
&lt;/rat:report&gt;</pre></div></section></section><section>
<h3><a name="fullTextMatcher"><code>fullTextMatcher</code></a></h3>
<p><i>since Rat Antlib 0.9</i></p>
<p>This matcher searches for the full text given, ignoring everything that is not a character or a number (and for US-ASCII characters it is case-insensitive). This allows licenses to be detected that can't be identified by a single line, even if the formatting has been changed.</p><section>
<h4><a name="Attributes_of_the_Type"></a>Attributes of the Type</h4>
<table border="1" class="bodyTable">
<tr class="a">
<td align="center">Name</td>
<td align="left">Description</td></tr>
<tr class="b">
<td align="center">licenseFamilyCategory</td>
<td align="left">Short name of the detected license. Should be at most five characters long if you want to keep the layout of the plain text report. This will be printed next to to the checked file inside the plain text report and creates <code>header-type</code> elements inside the XML report. <b>REQUIRED</b></td></tr>
<tr class="a">
<td align="center">licenseFamilyName</td>
<td align="left">Long name of the detected license. The value is checked against the list of approved licenses. This will not appear inside the plain text report and creates <code>license-family</code> elements inside the XML report. <b>REQUIRED</b></td></tr>
<tr class="b">
<td align="center">notes</td>
<td align="left">Additional notes you want to provide. This will not appear inside the plain text report and creates <code>header-sample</code> elements inside the XML report.</td></tr>
<tr class="a">
<td align="center">fullText</td>
<td align="left">The license text to look for. Everything that is not a character or a digit will be ignored. <b>REQUIRED</b> unless the text is specified as nested content.</td></tr></table>
<p>You can also nest the license text directly as content into the type.</p></section><section>
<h4><a name="Example"></a>Example</h4>
<p>Taking the example of <a href="./examples/custom.html">the custom types page</a> in order to detect</p>
<div>
<pre> /**
* Yet Another Software License, 1.0
*
* Lots of text, specifying the users rights, and whatever ...
*/</pre></div>
<p>you could use</p>
<div>
<pre>&lt;rat:report&gt;
&lt;fileset dir=&quot;src&quot;/&gt;
&lt;rat:fullTextMatcher licenseFamilyCategory=&quot;YASL1&quot;
licenseFamilyName=&quot;Yet Another Software License, Version 1.0&quot;
fullText=&quot;Yet Another Software License, 1.0 Lots of text, specifying the users rights, and whatever&quot;&gt;
&lt;/rat:fullTextMatcher&gt;
&lt;/rat:report&gt;</pre></div>
<p>or</p>
<div>
<pre>&lt;rat:report&gt;
&lt;fileset dir=&quot;src&quot;/&gt;
&lt;rat:fullTextMatcher licenseFamilyCategory=&quot;YASL1&quot;
licenseFamilyName=&quot;Yet Another Software License, Version 1.0&quot;&gt;
Yet Another Software License, 1.0
Lots of text, specifying the users rights, and whatever
&lt;/rat:fullTextMatcher&gt;
&lt;/rat:report&gt;</pre></div></section></section></section><section>
<h2><a name="License_Families">License Families</a></h2>
<p>The following types correspond to the built-in license families of Rat:</p>
<table border="1" class="bodyTable">
<tr class="a">
<td align="center">Typename</td>
<td align="left">License Family</td>
<td align="left">Corresponding class</td></tr>
<tr class="b">
<td align="center">academic-free-21 <i>since Rat Antlib 0.8</i></td>
<td align="left">Academic Free License 2.1</td>
<td align="left"><code>org.apache.rat.license.AcademicFree21LicenseFamily</code></td></tr>
<tr class="a">
<td align="center">apache20-license</td>
<td align="left">Apache License 2.0</td>
<td align="left"><code>org.apache.rat.license.Apache20LicenseFamily</code></td></tr>
<tr class="b">
<td align="center">gpl1-family <i>since Rat Antlib 0.9</i></td>
<td align="left">GNU General Public License, version 1</td>
<td align="left"><code>org.apache.rat.license.GPL1LicenseFamily</code></td></tr>
<tr class="a">
<td align="center">gpl2-family <i>since Rat Antlib 0.9</i></td>
<td align="left">GNU General Public License, version 2</td>
<td align="left"><code>org.apache.rat.license.GPL2LicenseFamily</code></td></tr>
<tr class="b">
<td align="center">gpl3-family <i>since Rat Antlib 0.9</i></td>
<td align="left">GNU General Public License, version 3</td>
<td align="left"><code>org.apache.rat.license.GPL3LicenseFamily</code></td></tr>
<tr class="a">
<td align="center">mit-family <i>since Rat Antlib 0.9</i></td>
<td align="left">The MIT License</td>
<td align="left"><code>org.apache.rat.license.MITLicenseFamily</code></td></tr>
<tr class="b">
<td align="center">modified-bsd <i>since Rat Antlib 0.8</i></td>
<td align="left">Modified BSD License</td>
<td align="left"><code>org.apache.rat.license.ModifiedBSDLicenseFamily</code></td></tr>
<tr class="a">
<td align="center">oasis-license <i>since Rat Antlib 0.8</i></td>
<td align="left">OASIS copyright claim plus derivative work clause</td>
<td align="left"><code>org.apache.rat.license.OASISLicenseFamily</code></td></tr>
<tr class="b">
<td align="center">w3c-doc-license</td>
<td align="left"><a class="externalLink" href="http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231">W3C Document License</a></td>
<td align="left"><code>org.apache.rat.license.W3CDocumentLicenseFamily</code></td></tr>
<tr class="a">
<td align="center">w3c-soft-license</td>
<td align="left"><a class="externalLink" href="http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231">W3C Software License</a></td>
<td align="left"><code>org.apache.rat.license.W3CSoftwareLicenseFamily</code></td></tr></table>
<p>While these types may technically provide attributes or nested elements you should use them as sole tags.</p><section>
<h3><a name="approvedLicense"><code>approvedLicense</code></a></h3>
<p><i>since Rat Antlib 0.8</i></p>
<p>This wrapper type makes it easy to specify a license name for new approved licenses. The type has a single attribute <code>familyName</code> that must match the license family name returned by the license matcher to make a license approved.</p><section>
<h4><a name="Example"></a>Example</h4>
<p>To make the YASL license of the <a href="#substringMatcher">substringMatcher</a> Example approved you'd use</p>
<div>
<pre>&lt;rat:report&gt;
&lt;fileset dir=&quot;src&quot;/&gt;
&lt;rat:substringMatcher licenseFamilyCategory=&quot;YASL1&quot;
licenseFamilyName=&quot;Yet Another Software License, Version 1.0&quot;&gt;
&lt;pattern substring=&quot;Yet Another Software License, 1.0&quot;/&gt;
&lt;/rat:substringMatcher&gt;
&lt;rat:approvedLicense
familyName=&quot;Yet Another Software License, Version 1.0&quot;/&gt;
&lt;/rat:report&gt;</pre></div></section></section></section>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">
Copyright &copy; 2016-2024 The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache Creadur, Creadur, Apache Rat, Apache Tentacles, Apache Whisker, Apache and the Apache feather logo are trademarks
of The Apache Software Foundation.
Oracle and Java are registered trademarks of Oracle and/or its affiliates.
All other marks mentioned may be trademarks or registered trademarks of their respective owners.
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>