Add the odk:import command.

Add a new command to manipulate the import declarations within an
ontology, allowing to add or remove declarations as needed.

Author: gouttegd

README.md

@@ -14,7 +14,8 @@ The following commands are provided by the plugin:
 * `odk:subset`: to create ontology subsets;
 * `odk:check-align`: to check the alignment of an ontology against an
   upper-level ontology and/or arbitrary root terms;
-* `odk:normalize`: to “normalise” an ontology.
+* `odk:normalize`: to “normalise” an ontology,
+* `odk:import`: to add/remove import declarations.
 
 Building
 --------

src/main/java/org/incenp/obofoundry/odk/ImportCommand.java

@@ -0,0 +1,74 @@
+/*
+ * ODK ROBOT Plugin
+ * Copyright © 2025 Damien Goutte-Gattat
+ * 
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+package org.incenp.obofoundry.odk;
+
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.Set;
+
+import org.apache.commons.cli.CommandLine;
+import org.obolibrary.robot.CommandLineHelper;
+import org.obolibrary.robot.CommandState;
+import org.semanticweb.owlapi.model.AddImport;
+import org.semanticweb.owlapi.model.IRI;
+import org.semanticweb.owlapi.model.OWLDataFactory;
+import org.semanticweb.owlapi.model.OWLImportsDeclaration;
+import org.semanticweb.owlapi.model.OWLOntology;
+import org.semanticweb.owlapi.model.OWLOntologyChange;
+import org.semanticweb.owlapi.model.RemoveImport;
+
+/**
+ * A command to edit import declarations within an ontology.
+ */
+public class ImportCommand extends BasePlugin {
+
+    public ImportCommand() {
+        super("import", "add/remove import declarations", "robot import [--add IMPORT|--remove IMPORT]");
+
+        options.addOption(null, "add", true, "inject an import declaration");
+        options.addOption(null, "remove", true, "remove an import declaration");
+        options.addOption(null, "exclusive", true,
+                "if true, replace any existing declarations by the ones set by --add");
+    }
+
+    @Override
+    public void performOperation(CommandState state, CommandLine line) throws Exception {
+        OWLOntology ontology = state.getOntology();
+        OWLDataFactory fac = ontology.getOWLOntologyManager().getOWLDataFactory();
+        ArrayList<OWLOntologyChange> changes = new ArrayList<>();
+
+        for ( String imp : CommandLineHelper.getOptionalValues(line, "add") ) {
+            changes.add(new AddImport(ontology, fac.getOWLImportsDeclaration(IRI.create(imp))));
+        }
+        for (String imp : CommandLineHelper.getOptionalValues(line, "remove")) {
+            changes.add(new RemoveImport(ontology, fac.getOWLImportsDeclaration(IRI.create(imp))));
+        }
+
+        if ( CommandLineHelper.getBooleanValue(line, "exclusive", false) ) {
+            Set<String> added = new HashSet<>(CommandLineHelper.getOptionalValues(line, "add"));
+            for ( OWLImportsDeclaration decl : ontology.getImportsDeclarations() ) {
+                if ( !added.contains(decl.getIRI().toString()) ) {
+                    changes.add(new RemoveImport(ontology, decl));
+                }
+            }
+        }
+
+        ontology.getOWLOntologyManager().applyChanges(changes);
+    }
+}

src/main/resources/META-INF/services/org.obolibrary.robot.Command

@@ -1,3 +1,4 @@
 org.incenp.obofoundry.odk.NormalizeCommand
 org.incenp.obofoundry.odk.SubsetCommand
 org.incenp.obofoundry.odk.CheckAlignmentCommand
+org.incenp.obofoundry.odk.ImportCommand

src/site/markdown/import.md

@@ -0,0 +1,64 @@
+Managing import declarations
+============================
+
+The `odk:import` command allows to programmatically add or remove import
+declarations from an ontology.
+
+It is primarily intended for internal use by the ODK itself (which uses
+it when updating an ODK repository).
+
+Adding an import declaration
+----------------------------
+
+Use the `--add <IRI>` option to add an import declaration. Repeat the
+option to add as many declarations as needed:
+
+```
+robot odk:import -i myont-edit.owl \
+                 --add http://purl.obolibrary.org/obo/myont/imports/a_import.owl \
+                 --add http://purl.obolibrary.org/obo/myont/imports/b_import.owl \
+      convert -f ofn -o myont-edit.owl
+```
+
+The option will be ignored if the input file happens to already contain
+a declaration for the same import.
+
+Removing an import declaration
+------------------------------
+
+Conversely, use the `--remove <IRI>` option to remove an import
+declaration. Again, the option may be used repeatedly in the same
+command:
+
+```
+robot odk:import -i myont-edit.obo \
+                 --remove http://purl.obolibrary.org/obo/myont/imports/a_import.owl \
+                 --remove http://purl.obolibrary.org/obo/myont/imports/b_import.owl \
+      convert --check false -o myont-edit.obo
+```
+
+Exclusive mode
+--------------
+
+With the `--exclusive true` option, the command will also _remove_ all
+import declarations that do not correspond to an import IRI added with
+any `--add` option.
+
+Use that option to ensure that an ontology contains import declarations
+for a fixed set of import IRIs _and only for those IRIs_.
+
+For example, the following command:
+
+```
+robot odk:import -i myont-edit.owl \
+                 --add http://purl.obolibrary.org/obo/myont/imports/a_import.owl \
+                 --add http://purl.obolibrary.org/obo/myont/imports/b_import.owl \
+                 --exclusive true \
+      convert -f ofn -o myont-edit.owl
+```
+
+will (1) _add_ the declarations for the `a_import.owl` and
+`b_import.owl` modules, and (2) _remove_ any other declaration.
+
+Use that option without any `--add` option to forcefully remove _all_
+import declarations from the ontology.

src/site/markdown/index.md

@@ -15,7 +15,9 @@ Currently, the ODK ROBOT plugin provides the following commands:
 * [odk:check-align](alignment.html), to check the alignment of an
   ontology against an upper-level ontology and/or arbitrary root terms;
 * [odk:normalize](normalize.html), to perform various normalisation
-  operations on an ontology.
+  operations on an ontology;
+* [odk:import](import.html), to add or remove import declarations in an
+  ontology.
 
 Using with the ODK
 ------------------