sssom-cli: Add new --cardinality option.

Replace the binary option `--force-cardinality` option with a new option
`--cardinality` that accepts three values:

* REMOVE, to forcefully remove the `mapping_cardinality` slot from the
  result set (default behaviour);
* FORCE, to include freshly computed cardinality values (same behaviour
  as the old `--force-cardinality` option);
* KEEP, to do nothing special with cardinality, just leaving any
  existing value untouched (new behaviour).

Author: gouttegd

cli/src/main/java/org/incenp/obofoundry/sssom/cli/CardinalityOption.java

@@ -0,0 +1,39 @@
+/*
+ * SSSOM-Java - SSSOM library for Java
+ * 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.sssom.cli;
+
+/**
+ * Possible behaviours regarding existing {@code mapping_cardinality} values.
+ */
+public enum CardinalityOption {
+    /**
+     * Remove the {@code mapping_cardinality} slot from the output completely.
+     */
+    REMOVE,
+
+    /**
+     * Leave any existing {@code mapping_cardinality} slot untouched.
+     */
+    KEEP,
+
+    /**
+     * Write freshly computed cardinality values (overwriting any existing value).
+     */
+    FORCE
+}

cli/src/main/java/org/incenp/obofoundry/sssom/cli/SimpleCLI.java

@@ -193,8 +193,17 @@ private static class OutputOptions {
                 description = "Split the set along subject and object prefix names and write the split sets in the specified directory.")
         String splitDirectory;
 
