add get information and docs

gtfierro · gtfierro · commit c22c4ca5e072 · 2025-09-04T13:39:15.000-06:00
diff --git a/README.md b/README.md
@@ -95,6 +95,7 @@ Examples:
 - Discovery: Commands (except `init`) discover an environment by walking up parent directories from the current working directory, looking for `.ontoenv/`.
 - Override: Set `ONTOENV_DIR` to point to a specific environment; if it points at a `.ontoenv` directory the parent of that directory is used as the root.
 - Creation: Only `ontoenv init` creates an environment on disk. Other commands will error if no environment is found.
+- Positional search directories: Only `ontoenv init` accepts positional search directories (LOCATIONS). Other commands ignore trailing positionals.
 - Temporary mode: Pass `--temporary` to run with an in‑memory environment (no `.ontoenv/`).
 
 #### update
@@ -117,6 +118,23 @@ Examples:
   - `ontoenv closure http://example.org/ont/MyOntology --no-rewrite-sh-prefixes`
   - `ontoenv closure http://example.org/ont/MyOntology --keep-owl-imports`
 
+#### get
+
+Retrieve a single ontology graph from the environment and write it to STDOUT or a file in a chosen serialization format.
+
+Examples:
+- `ontoenv get http://example.org/ont/MyOntology` — prints Turtle to STDOUT
+- `ontoenv get http://example.org/ont/MyOntology --format jsonld` — prints JSON‑LD to STDOUT
+- `ontoenv get http://example.org/ont/MyOntology --output my.ttl` — writes Turtle to `my.ttl`
+- Disambiguate when multiple copies share the same IRI (different locations):
+  - `ontoenv get http://example.org/ont/MyOntology --location ./ontologies/MyOntology-1.4.ttl`
+  - `ontoenv get http://example.org/ont/MyOntology -l https://example.org/MyOntology-1.3.ttl`
+
+Notes:
+- Supported formats: `turtle` (default), `ntriples`, `rdfxml`, `jsonld`.
+- `--output` writes to a file; omit to print to STDOUT.
+- `--location` accepts a file path or URL and is only needed to disambiguate when multiple sources exist for the same IRI.
+
 #### Other commands
 
 - `ontoenv dump` — show ontologies, imports, sizes, and metadata
diff --git a/cli/src/main.rs b/cli/src/main.rs
@@ -7,6 +7,7 @@ use ontoenv::ontology::{GraphIdentifier, OntologyLocation};
 use ontoenv::util::write_dataset_to_file;
 use ontoenv::ToUriString;
 use oxigraph::model::NamedNode;
+use oxigraph::io::{RdfFormat, JsonLdProfileSet};
 use serde_json;
 use std::env::current_dir;
 use std::path::PathBuf;
@@ -49,9 +50,6 @@ struct Cli {
     /// Do not search for ontologies in the search directories
     #[clap(long = "no-search", short = 'n', action, global = true)]
     no_search: bool,
-    /// Directories to search for ontologies. If not provided, the current directory is used.
-    #[clap(global = true, last = true)]
-    locations: Option<Vec<PathBuf>>,
 }
 
 #[derive(Debug, Subcommand)]
@@ -108,6 +106,9 @@ enum Commands {
         /// Overwrite the environment if it already exists
         #[clap(long, default_value = "false")]
         overwrite: bool,
+        /// Directories to search for ontologies. If not provided, the current directory is used.
+        #[clap(last = true)]
+        locations: Option<Vec<PathBuf>>,
     },
     /// Prints the version of the ontoenv binary
     Version,
@@ -146,6 +147,20 @@ enum Commands {
         #[clap(long, default_value = "-1")]
         recursion_depth: i32,
     },
