Move util classes from checker-qual to checker-util.

LICENSE.txt

@@ -11,11 +11,9 @@ the parts that you might want to include with your own program.
 
  * The annotations and utility files are licensed under the MIT License.
    (The text of this license also appears below.)  This applies to the
-   checker-qual*.jar and all the files that appear in it:  every file in a
-   qual/ directory, plus utility files FormatUtil.java,
-   I18nFormatUtil.java, NullnessUtil.java, Opt.java, PurityUnqualified.java,
-   RegexUtil.java, SignednessUtil.java, SignednessUtilExtra.java, and
-   UnitsTools.java.  It also applies to the cleanroom implementations of
+   checker-qual*.jar and checker-util.jar and all the files that appear in it,
+   all files in checker-qual and checker-util directories.
+   It also applies to the cleanroom implementations of
    third-party annotations (in checker/src/testannotations/,
    framework/src/main/java/org/jmlspecs/, and
    framework/src/main/java/com/google/).

build.gradle

@@ -223,7 +223,6 @@ allprojects {
             }
 
             // Error prone depends on checker-qual.jar, so don't run it on that project to avoid a circular dependency.
-            // All the classes in checker-qual are also in checker, so they are checked.
             // TODO: enable Error Prone on test classes.
             if (it.name.equals('compileJava') && !project.name.startsWith('checker-qual')) {
                 // Error Prone must be available in the annotation processor path
@@ -397,7 +396,7 @@ task allJavadoc(type: Javadoc, group: "Documentation") {
     description = 'Generates a global API documentation for all the modules'
     dependsOn(':checker:shadowJar', 'getPlumeScripts', 'getHtmlTools')
     destinationDir = file("${rootDir}/docs/api")
-    source(project(':checker').sourceSets.main.allJava, project(':framework').sourceSets.main.allJava,
+    source(project(':checker-util').sourceSets.main.allJava, project(':checker-qual').sourceSets.main.allJava, project(':checker').sourceSets.main.allJava, project(':framework').sourceSets.main.allJava,
             project(':dataflow').sourceSets.main.allJava, project(':javacutil').sourceSets.main.allJava)
 
     classpath = configurations.allProjects
@@ -456,7 +455,7 @@ def createJavadocTask(taskName, taskDescription, memberLevel) {
         destinationDir = file("${rootDir}/docs/tmpapi")
         destinationDir.mkdirs()
         subprojects.forEach {
-            if (!it.name.startsWith("checker-qual")) {
+            if (!it.name.startsWith("checker-qual-android")) {
                 source += it.sourceSets.main.allJava
             }
         }
@@ -601,8 +600,8 @@ subprojects {
 
     task checkFormat(type: Exec, dependsOn: [getCodeFormatScripts, pythonIsInstalled], group: 'Format') {
         description 'Check whether the source code is properly formatted'
-        // checker-qual* projects have no source, so skip
-        onlyIf {!project.name.startsWith('checker-qual') }
+        // checker-qual-android project have no source, so skip
+        onlyIf {!project.name.startsWith('checker-qual-android') }
         executable 'python3'
 
         doFirst {
@@ -620,8 +619,8 @@ subprojects {
 
     task reformat(type: Exec, dependsOn: [getCodeFormatScripts, pythonIsInstalled], group: 'Format') {
         description 'Format the Java source code'
-        // checker-qual* projects have no source, so skip
-        onlyIf { !project.name.startsWith('checker-qual') }
+        // checker-qual-android project have no source, so skip
+        onlyIf {!project.name.startsWith('checker-qual-android') }
         executable 'python3'
         doFirst {
             args += "${formatScriptsHome}/run-google-java-format.py"
@@ -650,7 +649,7 @@ subprojects {
         relocate 'plume', 'org.checkerframework.plume'
     }
 
-    if (!project.name.startsWith('checker-qual')) {
+    if (!project.name.startsWith('checker-qual-android')) {
         task tags(type: Exec) {
             description 'Create Emacs TAGS table'
             commandLine "bash", "-c", "find . \\( -name build \\) -prune -o -name '*.java' -print | sort-directory-order | xargs ctags -e -f TAGS"
@@ -668,7 +667,7 @@ subprojects {
         // Adds manifest to all Jar files
         tasks.withType(Jar) {
             includeEmptyDirs = false
-            if (archiveFileName.get().startsWith("checker-qual")) {
+            if (archiveFileName.get().startsWith("checker-qual") || archiveFileName.get().startsWith("checker-util")) {
                 metaInf {
                     from './LICENSE.txt'
                 }
@@ -683,7 +682,7 @@ subprojects {
                 if (! archiveFileName.get().endsWith("source.jar")) {
                     attributes('Automatic-Module-Name': "org.checkerframework." + project.name.replaceAll('-', '.'))
                 }
-                if (archiveFileName.get().startsWith("checker-qual")) {
+                if (archiveFileName.get().startsWith("checker-qual") || archiveFileName.get().startsWith("checker-util")) {
                     attributes("Bundle-License": "MIT")
                 } else {
                     attributes("Bundle-License": "(GPL-2.0-only WITH Classpath-exception-2.0)")

changelog.txt

@@ -2,6 +2,9 @@ Version 3.10.0, February 1, 2021
 
 **User-visible changes:**
 
+Moved utility classes from checker-qual.jar to the new checker-util.jar.
+Also, added `util` to the end of all the packages of the utility classes.
+
 When supplying the `-Ainfer=...` command-line argument, you must also supply `-Awarns`.
 
 Replaced several error message keys:

checker-qual/build.gradle

@@ -26,7 +26,6 @@ final checkerQualPom(publication) {
         name = 'Checker Qual'
         description = 'checker-qual contains annotations (type qualifiers)\n' +
                 'used by the Checker Framework to type-check Java source code.\n' +
-                'It also contains utility classes for programmers to use at run time.\n' +
                 '\n' +
                 'Please see artifact: org.checkerframework:checker'
         licenses {

checker-util/LICENSE.txt

@@ -0,0 +1,22 @@
+Checker Framework utilities
+Copyright 2004-present by the Checker Framework developers
+
+MIT License:
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

checker-util/build.gradle

@@ -0,0 +1,33 @@
+dependencies {
+    implementation project(':checker-qual')
+}
+apply from: rootProject.file("gradle-mvn-push.gradle")
+
+/** Adds information to the publication for uploading to Maven repositories. */
+final checkerUtilPom(publication) {
+    sharedPublicationConfiguration(publication)
+    publication.from components.java
+    publication.pom {
+        name = 'Checker Util'
+        description = 'checker-util contains utility classes for programmers to use at run time.\n' +
+                '\n' +
+                'Please see artifact: org.checkerframework:checker'
+        licenses {
+            license {
+                name = 'The MIT License'
+                url = 'http://opensource.org/licenses/MIT'
+                distribution = 'repo'
+            }
+        }
+    }
+}
+publishing {
+    publications {
+        checkerUtil(MavenPublication) {
+            checkerUtilPom it
+        }
+    }
+}
+signing {
+    sign publishing.publications.checkerUtil
+}

checker-qual/src/main/java/org/checkerframework/checker/formatter/FormatUtil.java → checker-util/src/main/java/org/checkerframework/checker/formatter/util/FormatUtil.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.formatter;
+package org.checkerframework.checker.formatter.util;
 
 import java.util.ArrayList;
 import java.util.HashMap;

checker-qual/src/main/java/org/checkerframework/checker/i18nformatter/I18nFormatUtil.java → checker-util/src/main/java/org/checkerframework/checker/i18nformatter/util/I18nFormatUtil.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.i18nformatter;
+package org.checkerframework.checker.i18nformatter.util;
 
 import java.text.ChoiceFormat;
 import java.text.DecimalFormat;

checker-qual/src/main/java/org/checkerframework/checker/nullness/NullnessUtil.java → checker-util/src/main/java/org/checkerframework/checker/nullness/util/NullnessUtil.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.nullness;
+package org.checkerframework.checker.nullness.util;
 
 import org.checkerframework.checker.nullness.qual.EnsuresNonNull;
 import org.checkerframework.checker.nullness.qual.NonNull;

checker-qual/src/main/java/org/checkerframework/checker/nullness/Opt.java → checker-util/src/main/java/org/checkerframework/checker/nullness/util/Opt.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.nullness;
+package org.checkerframework.checker.nullness.util;
 
 import java.util.NoSuchElementException;
 import java.util.function.Consumer;

checker-qual/src/main/java/org/checkerframework/checker/regex/RegexUtil.java → checker-util/src/main/java/org/checkerframework/checker/regex/util/RegexUtil.java

@@ -1,6 +1,6 @@
 // This class should be kept in sync with org.plumelib.util.RegexUtil in the plume-util project.
 
-package org.checkerframework.checker.regex;
+package org.checkerframework.checker.regex.util;
 
 import java.util.regex.Pattern;
 import java.util.regex.PatternSyntaxException;

checker-qual/src/main/java/org/checkerframework/checker/signedness/SignednessUtil.java → checker-util/src/main/java/org/checkerframework/checker/signedness/util/SignednessUtil.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.signedness;
+package org.checkerframework.checker.signedness.util;
 
 import java.io.IOException;
 import java.io.RandomAccessFile;

checker-qual/src/main/java/org/checkerframework/checker/signedness/SignednessUtilExtra.java → checker-util/src/main/java/org/checkerframework/checker/signedness/util/SignednessUtilExtra.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.signedness;
+package org.checkerframework.checker.signedness.util;
 
 import java.awt.Dimension;
 import java.awt.image.BufferedImage;

checker-qual/src/main/java/org/checkerframework/checker/units/UnitsTools.java → checker-util/src/main/java/org/checkerframework/checker/units/util/UnitsTools.java

@@ -1,4 +1,4 @@
-package org.checkerframework.checker.units;
+package org.checkerframework.checker.units.util;
 
 import org.checkerframework.checker.units.qual.A;
 import org.checkerframework.checker.units.qual.C;

checker/build.gradle

@@ -24,6 +24,7 @@ dependencies {
         exclude group: 'com.google.errorprone', module: 'javac'
     }
     implementation project(':checker-qual')
+    implementation project(':checker-util')
     // As of 2019-12-16, the version of reflection-util in the Annotation
     // File Utilities takes priority over this version, in the fat jar
     // file. :-( So update it and re-build it locally when updating this.
@@ -74,6 +75,15 @@ task copyJarsToDist(dependsOn: shadowJar, group: 'Build') {
             }
         }
 
+        copy {
+            from file(project(':checker-util').tasks.getByName("jar").archivePath)
+            into "${projectDir}/dist"
+            rename { String fileName ->
+                // remove version number on checker-util.jar
+                fileName.replace(fileName, "checker-util.jar")
+            }
+        }
+
         copy {
             from configurations.javacJar
             into "${projectDir}/dist"

checker/src/main/java/org/checkerframework/checker/formatter/FormatterAnnotatedTypeFactory.java

@@ -11,6 +11,7 @@
 import org.checkerframework.checker.formatter.qual.FormatMethod;
 import org.checkerframework.checker.formatter.qual.InvalidFormat;
 import org.checkerframework.checker.formatter.qual.UnknownFormat;
+import org.checkerframework.checker.formatter.util.FormatUtil;
 import org.checkerframework.checker.signature.qual.CanonicalName;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
 import org.checkerframework.common.basetype.BaseTypeChecker;

checker/src/main/java/org/checkerframework/checker/formatter/FormatterTransfer.java

@@ -3,6 +3,7 @@
 import javax.lang.model.element.AnnotationMirror;
 import org.checkerframework.checker.formatter.FormatterTreeUtil.Result;
 import org.checkerframework.checker.formatter.qual.ConversionCategory;
+import org.checkerframework.checker.formatter.util.FormatUtil;
 import org.checkerframework.dataflow.analysis.RegularTransferResult;
 import org.checkerframework.dataflow.analysis.TransferInput;
 import org.checkerframework.dataflow.analysis.TransferResult;

checker/src/main/java/org/checkerframework/checker/i18nformatter/I18nFormatterAnnotatedTypeFactory.java

@@ -18,6 +18,7 @@
 import org.checkerframework.checker.i18nformatter.qual.I18nFormatFor;
 import org.checkerframework.checker.i18nformatter.qual.I18nInvalidFormat;
 import org.checkerframework.checker.i18nformatter.qual.I18nUnknownFormat;
+import org.checkerframework.checker.i18nformatter.util.I18nFormatUtil;
 import org.checkerframework.checker.signature.qual.CanonicalName;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
 import org.checkerframework.common.basetype.BaseTypeChecker;

checker/src/main/java/org/checkerframework/checker/i18nformatter/I18nFormatterTreeUtil.java

@@ -30,6 +30,7 @@
 import org.checkerframework.checker.i18nformatter.qual.I18nInvalidFormat;
 import org.checkerframework.checker.i18nformatter.qual.I18nMakeFormat;
 import org.checkerframework.checker.i18nformatter.qual.I18nValidFormat;
+import org.checkerframework.checker.i18nformatter.util.I18nFormatUtil;
 import org.checkerframework.checker.signature.qual.BinaryName;
 import org.checkerframework.common.basetype.BaseTypeChecker;
 import org.checkerframework.dataflow.cfg.node.ArrayCreationNode;

checker/src/main/java/org/checkerframework/checker/regex/RegexAnnotatedTypeFactory.java

@@ -21,6 +21,7 @@
 import org.checkerframework.checker.regex.qual.Regex;
 import org.checkerframework.checker.regex.qual.RegexBottom;
 import org.checkerframework.checker.regex.qual.UnknownRegex;
+import org.checkerframework.checker.regex.util.RegexUtil;
 import org.checkerframework.common.basetype.BaseAnnotatedTypeFactory;
 import org.checkerframework.common.basetype.BaseTypeChecker;
 import org.checkerframework.framework.flow.CFAbstractAnalysis;

checker/src/test/java/org/checkerframework/checker/test/junit/FormatterUnitTest.java

@@ -1,6 +1,6 @@
 package org.checkerframework.checker.test.junit;
 
-import org.checkerframework.checker.formatter.FormatUtil;
+import org.checkerframework.checker.formatter.util.FormatUtil;
 import org.junit.Assert;
 import org.junit.Test;
 

checker/src/test/java/org/checkerframework/checker/test/junit/I18nFormatterUnitTest.java

@@ -1,7 +1,7 @@
 package org.checkerframework.checker.test.junit;
 
-import org.checkerframework.checker.i18nformatter.I18nFormatUtil;
 import org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory;
+import org.checkerframework.checker.i18nformatter.util.I18nFormatUtil;
 import org.junit.Assert;
 import org.junit.Test;
 

docs/examples/units-extension/UnitsExtensionDemo.java

@@ -1,6 +1,6 @@
-import org.checkerframework.checker.units.UnitsTools;
 import org.checkerframework.checker.units.qual.Prefix;
 import org.checkerframework.checker.units.qual.s;
+import org.checkerframework.checker.units.util.UnitsTools;
 import qual.Frequency;
 import qual.Hz;
 import qual.kHz;

docs/manual/creating-a-checker.tex

@@ -1286,7 +1286,7 @@
 \end{enumerate}
 
 The Regex Checker's dataflow customization for the
-\refmethod{checker/regex}{RegexUtil}{asRegex}{-java.lang.String-}
+\refmethod{checker/regex/util}{RegexUtil}{asRegex}{-java.lang.String-}
 run-time check is used as a running example.
 
 If needed, you can find more details about the implementation of

docs/manual/external-tools.tex

@@ -518,6 +518,7 @@
 \begin{itemize}
 \item \<javac.jar>: \url{https://search.maven.org/artifact/com.google.errorprone/javac/9%2B181-r4173-1/jar}
 \item \<checker-qual.jar>: \url{https://search.maven.org/artifact/org.checkerframework/checker-qual/3.9.1/jar}
+\item \<checker-util.jar> (optional): \url{https://search.maven.org/artifact/org.checkerframework/checker-util/3.9.1/jar}
 \item \<checker.jar>: \url{https://search.maven.org/artifact/org.checkerframework/checker/3.9.1/jar}
 \end{itemize}
 

docs/manual/faq.tex

@@ -663,7 +663,7 @@
 Some checkers have library methods that you can explicitly insert in your
 source code.
 Examples include the Nullness Checker's
-\refmethod{checker/nullness}{NullnessUtil}{castNonNull}{-T-} method (see
+\refmethod{checker/nullness/util}{NullnessUtil}{castNonNull}{-T-} method (see
 Section~\ref{suppressing-warnings-with-assertions}) and the Regex Checker's
 \<RegexUtil> class (see Section~\ref{regexutil-methods}).
 But, it would be better to have more general support that does not require

docs/manual/formatter-checker.tex

@@ -542,7 +542,7 @@
 obtained from an external resource, then the string must be trusted or tested.
 
 One way to test a string is to call the
-\refmethod{checker/formatter}{FormatUtil}{asFormat}{-java.lang.String-org.checkerframework.checker.formatter.qual.ConversionCategory...-}
+\refmethod{checker/formatter/util}{FormatUtil}{asFormat}{-java.lang.String-org.checkerframework.checker.formatter.qual.ConversionCategory...-}
 method to check whether the format string is valid and its format
 specifiers match certain conversion categories.
 If this is not the case, \<asFormat> raises an exception.  Your code should
@@ -581,7 +581,7 @@
 \end{Verbatim}
 
 \noindent
-To use the \<FormatUtil> class, the \<checker-qual.jar> file
+To use the \<FormatUtil> class, the \<checker-util.jar> file
 must be on the classpath at run time.
 
 %  LocalWords:  printf InvalidFormat Formatter FormatBottom specifier's

docs/manual/i18n-format-checker.tex

@@ -364,12 +364,12 @@
 \sectionAndLabel{Testing whether a string has an i18n format type}{i18n-format-testing}
 
 In the case that the checker cannot infer the i18n format type of a string,
-you can use the \refmethod{checker/i18nformatter}{I18nFormatUtil}{hasFormat}{-java.lang.String-org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory...-}
+you can use the \refmethod{checker/i18nformatter/util}{I18nFormatUtil}{hasFormat}{-java.lang.String-org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory...-}
 method to define the type of the string in the scope of a conditional statement.
 
 \begin{description}
 
-\item[\refmethod{checker/i18nformatter}{I18nFormatUtil}{hasFormat}{-java.lang.String-org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory...-}]
+\item[\refmethod{checker/i18nformatter/util}{I18nFormatUtil}{hasFormat}{-java.lang.String-org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory...-}]
   returns \<true> if the given string has the given i18n format type.
 
 \end{description}
@@ -389,7 +389,7 @@
       MessageFormat.format(value, "Text", new Date());
 \end{Verbatim}
   \item Using the
-    \refmethod{checker/i18nformatter}{I18nFormatUtil}{hasFormat}{-java.lang.String-org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory...-}
+    \refmethod{checker/util/i18nformatter}{I18nFormatUtil}{hasFormat}{-java.lang.String-org.checkerframework.checker.i18nformatter.qual.I18nConversionCategory...-}
     method to check whether a format
     string has particular conversion categories.
 \begin{Verbatim}

docs/manual/nullness-checker.tex

@@ -649,7 +649,7 @@
 If you need to suppress a warning within an expression, then
 sometimes writing an assertion is not convenient.  In such a case,
 you can suppress warnings by writing a call to the
-\refmethod{checker/nullness}{NullnessUtil}{castNonNull}{-T-} method.
+\refmethod{checker/nullness/util}{NullnessUtil}{castNonNull}{-T-} method.
 The rest of this section discusses the \<castNonNull> method.
 
 The Nullness Checker considers both the return value, and also the
@@ -675,7 +675,7 @@
   the argument is \<null>.  However, it is not intended for general defensive
   programming; see Section~\ref{defensive-programming}.
 
-  To use the \<castNonNull> method, the \<checker-qual.jar> file
+  To use the \<castNonNull> method, the \<checker-util.jar> file
   must be on the classpath at run time.
 
 \begin{sloppypar}