View Javadoc
1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one   *
3    * or more contributor license agreements.  See the NOTICE file *
4    * distributed with this work for additional information        *
5    * regarding copyright ownership.  The ASF licenses this file   *
6    * to you under the Apache License, Version 2.0 (the            *
7    * "License"); you may not use this file except in compliance   *
8    * with the License.  You may obtain a copy of the License at   *
9    *                                                              *
10   *   http://www.apache.org/licenses/LICENSE-2.0                 *
11   *                                                              *
12   * Unless required by applicable law or agreed to in writing,   *
13   * software distributed under the License is distributed on an  *
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY       *
15   * KIND, either express or implied.  See the License for the    *
16   * specific language governing permissions and limitations      *
17   * under the License.                                           *
18   */
19  package org.apache.rat;
20  
21  import java.io.File;
22  import java.io.IOException;
23  import java.io.PrintWriter;
24  import java.io.Serializable;
25  import java.util.Arrays;
26  import java.util.Collections;
27  import java.util.Comparator;
28  import java.util.Map;
29  import java.util.TreeMap;
30  import java.util.function.Consumer;
31  import java.util.function.Supplier;
32  import java.util.stream.Collectors;
33  
34  import org.apache.commons.cli.CommandLine;
35  import org.apache.commons.cli.DefaultParser;
36  import org.apache.commons.cli.Option;
37  import org.apache.commons.cli.Options;
38  import org.apache.commons.cli.ParseException;
39  import org.apache.rat.api.Document;
40  import org.apache.rat.commandline.Arg;
41  import org.apache.rat.commandline.ArgumentContext;
42  import org.apache.rat.commandline.StyleSheets;
43  import org.apache.rat.config.exclusion.StandardCollection;
44  import org.apache.rat.document.DocumentName;
45  import org.apache.rat.document.DocumentNameMatcher;
46  import org.apache.rat.document.FileDocument;
47  import org.apache.rat.help.Licenses;
48  import org.apache.rat.license.LicenseSetFactory;
49  import org.apache.rat.report.IReportable;
50  import org.apache.rat.report.claim.ClaimStatistic;
51  import org.apache.rat.utils.DefaultLog;
52  import org.apache.rat.utils.Log.Level;
53  import org.apache.rat.walker.ArchiveWalker;
54  import org.apache.rat.walker.DirectoryWalker;
55  
56  import static java.lang.String.format;
57  
58  /**
59   * The collection of standard options for the CLI as well as utility methods to manage them and methods to create the
60   * ReportConfiguration from the options and an array of arguments.
61   */
62  public final class OptionCollection {
63  
64      private OptionCollection() {
65          // do not instantiate
66      }
67  
68      /** The Option comparator to sort the help */
69      public static final Comparator<Option> OPTION_COMPARATOR = new OptionComparator();
70  
71      /** The Help option */
72      public static final Option HELP = new Option("?", "help", false, "Print help for the RAT command line interface and exit.");
73  
74      /** A mapping of {@code argName(value)} values to a description of those values. */
75      @Deprecated
76      private static final Map<String, Supplier<String>> ARGUMENT_TYPES;
77      static {
78          ARGUMENT_TYPES = new TreeMap<>();
79          for (ArgumentType argType : ArgumentType.values()) {
80              ARGUMENT_TYPES.put(argType.getDisplayName(), argType.description);
81          }
82      }
83  
84      /**
85       * Gets the mapping of {@code argName(value)} values to a description of those values.
86       * @return the mapping of {@code argName(value)} values to a description of those values.
87       * @deprecated use {@link ArgumentType}
88       */
89      @Deprecated
90      public static Map<String, Supplier<String>> getArgumentTypes() {
91          return Collections.unmodifiableMap(ARGUMENT_TYPES);
92      }
93  
94      /**
95       * Join a collection of objects together as a comma separated list of their string values.
96       * @param args the objects to join together.
97       * @return the comma separated string.
98       */
99      private static String asString(final Object[] args) {
100         return Arrays.stream(args).map(Object::toString).collect(Collectors.joining(", "));
101     }
102 
103     /**
104      * Parses the standard options to create a ReportConfiguration.
105      *
106      * @param workingDirectory The directory to resolve relative file names against.
107      * @param args the arguments to parse
108      * @param helpCmd the help command to run when necessary.
109      * @return a ReportConfiguration or {@code null} if Help was printed.
110      * @throws IOException on error.
111      */
112     public static ReportConfiguration parseCommands(final File workingDirectory, final String[] args, final Consumer<Options> helpCmd) throws IOException {
113         return parseCommands(workingDirectory, args, helpCmd, false);
114     }
115 
116     /**
117      * Parses the standard options to create a ReportConfiguration.
118      *
119      * @param workingDirectory The directory to resolve relative file names against.
120      * @param args the arguments to parse
121      * @param helpCmd the help command to run when necessary.
122      * @param noArgs If {@code true} then the commands do not need extra arguments.
123      * @return a ReportConfiguration or {@code null} if Help was printed.
124      * @throws IOException on error.
125      */
126     public static ReportConfiguration parseCommands(final File workingDirectory, final String[] args,
127                                                     final Consumer<Options> helpCmd, final boolean noArgs) throws IOException {
128         Options opts = buildOptions();
129         CommandLine commandLine;
130         try {
131             commandLine = DefaultParser.builder().setDeprecatedHandler(DeprecationReporter.getLogReporter())
132                     .setAllowPartialMatching(true).build().parse(opts, args);
133         } catch (ParseException e) {
134             DefaultLog.getInstance().error(e.getMessage());
135             DefaultLog.getInstance().error("Please use the \"--help\" option to see a list of valid commands and options.", e);
136             System.exit(1);
137             return null; // dummy return (won't be reached) to avoid Eclipse complaint about possible NPE
138             // for "commandLine"
139         }
140 
141         Arg.processLogLevel(commandLine);
142 
143         ArgumentContext argumentContext = new ArgumentContext(workingDirectory, commandLine);
144 
145         if (commandLine.hasOption(HELP)) {
146             helpCmd.accept(opts);
147             return null;
148         }
149 
150         if (commandLine.hasOption(Arg.HELP_LICENSES.option())) {
151             new Licenses(createConfiguration(argumentContext), new PrintWriter(System.out)).printHelp();
152             return null;
153         }
154 
155         ReportConfiguration configuration = createConfiguration(argumentContext);
156         if (!noArgs && !configuration.hasSource()) {
157             String msg = "No directories or files specified for scanning. Did you forget to close a multi-argument option?";
158             DefaultLog.getInstance().error(msg);
159             helpCmd.accept(opts);
160             throw new ConfigurationException(msg);
161         }
162 
163         return configuration;
164     }
165 
166     /**
167      * Create the report configuration.
168      * Note: this method is package private for testing.
169      * You probably want one of the {@code ParseCommands} methods.
170      * @param argumentContext The context to execute in.
171      * @return a ReportConfiguration
172      * @see #parseCommands(File, String[], Consumer)
173      * @see #parseCommands(File, String[], Consumer, boolean)
174      */
175     static ReportConfiguration createConfiguration(final ArgumentContext argumentContext) {
176         argumentContext.processArgs();
177         final ReportConfiguration configuration = argumentContext.getConfiguration();
178         final CommandLine commandLine = argumentContext.getCommandLine();
179         if (Arg.DIR.isSelected()) {
180             try {
181                 configuration.addSource(getReportable(commandLine.getParsedOptionValue(Arg.DIR.getSelected()), configuration));
182             } catch (ParseException e) {
183                 throw new ConfigurationException("Unable to set parse " + Arg.DIR.getSelected(), e);
184             }
185         }
186         for (String s : commandLine.getArgs()) {
187             IReportable reportable = getReportable(new File(s), configuration);
188             if (reportable != null) {
189                 configuration.addSource(reportable);
190             }
191         }
192         return configuration;
193     }
194 
195     /**
196      * Create an {@code Options} object from the list of defined Options.
197      * Mutually exclusive options must be listed in an OptionGroup.
198      * @return the Options comprised of the Options defined in this class.
199      */
200     public static Options buildOptions() {
201         return Arg.getOptions().addOption(HELP);
202     }
203 
204     /**
205      * Creates an IReportable object from the directory name and ReportConfiguration
206      * object.
207      *
208      * @param base the directory that contains the files to report on.
209      * @param config the ReportConfiguration.
210      * @return the IReportable instance containing the files.
211      */
212     static IReportable getReportable(final File base, final ReportConfiguration config) {
213         File absBase = base.getAbsoluteFile();
214         DocumentName documentName = DocumentName.builder(absBase).build();
215         if (!absBase.exists()) {
216             DefaultLog.getInstance().error("Directory '" + documentName + "' does not exist.");
217             return null;
218         }
219         DocumentNameMatcher documentExcluder = config.getDocumentExcluder(documentName);
220 
221         Document doc = new FileDocument(documentName, absBase, documentExcluder);
222         if (!documentExcluder.matches(doc.getName())) {
223             DefaultLog.getInstance().error("Directory '" + documentName + "' is in excluded list.");
224             return null;
225         }
226 
227         if (absBase.isDirectory()) {
228             return new DirectoryWalker(doc);
229         }
230 
231         return new ArchiveWalker(doc);
232     }
233 
234     /**
235      * This class implements the {@code Comparator} interface for comparing Options.
236      */
237     private static final class OptionComparator implements Comparator<Option>, Serializable {
238         /** The serial version UID.  */
239         private static final long serialVersionUID = 5305467873966684014L;
240 
241         private String getKey(final Option opt) {
242             String key = opt.getOpt();
243             key = key == null ? opt.getLongOpt() : key;
244             return key;
245         }
246 
247         /**
248          * Compares its two arguments for order. Returns a negative integer, zero, or a
249          * positive integer as the first argument is less than, equal to, or greater
250          * than the second.
251          *
252          * @param opt1 The first Option to be compared.
253          * @param opt2 The second Option to be compared.
254          * @return a negative integer, zero, or a positive integer as the first argument
255          * is less than, equal to, or greater than the second.
256          */
257         @Override
258         public int compare(final Option opt1, final Option opt2) {
259             return getKey(opt1).compareToIgnoreCase(getKey(opt2));
260         }
261     }
262 
263     public enum ArgumentType {
264         /**
265          * A plain file.
266          */
267         FILE("File", () -> "A file name."),
268         /**
269          * An Integer.
270          */
271         INTEGER("Integer", () -> "An integer value."),
272         /**
273          * A directory or archive.
274          */
275         DIRORARCHIVE("DirOrArchive", () -> "A directory or archive file to scan."),
276         /**
277          * A matching expression.
278          */
279         EXPRESSION("Expression", () -> "A file matching pattern usually of the form used in Ant build files and " +
280                 "'.gitignore' files (see https://ant.apache.org/manual/dirtasks.html#patterns for examples). " +
281                 "Regular expression patterns may be specified by surrounding the pattern with '%regex[' and ']'. " +
282                 "For example '%regex[[A-Z].*]' would match files and directories that start with uppercase latin letters."),
283         /**
284          * A license filter.
285          */
286         LICENSEFILTER("LicenseFilter", () -> format("A defined filter for the licenses to include. Valid values: %s.",
287                 asString(LicenseSetFactory.LicenseFilter.values()))),
288         /**
289          * A log level.
290          */
291         LOGLEVEL("LogLevel", () -> format("The log level to use. Valid values %s.", asString(Level.values()))),
292         /**
293          * A processing type.
294          */
295         PROCESSINGTYPE("ProcessingType", () -> format("Specifies how to process file types. Valid values are: %s%n",
296                 Arrays.stream(ReportConfiguration.Processing.values())
297                         .map(v -> format("\t%s: %s", v.name(), v.desc()))
298                         .collect(Collectors.joining(System.lineSeparator())))),
299         /**
300          * A style sheet.
301          */
302         STYLESHEET("StyleSheet", () -> format("Either an external xsl file or one of the internal named sheets. Internal sheets are: %n%s",
303                 Arrays.stream(StyleSheets.values())
304                         .map(v -> format("\t%s: %s%n", v.arg(), v.desc()))
305                         .collect(Collectors.joining(System.lineSeparator())))),
306         /**
307          * A license id.
308          */
309         LICENSEID("LicenseID", () -> "The ID for a license."),
310         /**
311          * A license family id.
312          */
313         FAMILYID("FamilyID", () -> "The ID for a license family."),
314         /**
315          * A standard collection name.
316          */
317         STANDARDCOLLECTION("StandardCollection", () -> format("Defines standard expression patterns (see above). Valid values are: %n%s%n",
318                 Arrays.stream(StandardCollection.values())
319                         .map(v -> format("\t%s: %s%n", v.name(), v.desc()))
320                         .collect(Collectors.joining(System.lineSeparator())))),
321         /**
322          * A Counter pattern name
323          */
324         COUNTERPATTERN("CounterPattern", () -> format("A pattern comprising one of the following prefixes followed by " +
325                         "a colon and a count (e.g. %s:5).  Prefixes are %n%s.", ClaimStatistic.Counter.UNAPPROVED,
326                 Arrays.stream(ClaimStatistic.Counter.values())
327                         .map(v -> format("\t%s: %s Default range [%s, %s]%n", v.name(), v.getDescription(),
328                                 v.getDefaultMinValue(),
329                                 v.getDefaultMaxValue() == -1 ? "unlimited" : v.getDefaultMaxValue()))
330                         .collect(Collectors.joining(System.lineSeparator())))),
331         /**
332          * A generic argument.
333          */
334         ARG("Arg", () -> "A string"),
335         /**
336          * No argument.
337          */
338         NONE("", () -> "");
339 
340         /**
341          * The display name
342          */
343         private final String displayName;
344         /**
345          * A supplier of the description
346          */
347         private final Supplier<String> description;
348 
349         ArgumentType(final String name,
350                      final Supplier<String> description) {
351             this.displayName = name;
352             this.description = description;
353         }
354 
355         public String getDisplayName() {
356             return displayName;
357         }
358 
359         public Supplier<String> description() {
360             return description;
361         }
362     }
363 }