+    /// Retrieve a single graph from the environment and write it to STDOUT or a file
+    Get {
+        /// Ontology IRI (name)
+        ontology: String,
+        /// Optional source location (file path or URL) to disambiguate
+        #[clap(long, short = 'l')]
+        location: Option<String>,
+        /// Output file path; if omitted, writes to STDOUT
+        #[clap(long)]
+        output: Option<String>,
+        /// Serialization format: one of [turtle, ntriples, rdfxml, jsonld] (default: turtle)
+        #[clap(long, short = 'f')]
+        format: Option<String>,
+    },
     /// Add an ontology to the environment
     Add {
         /// The location of the ontology to add (file path or URL)
@@ -212,6 +227,7 @@ impl ToString for Commands {
             Commands::Status { .. } => "Status".to_string(),
             Commands::Update { .. } => "Update".to_string(),
             Commands::Closure { .. } => "Closure".to_string(),
+            Commands::Get { .. } => "Get".to_string(),
             Commands::Add { .. } => "Add".to_string(),
             Commands::List { .. } => "List".to_string(),
             Commands::Dump { .. } => "Dump".to_string(),
@@ -406,8 +422,9 @@ fn main() -> Result<()> {
         .temporary(cmd.temporary)
         .no_search(cmd.no_search);
 
-    if let Some(locations) = cmd.locations {
-        builder = builder.locations(locations);
+    // Locations only apply to `init`; other commands ignore positional LOCATIONS
+    if let Commands::Init { locations: Some(locs), .. } = &cmd.command {
+        builder = builder.locations(locs.clone());
     }
     // only set includes if they are provided on the command line, otherwise use builder defaults
     if !cmd.includes.is_empty() {
@@ -469,20 +486,30 @@ fn main() -> Result<()> {
     // create the env object to use in the subcommand.
     // - if temporary is true, create a new env object each time
     // - if temporary is false, load the env from the .ontoenv directory if it exists
+    // Determine if this command needs write access to the store
+    let needs_rw = matches!(
+        cmd.command,
+        Commands::Add { .. } | Commands::Update { .. }
+    );
+
     let env: Option<OntoEnv> = if cmd.temporary {
         // Create a new OntoEnv object in temporary mode
         let e = OntoEnv::init(config.clone(), false)?;
         Some(e)
     } else if cmd.command.to_string() != "Init" && ontoenv_exists {
         // if .ontoenv exists, load it from discovered root
-        Some(OntoEnv::load_from_directory(discovered_root.unwrap(), false)?) // no read-only
+        // Open read-only unless the command requires write access
+        Some(OntoEnv::load_from_directory(
+            discovered_root.unwrap(),
+            !needs_rw,
+        )?)
     } else {
         None
     };
     info!("OntoEnv loaded: {}", env.is_some());
 
     match cmd.command {
-        Commands::Init { overwrite } => {
+        Commands::Init { overwrite, .. } => {
             // if temporary, raise an error
             if cmd.temporary {
                 return Err(anyhow::anyhow!(
@@ -509,6 +536,68 @@ fn main() -> Result<()> {
             // `update` will also save it to the directory.
             let _ = OntoEnv::init(config, overwrite)?;
         }
+        Commands::Get {
+            ontology,
+            location,
+            output,
+            format,
+        } => {
+            let env = require_ontoenv(env)?;
+
+            // If a location is provided, resolve by location. Otherwise resolve by name (IRI).
+            let graph = if let Some(loc) = location {
+                let oloc = if loc.starts_with("http://") || loc.starts_with("https://") {
+                    OntologyLocation::Url(loc)
+                } else {
+                    // Normalize to absolute path
+                    ontoenv::ontology::OntologyLocation::from_str(&loc).unwrap_or_else(|_| OntologyLocation::File(PathBuf::from(loc)))
+                };
+                // Read directly from the specified location to disambiguate
+                oloc.graph()?
+            } else {
+                let iri = NamedNode::new(ontology)
+                    .map_err(|e| anyhow::anyhow!(e.to_string()))?;
+                let graphid = env
+                    .resolve(ResolveTarget::Graph(iri))
+                    .ok_or(anyhow::anyhow!("Ontology not found"))?;
+                env.get_graph(&graphid)?
+            };
+
+            let fmt = match format
+                .as_deref()
+                .unwrap_or("turtle")
+                .to_ascii_lowercase()
+                .as_str()
+            {
+                "turtle" | "ttl" => RdfFormat::Turtle,
+                "ntriples" | "nt" => RdfFormat::NTriples,
+                "rdfxml" | "xml" => RdfFormat::RdfXml,
+                "jsonld" | "json-ld" => RdfFormat::JsonLd { profile: JsonLdProfileSet::default() },
+                other => {
+                    return Err(anyhow::anyhow!(
+                        "Unsupported format '{}'. Use one of: turtle, ntriples, rdfxml, jsonld",
+                        other
+                    ))
+                }
+            };
+
+            if let Some(path) = output {
+                let mut file = std::fs::File::create(path)?;
+                let mut serializer = oxigraph::io::RdfSerializer::from_format(fmt).for_writer(&mut file);
+                for t in graph.iter() {
+                    serializer.serialize_triple(t)?;
+                }
+                serializer.finish()?;
+            } else {
+                let stdout = std::io::stdout();
+                let mut handle = stdout.lock();
+                let mut serializer = oxigraph::io::RdfSerializer::from_format(fmt).for_writer(&mut handle);
+                for t in graph.iter() {
+                    serializer.serialize_triple(t)?;
+                }
+                serializer.finish()?;
+            }
+        }
         Commands::Version => {
             println!(
                 "ontoenv {} @ {}",
diff --git a/cli/tests/cli_integration.rs b/cli/tests/cli_integration.rs
@@ -133,3 +133,111 @@ fn why_lists_importers_paths() {
     assert!(stdout.contains(&format!("{} -> {} -> {}", c_uri, a_uri, b_uri)));
 }
 
+// Get command: default Turtle to STDOUT by IRI
+#[test]
+fn get_stdout_turtle() {
+    let exe = ontoenv_bin();
+    let root = tmp_dir("get_turtle");
+    let iri = "http://example.org/ont/Only";
+    let path = root.join("only.ttl");
+    write_ttl(&path, iri, "");
+
+    // init
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("init")
+        .output()
+        .expect("run init");
+    assert!(out.status.success(), "init failed: {}", String::from_utf8_lossy(&out.stderr));
+
+    // get to stdout
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("get")
+        .arg(iri)
+        .output()
+        .expect("run get");
+    assert!(out.status.success(), "get failed: {}", String::from_utf8_lossy(&out.stderr));
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    // Expect to see the ontology triple in some form
+    assert!(stdout.contains(iri), "stdout did not contain IRI: {}", stdout);
+}
+
+// Get command: JSON-LD output
+#[test]
+fn get_jsonld_output() {
+    let exe = ontoenv_bin();
+    let root = tmp_dir("get_jsonld");
+    let iri = "http://example.org/ont/JL";
+    let path = root.join("jl.ttl");
+    write_ttl(&path, iri, "");
+
+    // init
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("init")
+        .output()
+        .expect("run init");
+    assert!(out.status.success());
+
+    // get jsonld to stdout
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("get")
+        .arg(iri)
+        .arg("--format")
+        .arg("jsonld")
+        .output()
+        .expect("run get jsonld");
+    assert!(out.status.success(), "get jsonld failed: {}", String::from_utf8_lossy(&out.stderr));
+    let stdout = String::from_utf8_lossy(&out.stdout);
+    assert!(stdout.contains(iri), "jsonld output missing iri; got: {}", stdout);
+    assert!(stdout.trim_start().starts_with("{") || stdout.trim_start().starts_with("["), "not JSON-LD? {}", stdout);
+}
+
+// Get command: disambiguate with --location when same IRI at two locations
+#[test]
+fn get_with_location_disambiguates() {
+    let exe = ontoenv_bin();
+    let root = tmp_dir("get_loc");
+    let iri = "http://example.org/ont/Dup";
+    let p1 = root.join("dup_v1.ttl");
+    let p2 = root.join("dup_v2.ttl");
+    // add distinguishing triples
+    write_ttl(&p1, iri, "<http://example.org/x> <http://example.org/p> \"v1\" .");
+    write_ttl(&p2, iri, "<http://example.org/x> <http://example.org/p> \"v2\" .");
+
+    // init
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("init")
+        .output()
+        .expect("run init");
+    assert!(out.status.success());
+
+    // get with location pointing to v1
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("get")
+        .arg(iri)
+        .arg("--location")
+        .arg(p1.to_str().unwrap())
+        .output()
+        .expect("run get v1");
+    assert!(out.status.success(), "get v1 failed: {}", String::from_utf8_lossy(&out.stderr));
+    let s1 = String::from_utf8_lossy(&out.stdout);
+    assert!(s1.contains("\"v1\""), "expected v1 triple, got: {}", s1);
+
+    // get with location pointing to v2
+    let out = Command::new(&exe)
+        .current_dir(&root)
+        .arg("get")
+        .arg(iri)
+        .arg("-l")
+        .arg(p2.to_str().unwrap())
+        .output()
+        .expect("run get v2");
+    assert!(out.status.success(), "get v2 failed: {}", String::from_utf8_lossy(&out.stderr));
+    let s2 = String::from_utf8_lossy(&out.stdout);
+    assert!(s2.contains("\"v2\""), "expected v2 triple, got: {}", s2);
+}
