| <!DOCTYPE html> |
| |
| |
| <!-- |
| | Generated by Apache Maven Doxia Site Renderer 2.0.0 from src/site/markdown/development/ui/options.md at 2025-09-13 |
| | Rendered using Apache Maven Fluido Skin 2.1.0 |
| --> |
| <html xmlns="http://www.w3.org/1999/xhtml" lang="en"> |
| <head> |
| <meta charset="UTF-8" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1" /> |
| <meta name="generator" content="Apache Maven Doxia Site Renderer 2.0.0" /> |
| <title>Options – Apache RAT™ - A Release Audit Tool</title> |
| <link rel="stylesheet" href="../../css/apache-maven-fluido-2.1.0.min.css" /> |
| <link rel="stylesheet" href="../../css/site.css" /> |
| <link rel="stylesheet" href="../../css/print.css" media="print" /> |
| <script src="../../js/apache-maven-fluido-2.1.0.min.js"></script> |
| <link href="https://creadur.apache.org/font/matesc.css" type="text/css" rel="stylesheet" /> |
| </head> |
| <body> |
| <a class="github-fork-ribbon right-top" href="https://github.com/apache/creadur-rat" data-ribbon="Fork me on GitHub">Fork me on GitHub</a> |
| <div class="container-fluid container-fluid-top"> |
| <header> |
| <div id="banner"> |
| <div class="pull-left"><div id="bannerLeft"><h1><a href="https://www.apache.org/"><img src="https://www.apache.org/img/asf_logo.png" alt="The Apache Software Foundation" /> Apache RAT</a></h1></div></div> |
| <div class="pull-right"></div> |
| <div class="clear"><hr/></div> |
| </div> |
| |
| <div id="breadcrumbs"> |
| <ul class="breadcrumb"> |
| <li id="publishDate">Last Published: 2025-09-13<span class="divider">|</span> |
| </li> |
| <li id="projectVersion">Version: 0.17-SNAPSHOT<span class="divider">|</span></li> |
| <li><a href="https://www.apache.org/">Apache</a><span class="divider">/</span></li> |
| <li><a href="../../../">Creadur</a><span class="divider">/</span></li> |
| <li><a href="../.././">RAT</a><span class="divider">/</span></li> |
| <li class="active">Options</li> |
| </ul> |
| </div> |
| </header> |
| <div class="row-fluid"> |
| <header id="leftColumn" class="span2"> |
| <nav class="well sidebar-nav"> |
| <ul class="nav nav-list"> |
| <li class="nav-header">Apache RAT™</li> |
| <li><a href="../../index.html">Introducing RAT</a></li> |
| <li><a href="../../download_rat.cgi">Downloads</a></li> |
| <li><a href="../../changes.html">Changes</a></li> |
| <li class="nav-header">RAT from the Command Line</li> |
| <li><a href="../../apache-rat/index.html">Command Line Introduction</a></li> |
| <li><a href="../../apache-rat/cli_options.html">Command Line Options</a></li> |
| <li><a href="../../apache-rat-core/exclusion_expression.html">Exclusion Expressions</a></li> |
| <li><a href="../../apache-rat/standard_collections.html">Standard Collections</a></li> |
| <li class="nav-header">RAT from Ant</li> |
| <li><a href="../../apache-rat-tasks/index.html">Ant Task Introduction</a></li> |
| <li><a href="../../apache-rat-tasks/ant_options.html">Ant Elements and Attributes</a></li> |
| <li class="nav-header">RAT from Maven</li> |
| <li><a href="../../apache-rat-plugin/index.html">Maven Plugin Introduction</a></li> |
| <li><a href="../../apache-rat-plugin/mvn_options.html">Maven Options</a></li> |
| <li><a href="../../apache-rat-plugin/examples/index.html">Maven Examples</a></li> |
| <li class="nav-header">Configuring RAT</li> |
| <li><a href="../../apache-rat/name_xref.html">Option Name Cross Reference</a></li> |
| <li><a href="../../apache-rat/default_licenses.html">Default Licenses</a></li> |
| <li><a href="../../apache-rat/default_matchers.html">Default Matchers</a></li> |
| <li><a href="../../license_def.html">Defining New Licenses</a></li> |
| <li><a href="../../apache-rat/xsd.html">Configuration XSD</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/default.xml">Default Configuration</a></li> |
| <li><a href="../../apache-rat/detecting_generated_files.html">Detecting Generated Files</a></li> |
| <li class="nav-header">RAT Output</li> |
| <li><a href="../../apache-rat/output/example.html">Standard Output Example</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/rat-report.xsd">Output XSD</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/plain-rat.xsl">XSLT - Plain text</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/missing-headers.xsl">XSLT - Missing headers list</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf/creadur-rat/blob/master/apache-rat-core/src/main/resources/org/apache/rat/unapproved-licenses.xsl">XSLT - Unapproved licenses list</a></li> |
| <li class="nav-header">Developing RAT</li> |
| <li><a href="../../architecture.html">Architecture</a></li> |
| <li><a href="../../apidocs/index.html">Javadocs</a></li> |
| <li><a href="../../apache-rat-core/development/document_name.html">Document Name concept</a></li> |
| <li><a href="../../development/ui_implementation.html">UI Development</a></li> |
| <li><a href="../../apache-rat-core/development/write_file_processor.html">Writing a File Processor</a></li> |
| <li class="nav-header">Apache Creadur™</li> |
| <li><a href="../../..">Creadur Project Home</a></li> |
| <li><a href="../../../tentacles">Apache Tentacles</a></li> |
| <li><a href="../../../whisker">Apache Whisker</a></li> |
| <li><a href="https://www.apache.org/security/">Security</a></li> |
| <li><a href="https://www.apache.org/licenses/">License</a></li> |
| <li><a href="https://privacy.apache.org/policies/privacy-policy-public.html">Privacy</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <li class="nav-header">The Apache Software Foundation</li> |
| <li><a href="https://www.apache.org/foundation">About the Foundation</a></li> |
| <li><a href="https://projects.apache.org">The projects</a></li> |
| <li><a href="https://people.apache.org">The people</a></li> |
| <li><a href="https://www.apache.org/foundation/how-it-works.html">How we work</a></li> |
| <li><a href="https://www.apache.org/foundation/how-it-works.html#history">Our history</a></li> |
| <li><a href="https://blogs.apache.org/foundation/">News</a></li> |
| <li class="nav-header">Contribute</li> |
| <li><a href="https://www.apache.org/foundation/getinvolved.html">Get Involved</a></li> |
| <li class="nav-header">Committer Info</li> |
| <li><a href="https://www.apache.org/dev/committers.html">ASF Committers' FAQ</a></li> |
| <li><a href="https://www.apache.org/dev/new-committers-guide.html">New Committers Guide</a></li> |
| <li><a href="https://gitbox.apache.org/repos/asf/creadur-site/blob/asf-site/README.md">How to publish this site</a></li> |
| <li><a href="https://community.apache.org/">Community</a></li> |
| <li><a href="https://www.apache.org/legal/">Legal</a></li> |
| <li><a href="https://www.apache.org/foundation/marks/">Branding</a></li> |
| <li><a href="https://www.apache.org/press/">Media Relations</a></li> |
| <li class="nav-header">Modules</li> |
| <li><a href="../../apache-rat-core/index.html">Apache Creadur RAT::Core</a></li> |
| <li><a href="../../apache-rat-plugin/index.html">Apache Creadur RAT::Plugin4Maven</a></li> |
| <li><a href="../../apache-rat-tasks/index.html">Apache Creadur RAT::Tasks4Ant</a></li> |
| <li><a href="../../apache-rat/index.html">Apache Creadur RAT::Packaging</a></li> |
| <li><a href="../../apache-rat-tools/index.html">Apache Creadur RAT::Tools</a></li> |
| <li><a href="../../apache-rat-testdata/index.html">Apache Creadur RAT::Testdata</a></li> |
| <li class="nav-header">Project Documentation</li> |
| <li><a href="../../project-info.html"><span class="icon-chevron-right"></span>Project Information</a></li> |
| <li><a href="../../project-reports.html"><span class="icon-chevron-right"></span>Project Reports</a></li> |
| </ul> |
| </nav> |
| <div class="well sidebar-nav"> |
| <div id="poweredBy"> |
| <div class="clear"></div> |
| <div class="clear"></div> |
| <a href="https://maven.apache.org/" class="builtBy"><img class="builtBy" src="https://maven.apache.org/images/logos/maven-feather.png" /> Maven</a> |
| </div> |
| </div> |
| </header> |
| <main id="bodyColumn" class="span10"> |
| <!--- |
| 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. |
| --> |
| <section><a id="Options"></a> |
| <h1>Options</h1> |
| <blockquote> |
| |
| <p>Up: <a href="../ui_implementation.html">UI Implementation</a> |
| <br />Options | <a href="./generator.html">Generator</a> | <a href="./ui_specific.html">UI Specific</a></p> |
| </blockquote> |
| <p>In this section we will explore how the RAT core module exposes the information necessary to build a UI specific Option implementation. We will be using the Maven tooling code in <code>apache-rat-tools</code> as the basis of the examples in this section. As always, the current code base is the source of truth.</p> |
| <p>RAT core uses the Apache Commons CLI library to process command line options. All the options are recorded in the <code>org.apache.rat.commandline.Arg</code> enumeration. Internally the Arg enumeration contains logical option groups that represent a single option. The use of option groups provides us a way to deprecate options and create replacements. Only one option in an option group may be used in a single RAT invocation.</p> |
| <p>Each UI will have a representation of the individual options specified within the Arg enumeration. To simplify the code each UI implementation should have an implementation of the <code>org.apache.rat.documentation.options.AbstractOption</code> class. This class will map the information contained in the <code>org.apache.commons.cli.Option</code> into methods that make sense with respect to the UI being implemented.</p> |
| <p>As an example we will look at the <code>org.apache.rat.documentation.options.MavenOption</code>.</p><section><a id="MavenOption"></a> |
| <h2>MavenOption</h2><section><a id="Name_conversion"></a> |
| <h3>Name conversion</h3> |
| <p>First to deal with the mapping from the kebab style to the camel case style, the <code>MavenOption</code> utilizes a static method in the <code>MavenGenerator</code> class to perform the conversion.</p> |
| |
| <pre class="prettyprint"><code class="language-java"> static String createName(final Option option) { |
| String name = StringUtils.defaultIfEmpty(option.getLongOpt(), option.getOpt()); |
| name = StringUtils.defaultIfEmpty(RENAME_MAP.get(name), name).toLowerCase(Locale.ROOT); |
| return new CasedString(StringCase.KEBAB, name).toCase(StringCase.CAMEL); |
| } |
| </code></pre> |
| <p>This method ensures that long options are selected over short options and then allows those options to be mapped to a different name. The remapping is an historical case where there was a camel case option in the CLI that had to be converted to kebab case first. In addition, it may be that a future CLI option will generate a camel case name that conflicts with some other UI based method. The mapping allows that to be easily overcome. Finally, the <code>createName</code> method uses the <code>org.apache.rat.utils.CasedString</code> and <code>org.apache.rat.utils.CasedString.StringCase</code> classes to convert the kebab case into the camel case. This method will always yield a camel case that starts with a lower case letter.</p></section><section><a id="Overridden_methods"></a> |
| <h3>Overridden methods</h3> |
| <p>The AbstractOption has several methods that should be overridden.</p><section><a id="cleanupName"></a> |
| <h4>cleanupName</h4> |
| <p>The cleanup name method is called by the AbstractOption to convert the <code>org.apache.commons.cli.Option</code> name (kebab style) into the name expected in the configuration of the UI. In the Maven case it returns the camel case name inside of angle brackets so that it appears as an XML element name.</p></section><section><a id="getDefaultValue"></a> |
| <h4>getDefaultValue</h4> |
| <p>The default value method will return the default value specified in the <code>org.apache.commons.cli.Option</code> unless it is overridden.</p> |
| <p>Maven allows the definition of default values for its options. The class <code>org.apache.rat.documentation.options.MavenOption</code> defines the default values for the CLI options that have default values in Maven. For example, the Maven environment expects the output of the tool to be written to a file and not displayed on standard out so this value is set as the default.</p></section></section><section><a id="Generating_the_method_signature"></a> |
| <h3>Generating the method signature</h3> |
| <p>The MavenGenerator needs to generate method signatures based on the <code>org.apache.commons.cli.Option</code> state so the MavenOption provides the <code>getMethodSignature</code> method. This method checks the following conditions:</p> |
| <ol style="list-style-type: decimal;"> |
| |
| <li>Is the option deprecated? If so add the <code>@Deprecated</code> annotation.</li> |
| <li>Does the option accept one or more arguments (i.e. is not a flag option)? If it does the argument should be a <code>String</code> otherwise it should be a <code>boolean</code>.</li> |
| <li>Does the method accept multiple arguments? If so modify the name to indicate plural as per the Maven standard.</li> |
| <li>Create the Maven <code>@Property</code> annotation with optional Maven command line property and defaults for the method.</li> |
| <li>Write all the information into a string and prefix the method name with “set” as per the Maven standard.</li> |
| </ol></section></section><section><a id="AntOption"></a> |
| <h2>AntOption</h2> |
| <p>The <code>AntOption</code> class is very similar to the <code>MavenOption</code> except that, as noted earlier, it creates XML Elements and Attributes depending on whether the option accepts more than one argument.</p> |
| <blockquote> |
| |
| <p>Up: <a href="../ui_implementation.html">UI Implementation</a> |
| <br />Options | <a href="./generator.html">Generator</a> | <a href="./ui_specific.html">UI Specific</a></p> |
| </blockquote></section></section> </main> |
| </div> |
| </div> |
| <hr/> |
| <footer> |
| <div class="container-fluid"> |
| <div class="row-fluid"> |
| Copyright © 2016-2025 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. |
| Apache Creadur, Creadur, Apache RAT, Apache Tentacles, Apache Whisker, Apache and the ASF 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> |
| </footer> |
| </body> |
| </html> |