-        @Option(names = { "-c", "--force-cardinality" }, description = "Include mapping cardinality values.")
-        boolean forceCardinality;
+        @Option(names = { "-c", "--force-cardinality" },
+                hidden = true,
+                description = "Include mapping cardinality values.")
+        private void forceCardinality(boolean value) {
+            cardinality = CardinalityOption.FORCE;
+        }
+
+        @Option(names = {"-C", "--cardinality" },
+                paramLabel = "OPT",
+                description = "What to do with mapping cardinality values. Possible options: ${COMPLETION-CANDIDATES}. Default is REMOVE.")
+        CardinalityOption cardinality = CardinalityOption.REMOVE;
 
         @Option(names = "--output-prefix-map",
                 paramLabel = "SRC",
@@ -496,9 +505,9 @@ private File getCatalogFile(String userSpecified, String defaultFile) {
     }
 
     private void postProcess(MappingSet ms) {
-        if ( outputOpts.forceCardinality ) {
+        if ( outputOpts.cardinality == CardinalityOption.FORCE ) {
             new Cardinalizer().fillCardinality(ms.getMappings());
-        } else {
+        } else if ( outputOpts.cardinality == CardinalityOption.REMOVE ) {
             ms.getMappings().forEach(mapping -> mapping.setMappingCardinality(null));
         }
 

cli/src/site/apt/index.apt

@@ -324,11 +324,12 @@ sssom-cli set.sssom.tsv:metadata.yaml
   computed on the fly whenever needed, because pre-computed values found
   in a set may not be reliable (if the composition of the set has
   changed since the values were computed). Use the
-  <<<--force-cardinality>>> option to include the
-  <<<mapping_cardinality>>> slot in the result set. In that case, what
-  will be written will always be the <effective> cardinality for each
-  mapping, computed at the last moment before writing the set (in
-  particular, after any transformation of the set).
+  <<<--cardinality keep>>> option to include the
+  <<<mapping_cardinality>>> slot in the result set, or
+  <<<--cardinality force>>> to not only include the slot, but also
+  compute the <effective> cardinality for each mapping (computed at the
+  last moment before writing the set – in particular, after any
+  transformation of the set).
 
   The result set is always <sorted>, so that the mappings are written in
   a completely deterministic order. Use the <<<--no-sorting>>> option to

cli/src/test/java/org/incenp/obofoundry/sssom/cli/SSSOMCLITest.java

@@ -174,6 +174,16 @@ void testWritingOutCardinality() throws IOException {
         // We merge the three O2C, O2N, and C2N sets to have a range of cardinalities
         TestUtils.runCommand(0, new String[] { "exo2c.sssom.tsv", "exo2n.sssom.tsv", "exc2n.sssom.tsv" },
                 "exall-cardinality.sssom.tsv", new String[] { "--force-cardinality" });
+
+        // Same, but using the new --cardinality option.
+        TestUtils.runCommand(0, new String[] { "exo2c.sssom.tsv", "exo2n.sssom.tsv", "exc2n.sssom.tsv" },
+                "exall-cardinality.sssom.tsv", new String[] { "--cardinality", "force" });
+    }
+
+    @Test
+    void testKeepingCardinalityValues() throws IOException {
+        TestUtils.runCommand(0, new String[] { "exo2c-with-cardinality.sssom.tsv" },
+                "test-keeping-cardinality.sssom.tsv", new String[] { "--cardinality", "keep" });
     }
 
     @Test

cli/src/test/resources/output/test-keeping-cardinality.sssom.tsv

@@ -0,0 +1,19 @@
+#curie_map:
+#  COMENT: https://example.com/entities/
+#  ORGENT: https://example.org/entities/
+#  ORGPID: https://example.org/people/
+#mapping_set_id: https://example.org/sets/exo2c
+#mapping_set_title: O2C set
+#creator_id:
+#  - ORGPID:0000-0000-0001-1234
+#license: https://creativecommons.org/licenses/by/4.0/
+#publication_date: 2023-09-13
+subject_id	subject_label	predicate_id	object_id	object_label	mapping_justification	mapping_cardinality
+ORGENT:0001	alice	skos:closeMatch	COMENT:0011	alpha	semapv:ManualMappingCuration	1:1
+ORGENT:0002	bob	skos:closeMatch	COMENT:0012	beta	semapv:ManualMappingCuration	1:1
+ORGENT:0004	daphne	skos:closeMatch	COMENT:0014	delta	semapv:ManualMappingCuration	1:1
+ORGENT:0005	eve	skos:closeMatch	COMENT:0015	epsilon	semapv:ManualMappingCuration	1:1
+ORGENT:0006	fanny	skos:closeMatch	COMENT:0016	zeta	semapv:ManualMappingCuration	1:1
+ORGENT:0007	gavin	skos:exactMatch	COMENT:0013	gamma	semapv:ManualMappingCuration	1:1
+ORGENT:0008	hector	skos:closeMatch	COMENT:0017	eta	semapv:ManualMappingCuration	1:1
+ORGENT:0009	ivan	skos:exactMatch	COMENT:0019	iota	semapv:ManualMappingCuration	1:1

cli/src/test/resources/sets/exo2c-with-cardinality.sssom.tsv

@@ -0,0 +1,19 @@
+#curie_map:
+#  COMENT: https://example.com/entities/
+#  ORGENT: https://example.org/entities/
+#  ORGPID: https://example.org/people/
+#mapping_set_id: https://example.org/sets/exo2c
+#mapping_set_title: O2C set
+#creator_id:
+#  - ORGPID:0000-0000-0001-1234
+#license: https://creativecommons.org/licenses/by/4.0/
+#publication_date: 2023-09-13
+subject_id	subject_label	predicate_id	object_id	object_label	mapping_justification	mapping_cardinality
+ORGENT:0001	alice	skos:closeMatch	COMENT:0011	alpha	semapv:ManualMappingCuration	1:1
+ORGENT:0002	bob	skos:closeMatch	COMENT:0012	beta	semapv:ManualMappingCuration	1:1
+ORGENT:0004	daphne	skos:closeMatch	COMENT:0014	delta	semapv:ManualMappingCuration	1:1
+ORGENT:0005	eve	skos:closeMatch	COMENT:0015	epsilon	semapv:ManualMappingCuration	1:1
+ORGENT:0006	fanny	skos:closeMatch	COMENT:0016	zeta	semapv:ManualMappingCuration	1:1
+ORGENT:0007	gavin	skos:exactMatch	COMENT:0013	gamma	semapv:ManualMappingCuration	1:1
+ORGENT:0008	hector	skos:closeMatch	COMENT:0017	eta	semapv:ManualMappingCuration	1:1
+ORGENT:0009	ivan	skos:exactMatch	COMENT:0019	iota	semapv:ManualMappingCuration	1:1