Feature: Add load-from-string primitive

Author: LaCuneta

README.md

@@ -206,6 +206,7 @@ There may be rare occasions in which you don't want the NW extension to remember
 [`nw:save-graphml`](#nwsave-graphml)
 [`nw:load-graphml`](#nwload-graphml)
 [`nw:load`](#nwload)
+[`nw:load-from-string`](#nwload-from-string)
 [`nw:save`](#nwsave)
 
 ### Centrality Measures
@@ -1337,6 +1338,37 @@ Limitations:
 
 
 
+### `nw:load-from-string`
+
+```NetLogo
+nw:load-from-string format data default-turtle-breed default-link-breed optional-command-block
+```
+
+
+Load `data` from an in-memory string rather than from a file. This is useful in NetLogo Web and other contexts where the data comes from somewhere other than the file system, such as the `fetch` or `resource` extensions.
+
+Because there is no file name to infer the file-type from, the first argument, `format`, names the format explicitly. It is case-insensitive and an optional leading dot is ignored, so `"gml"`, `"GML"`, and `".gml"` are all equivalent. The supported formats are:
+
+- `dl`
+- `gdf`
+- `gexf`
+- `gml`
+- `graphml`
+- `matrix`
+- `vna`
+
+Aside from taking its data from a string and its format from the `format` argument, `nw:load-from-string` behaves exactly like the corresponding `nw:load-*` primitive, including matching node and edge attributes to turtle and link variables and honoring `breed`.
+
+For example, to load a GML network fetched from a URL:
+
+```
+fetch:url-async "https://example.com/network.gml" [ [gml] ->
+  nw:load-from-string "gml" gml turtles links
+] [ [err] -> print err ]
+```
+
+
+
 ### `nw:save`
 
 ```NetLogo

documentation.conf

@@ -1147,6 +1147,36 @@ Limitations:
 """
   },
 
+  {
+    name: load-from-string,
+    type: command,
+    tags: [ io ],
+    arguments: [ {name: format, type: string}, {name: data, type: string}, {name: default-turtle-breed, type: turtleset}, {name: default-link-breed, type: linkset}, {name: optional-command-block, type: "optional command block"} ],
+    description: """
+Load network `data` from an in-memory string rather than from a file. This is useful in NetLogo Web and other contexts where the data comes from somewhere other than the file system, such as the `fetch` or `resource` extensions.
+
+Because there is no file name to infer the file-type from, the first argument, `format`, names the format explicitly. It is case-insensitive and an optional leading dot is ignored, so `"gml"`, `"GML"`, and `".gml"` are all equivalent. The supported formats are:
+
+- `dl`
+- `gdf`
+- `gexf`
+- `gml`
+- `graphml`
+- `matrix`
+- `vna`
+
+Aside from taking its data from a string and its format from the `format` argument, `nw:load-from-string` behaves exactly like the corresponding `nw:load-*` primitive, including matching node and edge attributes to turtle and link variables and honoring `breed`.
+
+For example, to load a GML network fetched from a URL:
+
+```
+fetch:url-async "https://example.com/network.gml" [ [gml] ->
+  nw:load-from-string "gml" gml turtles links
+] [ [err] -> print err ]
+```
+"""
+  },
+
   {
     name: save,
     type: command,

documentation.yaml

@@ -1221,6 +1221,44 @@ primitives:
   tags:
   - io
   type: command
+- arguments:
+  - name: format
+    type: string
+  - name: data
+    type: string
+  - name: default-turtle-breed
+    type: turtleset
+  - name: default-link-breed
+    type: linkset
+  - name: optional-command-block
+    type: optional command block
+  description: |2
+
+    Load network `data` from an in-memory string rather than from a file. This is useful in NetLogo Web and other contexts where the data comes from somewhere other than the file system, such as the `fetch` or `resource` extensions.
+
+    Because there is no file name to infer the file-type from, the first argument, `format`, names the format explicitly. It is case-insensitive and an optional leading dot is ignored, so `"gml"`, `"GML"`, and `".gml"` are all equivalent. The supported formats are:
+
+    - `dl`
+    - `gdf`
+    - `gexf`
+    - `gml`
+    - `graphml`
+    - `matrix`
+    - `vna`
+
+    Aside from taking its data from a string and its format from the `format` argument, `nw:load-from-string` behaves exactly like the corresponding `nw:load-*` primitive, including matching node and edge attributes to turtle and link variables and honoring `breed`.
+
+    For example, to load a GML network fetched from a URL:
+
+    ```
+    fetch:url-async "https://example.com/network.gml" [ [gml] ->
+      nw:load-from-string "gml" gml turtles links
+    ] [ [err] -> print err ]
+    ```
+  name: load-from-string
+  tags:
+  - io
+  type: command
 - arguments:
   - name: file-name
     type: string

src/main/org/nlogo/extensions/nw/NetworkExtension.scala

@@ -94,6 +94,7 @@ class NetworkExtension extends api.DefaultClassManager with GraphContextManager
     add("load-graphml", new LoadGraphML())
 
     add("load", new prim.Load())
+    add("load-from-string", new prim.LoadFromString())
     add("load-dl", new LoadFileType(".dl"))
     add("load-gdf", new LoadFileType(".gdf"))
     add("load-gexf", new LoadFileType(".gexf"))

src/main/org/nlogo/extensions/nw/NetworkExtensionUtil.scala

@@ -9,10 +9,19 @@ import org.nlogo.{agent, api, nvm}
 import org.nlogo.api.MersenneTwisterFast
 import scala.language.implicitConversions
 import scala.reflect.Selectable.reflectiveSelectable
+import java.io.{ ByteArrayInputStream, InputStreamReader, Reader }
+import java.nio.charset.StandardCharsets
 import java.util.Locale
 
 object NetworkExtensionUtil {
 
+  // Wraps an in-memory string in a Reader for feeding to the file importers. We deliberately do NOT use StringReader:
+  // its `ready()` always returns true, even at EOF, whereas the Gephi importers loop on `reader.ready()` and rely on it
+  // going false to stop. Backing the reader with a ByteArrayInputStream gives FileReader-like `ready()` semantics
+  // (false at EOF), so the importers terminate. -Jeremy B July 2026
+  def readerForString(data: String): Reader =
+    new InputStreamReader(new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8)), StandardCharsets.UTF_8)
+
   implicit def functionToTransformer[I, O](f: Function1[I, O]): org.apache.commons.collections15.Transformer[I,O] =
     new org.apache.commons.collections15.Transformer[I, O] {
       override def transform(i: I) = f(i)

src/main/org/nlogo/extensions/nw/gephi/GephiImport.scala

@@ -1,7 +1,7 @@
 package org.nlogo.extensions.nw.gephi
 
 import java.awt.Color
-import java.io.{ File, FileReader, IOException }
+import java.io.{ File, FileReader, IOException, Reader }
 import java.lang.{ Boolean => JBoolean, Double  => JDouble }
 import java.util.Collection
 
@@ -48,10 +48,23 @@ object GephiImport {
     if (!file.exists) {
       throw new ExtensionException("The file " + file + " cannot be found.")
     }
+    load(new FileReader(file), file.toString, world, defaultTurtleBreed, defaultLinkBreed, initTurtles, importer)
+  }
+
+  def loadString(data: String, extension: String, world: World,
+                 defaultTurtleBreed: AgentSet, defaultLinkBreed: AgentSet,
+                 initTurtles: IterableOnce[Turtle] => Unit): Unit = GephiUtils.withNWLoaderContext {
+    load(readerForString(data), s"the given $extension string",
+      world, defaultTurtleBreed, defaultLinkBreed, initTurtles, importController.getFileImporter(extension))
+  }
 
+  def load(reader: => Reader, sourceName: String, world: World,
+           defaultTurtleBreed: AgentSet, defaultLinkBreed: AgentSet,
+           initTurtles: IterableOnce[Turtle] => Unit,
+           importer: FileImporter): Unit = GephiUtils.withNWLoaderContext {
     val isGdfImport = importer match {
       case null =>
-        throw new ExtensionException("Unable to find importer for " + file)
+        throw new ExtensionException("Unable to find importer for " + sourceName)
 
       case _: ImporterSpreadsheetCSV =>
         throw new ExtensionException("Importing CSV files is not supported.")
@@ -70,7 +83,7 @@ object GephiImport {
     val linkBreeds = world.linkBreeds.asScala
 
     val container = try {
-      using(new FileReader(file))(r => importController.importFile(r, importer))
+      using(reader)(r => importController.importFile(r, importer))
     } catch {
       case e: IOException =>
         throw new ExtensionException(e)

src/main/org/nlogo/extensions/nw/jung/io/GraphMLImport.scala

@@ -1,6 +1,6 @@
 package org.nlogo.extensions.nw.jung.io
 
-import java.io.{BufferedReader, FileReader}
+import java.io.{BufferedReader, FileReader, Reader}
 import java.util.Locale
 
 import edu.uci.ics.jung
@@ -133,14 +133,18 @@ object GraphMLImport {
       elem -> agent
     }.toMap
 
-  def load(fileName: String, world: World, rng: MersenneTwisterFast): Iterator[Turtle] = {
+  def load(fileName: String, world: World, rng: MersenneTwisterFast): Iterator[Turtle] =
+    load(new BufferedReader(new FileReader(fileName)), world, rng, world.turtles, world.links)
+
+  def load(reader: => Reader, world: World, rng: MersenneTwisterFast,
+           defaultTurtleBreed: AgentSet, defaultLinkBreed: AgentSet): Iterator[Turtle] = {
     try {
       val graphFactory = sparseGraphFactory[Vertex, Edge]
       val graphTransformer = transformer { (_: GraphMetadata) => graphFactory.create }
 
       using {
         new GraphMLReader2[jung.graph.Graph[Vertex, Edge], Vertex, Edge](
-          new BufferedReader(new FileReader(fileName)),
+          reader,
           graphTransformer,
           transformer(Vertex.apply),
           transformer(Edge.apply),
@@ -160,11 +164,11 @@ object GraphMLImport {
         val vertices = graph.getVertices.asScala.toList.sortBy(_.id)
 
         val turtles: Map[Vertex, Turtle] =
-          createAgents(vertices, keyMap(MetadataType.NODE), world.turtles, world.getBreed) {
+          createAgents(vertices, keyMap(MetadataType.NODE), defaultTurtleBreed, world.getBreed) {
             (_, breed) => createTurtle(world, breed, rng)
           }
 
-        createAgents(graph.getEdges.asScala, keyMap(MetadataType.EDGE), world.links, world.getLinkBreed) {
+        createAgents(graph.getEdges.asScala, keyMap(MetadataType.EDGE), defaultLinkBreed, world.getLinkBreed) {
           (e: Edge, breed) =>
             createLink(turtles, graph.getEndpoints(e), graph.getDefaultEdgeType == EdgeType.DIRECTED, breed, world)
         }

src/main/org/nlogo/extensions/nw/jung/io/Matrix.scala

@@ -2,7 +2,7 @@
 
 package org.nlogo.extensions.nw.jung.io
 
-import java.io.FileNotFoundException
+import java.io.{ BufferedReader, FileNotFoundException, Reader }
 
 import org.nlogo.agent.AgentSet
 import org.nlogo.agent.Link
@@ -40,12 +40,24 @@ object Matrix {
     }
   }
 
-  def load(filename: String, turtleBreed: AgentSet, linkBreed: AgentSet, world: World, rng: MersenneTwisterFast) = {
+  def load(filename: String, turtleBreed: AgentSet, linkBreed: AgentSet, world: World, rng: MersenneTwisterFast): Iterator[Turtle] =
+    load(matrixFile => matrixFile.load(filename), turtleBreed, linkBreed, world, rng)
+
+  def load(reader: Reader, turtleBreed: AgentSet, linkBreed: AgentSet, world: World, rng: MersenneTwisterFast): Iterator[Turtle] = {
+    val buffered = reader match {
+      case b: BufferedReader => b
+      case r                 => new BufferedReader(r)
+    }
+    load(matrixFile => matrixFile.load(buffered), turtleBreed, linkBreed, world, rng)
+  }
+
+  private def load(readGraph: jung.io.MatrixFile[DummyGraph.Vertex, DummyGraph.Edge] => jung.graph.Graph[DummyGraph.Vertex, DummyGraph.Edge],
+                   turtleBreed: AgentSet, linkBreed: AgentSet, world: World, rng: MersenneTwisterFast): Iterator[Turtle] = {
     val matrixFile = new jung.io.MatrixFile(
       null, // TODO: provide weight key (null means 1) (issue #19)
       factoryFor(linkBreed), DummyGraph.vertexFactory, DummyGraph.edgeFactory)
     val graph = try {
-      matrixFile.load(filename)
+      readGraph(matrixFile)
     } catch {
       case e: Exception => e.getCause match {
         case fileNotFound: FileNotFoundException =>

src/main/org/nlogo/extensions/nw/prim/IO.scala

@@ -1,6 +1,7 @@
 package org.nlogo.extensions.nw.prim
 
 import java.io.File
+import java.util.Locale
 
 import org.nlogo.agent.World
 import org.nlogo.api
@@ -10,6 +11,7 @@ import org.nlogo.nvm.ExtensionContext
 import org.nlogo.extensions.nw.GraphContextProvider
 import org.nlogo.extensions.nw.NetworkExtensionUtil._
 import org.nlogo.extensions.nw.gephi.{ GephiExport, GephiImport, GephiUtils }
+import org.nlogo.extensions.nw.jung.io.{ GraphMLImport, Matrix }
 
 class Load extends TurtleAskingCommand {
   override def getSyntax = commandSyntax(
@@ -25,6 +27,33 @@ class Load extends TurtleAskingCommand {
   }
 }
 
+class LoadFromString extends TurtleAskingCommand {
+  override def getSyntax = commandSyntax(
+    right = List(StringType, StringType, TurtlesetType, LinksetType, CommandBlockType | OptionalType),
+    blockAgentClassString = Some("-T--"))
+  override def perform(args: Array[api.Argument], context: api.Context) = GephiUtils.withNWLoaderContext {
+    implicit val world = context.world.asInstanceOf[World]
+    val rawFormat   = args(0).getString
+    val format      = rawFormat.trim.toLowerCase(Locale.ENGLISH).stripPrefix(".")
+    val data        = args(1).getString
+    val turtleBreed = args(2).getAgentSet.requireTurtleBreed
+    val linkBreed   = args(3).getAgentSet.requireLinkBreed
+    val rng         = context.getRNG
+    format match {
+      case "graphml" =>
+        askTurtles(context)(GraphMLImport.load(readerForString(data), world, rng, turtleBreed, linkBreed))
+      case "matrix" =>
+        askTurtles(context)(Matrix.load(readerForString(data), turtleBreed, linkBreed, world, rng))
+      case "dl" | "gdf" | "gexf" | "gml" | "vna" =>
+        GephiImport.loadString(data, "." + format, world, turtleBreed, linkBreed, askTurtles(context))
+      case _ =>
+        throw new api.ExtensionException(
+          s"'$rawFormat' is not a supported network format. Valid formats are: " +
+          "dl, gdf, gexf, gml, graphml, matrix, and vna.")
+    }
+  }
+}
+
 class LoadFileType(extension: String) extends TurtleAskingCommand {
   override def getSyntax = commandSyntax(right = List(StringType, TurtlesetType, LinksetType, CommandBlockType | OptionalType), blockAgentClassString = Some("-T--"))
   override def perform(args: Array[api.Argument], context: api.Context) = GephiUtils.withNWLoaderContext {