~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~ 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 {{{https://ant.apache.org/manual/Tasks/typedef.html} <<>>}} rather than {{{https://ant.apache.org/manual/Tasks/componentdef.html} <<>>}} 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 | <<>> *-------*---------+-------------+ | dojo | {{{http://dojotoolkit.org/community/licensing.shtml}License of the Dojo Toolkit}} | <<>> | | | *-------*---------+-------------+ | generated | Generated documents that don't need a license | <<>> *-------*---------+-------------+ | gpl1 | {{{http://www.gnu.org/licenses/old-licenses/gpl-1.0.html}GNU General Public License, version 1}} | <<>> | | | *-------*---------+-------------+ | gpl2 | {{{http://www.gnu.org/licenses/old-licenses/gpl-2.0.html}GNU General Public License, version 2}} | <<>> | | | *-------*---------+-------------+ | gpl3 | {{{http://www.gnu.org/licenses/gpl.html}GNU General Public License, version 3}} | <<>> | | | *-------*---------+-------------+ | javadoc | Javadocs that don't need a license | <<>> *-------*---------+-------------+ | mit | {{{http://www.opensource.org/licenses/MIT}The MIT License}} | <<>> | | | *-------*---------+-------------+ | oasis | OASIS copyright claim plus derivative work clause | <<>> | | | *-------*---------+-------------+ | w3c | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<>> *-------*---------+-------------+ | w3c-doc | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<>> *-------*---------+-------------+ While these types may technically provide attributes or nested elements you should use them as sole tags. * {<<>>} 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 <<>> 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 <<>> elements inside the XML report. | | <> *-------------------------*-------------------------------+ | 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 <<>> elements inside the XML report. | | <> *-------------------------*-------------------------------+ | notes | Additional notes you want to provide. | | This will not appear inside the plain text report and creates <<>> elements inside the XML report. *-------------------------*-------------------------------+ ** Nested Elements Supported by the Type The substring(s) to look for are specified as nested <<>> elements with a substring attribute. You can specifiy multiple <<>> elements and the <<>> 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 ------------------------------------------------------------------ ------------------------------------------------------------------ * {<<>>} 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 <<>> elements inside the XML report. | | <> *-------------------------*-------------------------------+ | 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 <<>> elements inside the XML report. | | <> *-------------------------*-------------------------------+ | notes | Additional notes you want to provide. | | This will not appear inside the plain text report and creates <<>> elements inside the XML report. *-------------------------*-------------------------------+ | fullText | The license text to look for. | | Everything that is not a character or a digit will be ignored. | | <> 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 ------------------------------------------------------------------ ------------------------------------------------------------------ or ------------------------------------------------------------------ Yet Another Software License, 1.0 Lots of text, specifying the users rights, and whatever ------------------------------------------------------------------ {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 | <<>> | | | *-------*---------+-------------+ | apache20-license | Apache License 2.0 | <<>> *-------*---------+-------------+ | gpl1-family | GNU General Public License, version 1 | <<>> | | | *-------*---------+-------------+ | gpl2-family | GNU General Public License, version 2 | <<>> | | | *-------*---------+-------------+ | gpl3-family | GNU General Public License, version 3 | <<>> | | | *-------*---------+-------------+ | mit-family | The MIT License | <<>> | | | *-------*---------+-------------+ | modified-bsd | Modified BSD License | <<>> | | | *-------*---------+-------------+ | oasis-license | OASIS copyright claim plus derivative work clause | <<>> | | | *-------*---------+-------------+ | w3c-doc-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-documents-20021231}W3C Document License}} | <<>> *-------*---------+-------------+ | w3c-soft-license | {{{http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231}W3C Software License}} | <<>> *-------*---------+-------------+ While these types may technically provide attributes or nested elements you should use them as sole tags. * {<<>>} This wrapper type makes it easy to specify a license name for new approved licenses. The type has a single attribute <<>> 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 ------------------------------------------------------------------ ------------------------------------------------------------------