Feature: Add save-to-string primitive

Author: LaCuneta

README.md

@@ -208,6 +208,7 @@ There may be rare occasions in which you don't want the NW extension to remember
 [`nw:load`](#nwload)
 [`nw:load-from-string`](#nwload-from-string)
 [`nw:save`](#nwsave)
+[`nw:save-to-string`](#nwsave-to-string)
 
 ### Centrality Measures
 
@@ -1398,6 +1399,35 @@ Limitations:
 
 
 
+### `nw:save-to-string`
+
+```NetLogo
+nw:save-to-string format
+```
+
+
+Serialize the current network context to a string in the given format and report it, rather than writing to a file. This is the counterpart to [`nw:load-from-string`](#nwload-from-string), and is useful in NetLogo Web and other contexts where the result needs to go somewhere other than the file system.
+
+The `format` argument names the format explicitly and takes the same values as `nw:load-from-string`. 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 reporting a string instead of writing to a file, `nw:save-to-string` behaves exactly like the corresponding `nw:save-*` primitive, with the same limitations regarding attributes and multigraphs.
+
+For example, to save a network and hand it off to a browser download in NetLogo Web:
+
+```
+let gml nw:save-to-string "gml"
+```
+
+
+
 ## Building
 
 The extension is written in Scala (version 2.9.2).

documentation.conf

@@ -1202,6 +1202,35 @@ Limitations:
 - Multigraphs are not supported. Thus, two turtles can share at most one link. `nw:save-graphml` does support multigraphs, so use that if turtles can have more than one type of link connecting them.
 
 `nw:save` determines the file-type of the given file based on the extension and calls the corresponding `save-*` primitive on it. Note that GraphML must be exported with `nw:save-graphml`.
+"""
+  },
+
+  {
+    name: save-to-string,
+    type: reporter,
+    returns: string,
+    tags: [ io ],
+    arguments: [ {name: format, type: string} ],
+    description: """
+Serialize the current network context to a string in the given format and report it, rather than writing to a file. This is the counterpart to [`nw:load-from-string`](#nwload-from-string), and is useful in NetLogo Web and other contexts where the result needs to go somewhere other than the file system.
+
+The `format` argument names the format explicitly and takes the same values as `nw:load-from-string`. 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 reporting a string instead of writing to a file, `nw:save-to-string` behaves exactly like the corresponding `nw:save-*` primitive, with the same limitations regarding attributes and multigraphs.
+
+For example, to save a network and hand it off to a browser download in NetLogo Web:
+
+```
+let gml nw:save-to-string "gml"
+```
 """
   }
 ]

documentation.yaml

@@ -1287,6 +1287,35 @@ primitives:
   tags:
   - io
   type: command
+- arguments:
+  - name: format
+    type: string
+  description: |2
+
+    Serialize the current network context to a string in the given format and report it, rather than writing to a file. This is the counterpart to [`nw:load-from-string`](#nwload-from-string), and is useful in NetLogo Web and other contexts where the result needs to go somewhere other than the file system.
+
+    The `format` argument names the format explicitly and takes the same values as `nw:load-from-string`. 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 reporting a string instead of writing to a file, `nw:save-to-string` behaves exactly like the corresponding `nw:save-*` primitive, with the same limitations regarding attributes and multigraphs.
+
+    For example, to save a network and hand it off to a browser download in NetLogo Web:
+
+    ```
+    let gml nw:save-to-string "gml"
+    ```
+  name: save-to-string
+  returns: string
+  tags:
+  - io
+  type: reporter
 tableOfContents:
   centrality: Centrality Measures
   clusterer: Clusterer/Community Detection

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

@@ -102,6 +102,7 @@ class NetworkExtension extends api.DefaultClassManager with GraphContextManager
     add("load-vna", new LoadFileType(".vna"))
 
     add("save", new prim.Save(this))
+    add("save-to-string", new prim.SaveToString(this))
     add("save-dl", new SaveFileType(this, ".dl"))
     add("save-gdf", new SaveFileType(this, ".gdf"))
     add("save-gexf", new SaveFileType(this, ".gexf"))

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

@@ -22,6 +22,14 @@ object NetworkExtensionUtil {
   def readerForString(data: String): Reader =
     new InputStreamReader(new ByteArrayInputStream(data.getBytes(StandardCharsets.UTF_8)), StandardCharsets.UTF_8)
 
+  val supportedStringFormats = Seq("dl", "gdf", "gexf", "gml", "graphml", "matrix", "vna")
+
+  def normalizeNetworkFormat(rawFormat: String): String =
+    rawFormat.trim.toLowerCase(Locale.ENGLISH).stripPrefix(".")
+
+  def unsupportedFormatMessage(rawFormat: String): String =
+    s"'$rawFormat' is not a supported network format. Valid formats are: dl, gdf, gexf, gml, graphml, matrix, and vna."
+
   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/GephiExport.scala

@@ -1,6 +1,6 @@
 package org.nlogo.extensions.nw.gephi
 
-import java.io.File
+import java.io.{ File, StringWriter }
 
 import org.nlogo.agent.{ AgentSet, Link, Turtle, World }
 import org.nlogo.api
@@ -10,7 +10,7 @@ import org.nlogo.core.Breed
 import org.gephi.graph.api.{ Column, GraphController }
 import org.gephi.io.exporter.api.ExportController
 import org.gephi.io.exporter.plugin.{ ExporterCSV, ExporterGraphML }
-import org.gephi.io.exporter.spi.Exporter
+import org.gephi.io.exporter.spi.{ CharacterExporter, Exporter }
 import org.gephi.project.api.ProjectController
 import org.gephi.utils.longtask.spi.LongTask
 import org.gephi.utils.progress.ProgressTicket
@@ -30,11 +30,29 @@ object GephiExport {
     save(context, world, file, exportController.getFileExporter(file))
   }
 
-  def save(context: GraphContext, world: World, file: File, exporter: Exporter) = GephiUtils.withNWLoaderContext {
-    implicit val implicitWorld = world;
+  def save(context: GraphContext, world: World, file: File, exporter: Exporter): Unit = GephiUtils.withNWLoaderContext {
+    prepareExport(exporter, file.toString)
+    buildWorkspace(context, world)
+    exportController.exportFile(file, exporter)
+  }
+
+  def saveToString(context: GraphContext, world: World, extension: String): String = GephiUtils.withNWLoaderContext {
+    val exporter = exportController.getExporter(extension)
+    prepareExport(exporter, s"the given $extension string")
+    buildWorkspace(context, world)
+    exporter match {
+      case ce: CharacterExporter =>
+        val writer = new StringWriter
+        exportController.exportWriter(writer, ce)
+        writer.toString
+      case _ =>
+        throw new ExtensionException(s"The $extension format cannot be exported to a string.")
+    }
+  }
 
+  private def prepareExport(exporter: Exporter, sourceName: String): Unit = {
     if (exporter == null) {
-      throw new ExtensionException("Unable to find exporter for " + file)
+      throw new ExtensionException("Unable to find exporter for " + sourceName)
     } else if (exporter.isInstanceOf[ExporterCSV]) {
       throw new ExtensionException("Exporting CSV files is not supported.")
     } else if (exporter.isInstanceOf[ExporterGraphML]) {
@@ -70,6 +88,11 @@ object GephiExport {
         } )
       case _ => // ignore
     }
+  }
+
+  private def buildWorkspace(context: GraphContext, world: World): Unit = {
+    implicit val implicitWorld = world;
+
     val program = world.program
     val projectController = Lookup.getDefault.lookup(classOf[ProjectController])
     projectController.newProject()
@@ -144,7 +167,6 @@ object GephiExport {
       graph.addEdge(edge)
     }
     gephiWorkspace.add(graphModel)
-    exportController.exportFile(file, exporter)
   }
 
   private type JDouble     = java.lang.Double

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

@@ -5,6 +5,8 @@ package org.nlogo.extensions.nw.jung.io
 import java.io.BufferedWriter
 import java.io.FileWriter
 import java.io.PrintWriter
+import java.io.StringWriter
+import java.io.Writer
 
 import org.apache.commons.collections15.Transformer
 import org.nlogo.agent
@@ -15,7 +17,23 @@ import org.nlogo.extensions.nw.NetworkExtensionUtil.{ functionToTransformer, usi
 
 object GraphMLExport {
 
-  def save(graphContext: GraphContext, filename: String) = {
+  def save(graphContext: GraphContext, filename: String): Unit =
+    try {
+      using(new PrintWriter(new BufferedWriter(new FileWriter(filename)))) { writeGraphML(graphContext, _) }
+    } catch {
+      case e: Exception => throw new ExtensionException(e)
+    }
+
+  def saveToString(graphContext: GraphContext): String =
+    try {
+      val writer = new StringWriter
+      writeGraphML(graphContext, writer)
+      writer.toString
+    } catch {
+      case e: Exception => throw new ExtensionException(e)
+    }
+
+  private def writeGraphML(graphContext: GraphContext, writer: Writer): Unit = {
     val world = graphContext.world
 
     val graphMLWriter = new GraphMLWriterWithAttribType[agent.Turtle, agent.Link]
@@ -79,13 +97,7 @@ object GraphMLExport {
       }
     }
 
-    try {
-      using(new PrintWriter(new BufferedWriter(new FileWriter(filename)))) { printWriter =>
-        graphMLWriter.save(graphContext.asJungGraph, printWriter)
-      }
-    } catch {
-      case e: Exception => throw new ExtensionException(e)
-    }
+    graphMLWriter.save(graphContext.asJungGraph, writer)
 
   }
 

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

@@ -2,7 +2,7 @@
 
 package org.nlogo.extensions.nw.jung.io
 
-import java.io.{ BufferedReader, FileNotFoundException, Reader }
+import java.io.{ BufferedReader, FileNotFoundException, Reader, StringWriter, Writer }
 
 import org.nlogo.agent.AgentSet
 import org.nlogo.agent.Link
@@ -19,24 +19,34 @@ import edu.uci.ics.jung.algorithms.matrix.GraphMatrixOperations
 
 object Matrix {
 
-  def save(graph: jung.graph.Graph[Turtle, Link], filename: String): Unit = {
+  def save(graph: jung.graph.Graph[Turtle, Link], filename: String): Unit =
+    try {
+      using(new java.io.FileWriter(filename)) { writeMatrix(graph, _) }
+    } catch {
+      case e: Exception => throw new ExtensionException(e)
+    }
+
+  def saveToString(graph: jung.graph.Graph[Turtle, Link]): String =
+    try {
+      val writer = new StringWriter
+      writeMatrix(graph, writer)
+      writer.toString
+    } catch {
+      case e: Exception => throw new ExtensionException(e)
+    }
+
+  private def writeMatrix(graph: jung.graph.Graph[Turtle, Link], writer: Writer): Unit = {
     /* This is almost a line for line copy of jung.io.MatrixFile.save, the major
      * difference being that it explicitly uses the US locale to make sure entries
      * use the dot decimal separator (see issue #69) */
-    try {
-      using(new java.io.FileWriter(filename)) { writer =>
-        val matrix = GraphMatrixOperations.graphToSparseMatrix(graph, null) // TODO: provide weights
-        for (i <- 0 until matrix.rows) {
-          for (j <- 0 until matrix.columns) {
-            val w = matrix.getQuick(i, j)
-            writer.write("%4.2f".formatLocal(java.util.Locale.US, w))
-            if (j < matrix.columns - 1) writer.write(" ")
-          }
-          writer.write("\n")
-        }
+    val matrix = GraphMatrixOperations.graphToSparseMatrix(graph, null) // TODO: provide weights
+    for (i <- 0 until matrix.rows) {
+      for (j <- 0 until matrix.columns) {
+        val w = matrix.getQuick(i, j)
+        writer.write("%4.2f".formatLocal(java.util.Locale.US, w))
+        if (j < matrix.columns - 1) writer.write(" ")
       }
-    } catch {
-      case e: Exception => throw new ExtensionException(e)
+      writer.write("\n")
     }
   }
 

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

@@ -1,7 +1,6 @@
 package org.nlogo.extensions.nw.prim
 
 import java.io.File
-import java.util.Locale
 
 import org.nlogo.agent.World
 import org.nlogo.api
@@ -11,7 +10,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 }
+import org.nlogo.extensions.nw.jung.io.{ GraphMLExport, GraphMLImport, Matrix }
 
 class Load extends TurtleAskingCommand {
   override def getSyntax = commandSyntax(
@@ -34,22 +33,19 @@ class LoadFromString extends TurtleAskingCommand {
   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 {
+    normalizeNetworkFormat(rawFormat) 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" =>
+      case format @ ("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.")
+        throw new api.ExtensionException(unsupportedFormatMessage(rawFormat))
     }
   }
 }
@@ -87,6 +83,25 @@ class Save(gcp: GraphContextProvider) extends api.Command {
   }
 }
 
+class SaveToString(gcp: GraphContextProvider) extends api.Reporter {
+  override def getSyntax = reporterSyntax(right = List(StringType), ret = StringType)
+  override def report(args: Array[api.Argument], context: api.Context): AnyRef = GephiUtils.withNWLoaderContext {
+    val world        = context.getAgent.world.asInstanceOf[World]
+    val rawFormat    = args(0).getString
+    val graphContext = gcp.getGraphContext(world)
+    normalizeNetworkFormat(rawFormat) match {
+      case "graphml" =>
+        GraphMLExport.saveToString(graphContext)
+      case "matrix" =>
+        Matrix.saveToString(graphContext.asJungGraph)
+      case format @ ("dl" | "gdf" | "gexf" | "gml" | "vna") =>
+        GephiExport.saveToString(graphContext, world, "." + format)
+      case _ =>
+        throw new api.ExtensionException(unsupportedFormatMessage(rawFormat))
+    }
+  }
+}
+
 class SaveFileType(gcp: GraphContextProvider, extension: String) extends api.Command {
   override def getSyntax = commandSyntax(right = List(StringType))
   override def perform(args: Array[api.Argument], context: api.Context) = GephiUtils.withNWLoaderContext {