~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
~~   Licensed to the Apache Software Foundation (ASF) under one or more
~~   contributor license agreements.  See the NOTICE file distributed with
~~   this work for additional information regarding copyright ownership.
~~   The ASF licenses this file to You under the Apache License, Version 2.0
~~   (the "License"); you may not use this file except in compliance with
~~   the License.  You may obtain a copy of the License at
~~
~~       http://www.apache.org/licenses/LICENSE-2.0
~~
~~   Unless required by applicable law or agreed to in writing, software
~~   distributed under the License is distributed on an "AS IS" BASIS,
~~   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~   See the License for the specific language governing permissions and
~~   limitations under the License.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

                -----
                Built-In Types
                -----

Built-In Types

 The Rat Antlib defines a few Ant types that can be used as nested
 elements to the {{{./report.html} Report Task}} as license matchers or
 license families.

 In order to stay compatible with Ant 1.7.1 these types are defined
 via {{{http://ant.apache.org/manual/Tasks/typedef.html}
 <<<typedef>>>}} rather than
 {{{http://ant.apache.org/manual/Tasks/componentdef.html}
 <<<componentdef>>>}} which means they can be defined outside of the
 Report task as well - but they will be completely useless there.

{License Matchers}

 The following types correspond to the built-in license matchers of Rat:

*-------*---------+-------------+
| Typename | Detected License | Corresponding class |
*-------*---------+-------------+
| asl20 | Apache License 2.0 | <<<org.apache.rat.analysis.license.ApacheSoftwareLicense20>>>
*-------*---------+-------------+
| dojo | {{{http://dojotoolkit.org/community/licensing.shtml}License of the Dojo Toolkit}} | <<<org.apache.rat.analysis.license.DojoLicenseHeader>>>
| <since Rat Antlib 0.8> | |
*-------*---------+-------------+
| generated | Generated documents that don't need a license | <<<org.apache.rat.analysis.generation.GeneratedLicenseNotRequired>>>
*-------*---------+-------------+
| gpl1 | {{{http://www.gnu.org/licenses/old-licenses/gpl-1.0.html}GNU General Public License, version 1}} | <<<org.apache.rat.analysis.license.GPL1License>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| gpl2 | {{{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html}GNU General Public License, version 2}} | <<<org.apache.rat.analysis.license.GPL2License>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| gpl3 | {{{http://www.gnu.org/licenses/gpl.html}GNU General Public License, version 3}} | <<<org.apache.rat.analysis.license.GPL3License>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| javadoc | Javadocs that don't need a license | <<<org.apache.rat.analysis.generation.JavaDocLicenseNotRequired>>>
*-------*---------+-------------+
| mit | {{{http://www.opensource.org/licenses/MIT}The MIT License}} | <<<org.apache.rat.analysis.license.MITLicense>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| oasis | OASIS copyright claim plus derivative work clause | <<<org.apache.rat.analysis.license.OASISLicense>>>
| <since Rat Antlib 0.8> | |
*-------*---------+-------------+
| w3c | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<<org.apache.rat.analysis.license.W3CLicense>>>
*-------*---------+-------------+
| w3c-doc | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<<org.apache.rat.analysis.license.W3CDocLicense>>>
*-------*---------+-------------+

 While these types may technically provide attributes or nested
 elements you should use them as sole tags.

* {<<<substringMatcher>>>}

 <since Rat Antlib 0.8>

 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
 <<<substringMatcher>>> type.

**  Attributes of the Type

*-------------------------*-------------------------------+
|Name                     |Description                    |
*-------------------------*-------------------------------+
| licenseFamilyCategory | 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 <<<header-type>>> elements inside the XML report.
| | <<REQUIRED>>
*-------------------------*-------------------------------+
| licenseFamilyName | 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 <<<license-family>>> elements inside the XML report.
| | <<REQUIRED>>
*-------------------------*-------------------------------+
| notes | Additional notes you want to provide.
| | This will not appear inside the plain text report and creates <<<header-sample>>> elements inside the XML report.
*-------------------------*-------------------------------+

**  Nested Elements Supported by the Type

 The substring(s) to look for are specified as nested <<<pattern>>>
 elements with a substring attribute.  You can specifiy multiple
 <<<pattern>>> elements and the <<<substringMatcher>>> will claim the
 license matches if at least one substring can be found.

 At least one pattern is required.

** Example

 Taking the example of {{{./examples/custom.html}the custom types page}}
 in order to detect

------------------------------------------------------------------
  /**
   * Yet Another Software License, 1.0
   *
   * Lots of text, specifying the users rights, and whatever ...
   */
------------------------------------------------------------------

  you could use

------------------------------------------------------------------
<rat:report>
    <fileset dir="src"/>
    <rat:substringMatcher licenseFamilyCategory="YASL1"
             licenseFamilyName="Yet Another Software License, Version 1.0">
        <pattern substring="Yet Another Software License, 1.0"/>
    </rat:substringMatcher>
</rat:report>
------------------------------------------------------------------

* {<<<fullTextMatcher>>>}

 <since Rat Antlib 0.9>

 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.

**  Attributes of the Type

*-------------------------*-------------------------------+
|Name                     |Description                    |
*-------------------------*-------------------------------+
| licenseFamilyCategory | 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 <<<header-type>>> elements inside the XML report.
| | <<REQUIRED>>
*-------------------------*-------------------------------+
| licenseFamilyName | 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 <<<license-family>>> elements inside the XML report.
| | <<REQUIRED>>
*-------------------------*-------------------------------+
| notes | Additional notes you want to provide.
| | This will not appear inside the plain text report and creates <<<header-sample>>> elements inside the XML report.
*-------------------------*-------------------------------+
| fullText | The license text to look for.
| | Everything that is not a character or a digit will be ignored.
| | <<REQUIRED>> unless the text is specified as nested content.
*-------------------------*-------------------------------+

 You can also nest the license text directly as content into the type.

** Example

 Taking the example of {{{./examples/custom.html}the custom types page}}
 in order to detect

------------------------------------------------------------------
  /**
   * Yet Another Software License, 1.0
   *
   * Lots of text, specifying the users rights, and whatever ...
   */
------------------------------------------------------------------

  you could use

------------------------------------------------------------------
<rat:report>
    <fileset dir="src"/>
    <rat:fullTextMatcher licenseFamilyCategory="YASL1"
             licenseFamilyName="Yet Another Software License, Version 1.0"
             fullText="Yet Another Software License, 1.0 Lots of text, specifying the users rights, and whatever">
    </rat:fullTextMatcher>
</rat:report>
------------------------------------------------------------------

  or

------------------------------------------------------------------
<rat:report>
    <fileset dir="src"/>
    <rat:fullTextMatcher licenseFamilyCategory="YASL1"
             licenseFamilyName="Yet Another Software License, Version 1.0">
Yet Another Software License, 1.0

Lots of text, specifying the users rights, and whatever
    </rat:fullTextMatcher>
</rat:report>
------------------------------------------------------------------

{License Families}

 The following types correspond to the built-in license families of Rat:

*-------*---------+-------------+
| Typename | License Family | Corresponding class |
*-------*---------+-------------+
*-------*---------+-------------+
| academic-free-21 | Academic Free License 2.1 | <<<org.apache.rat.license.AcademicFree21LicenseFamily>>>
| <since Rat Antlib 0.8> | |
*-------*---------+-------------+
| apache20-license | Apache License 2.0 | <<<org.apache.rat.license.Apache20LicenseFamily>>>
*-------*---------+-------------+
| gpl1-family | GNU General Public License, version 1 | <<<org.apache.rat.license.GPL1LicenseFamily>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| gpl2-family | GNU General Public License, version 2 | <<<org.apache.rat.license.GPL2LicenseFamily>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| gpl3-family | GNU General Public License, version 3 | <<<org.apache.rat.license.GPL3LicenseFamily>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| mit-family | The MIT License | <<<org.apache.rat.license.MITLicenseFamily>>>
| <since Rat Antlib 0.9> | |
*-------*---------+-------------+
| modified-bsd | Modified BSD License | <<<org.apache.rat.license.ModifiedBSDLicenseFamily>>>
| <since Rat Antlib 0.8> | |
*-------*---------+-------------+
| oasis-license | OASIS copyright claim plus derivative work clause | <<<org.apache.rat.license.OASISLicenseFamily>>>
| <since Rat Antlib 0.8> | |
*-------*---------+-------------+
| w3c-doc-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<<org.apache.rat.license.W3CDocumentLicenseFamily>>>
*-------*---------+-------------+
| w3c-soft-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<<org.apache.rat.license.W3CSoftwareLicenseFamily>>>
*-------*---------+-------------+

 While these types may technically provide attributes or nested
 elements you should use them as sole tags.

* {<<<approvedLicense>>>}

 <since Rat Antlib 0.8>

 This wrapper type makes it easy to specify a license name for new
 approved licenses.  The type has a single attribute <<<familyName>>>
 that must match the license family name returned by the license
 matcher to make a license approved.

** Example

 To make the YASL license of the {{substringMatcher}} Example approved
 you'd use

------------------------------------------------------------------
<rat:report>
    <fileset dir="src"/>
    <rat:substringMatcher licenseFamilyCategory="YASL1"
             licenseFamilyName="Yet Another Software License, Version 1.0">
        <pattern substring="Yet Another Software License, 1.0"/>
    </rat:substringMatcher>
    <rat:approvedLicense
             familyName="Yet Another Software License, Version 1.0"/>
</rat:report>
------------------------------------------------------------------