Specification of the command line tool for purity and nullability analysis

CmdSpec.md

Specification of the command line tool for purity and nullability analysis

Throughout this document, a ! means that the said option is not implemented yet.

The following specificies the details of the command line interface exposed by the tool. Please note that this is subject to change:

The options:

The following options are planned as of yet:

• ! --class <path/to/classfile.class> : Analyse the class at the specified location. This uses only the standard library, and other installed libraries as the base for the analysis. See below for what installing a library means.

• ! --classpath : The classpath to be used during the analysis. The class can refer to any class in this classpath, and all files containing such classes will be recursively analysed by the tool.

• ! --dir <path/to/directory/> : Analyse all classes (.class files) found within the directory recursively, as above. The dependencies now include all classes in the current directory. (Implementation note: The implementation of this would probably involve installing the library incrementally, in the database. After this operation the files would be uninstalled from the database.)

• ! --install-class </path/to/classfile.class> : Analyses and installs the class to the database. This class file will be in scope for all further analyses, until uninstalled (below)

• ! --install-dir <path/to/directory/> : This will permanently install the analysed .class files in this directory, recursively.

• ! --uninstall-class <package name.classname> : Uninstall the class referred to. The class name should be specified in the package.classname format

• ! --uninstall-package <package name> : Uninstall all class files in the package specified. Note that if all the files in a directory are not in the same package, uninstalling them will take multiple invocations of --uninstall-class. This option does not help. But the specification may change in the future to include an --uninstall-dir. (Implementation note: The main reason why the current spec does not involve the --uninstall-dir is because it would involve a reanalysis of the .class file to determine the package name, and that would require the presence of the class file.)

• ! --db </path/to/database/directory>: Use the following directory as the root of the database of the tool, ignoring the option specified in the config file. The default option, if nothing is specified here or in the config file, is ./<tool name>/db/

The config file

The config file is specified to currently have the following option(s). It will be a json file by the name of .<toolname>.json

• ! db : The path to the default database being used. Please see the option --db above for further details.

Glossary

The following terms used the document have a meaning specific to the tool:

• install: Installing refers to the process in which an analysed class file's analysis result is saved in the database, scoped by <package_name.class_name>, thus enabling the usage of this classfile in the analysis of another .class file which uses this as a dependency. Installing a package refers to the same thing, only applied to the class files in that package, properly scoped.

• database: Database refers to the data stored by the tool, to use in the analysis of other class files.