Fixing quickstart example, adding plot

docs/Project.toml

@@ -1,6 +1,10 @@
 [deps]
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 OMJulia = "0f4fe800-344e-11e9-2949-fb537ad918e1"
+PlotlyDocumenter = "9b90f1cd-2639-4507-8b17-2fbe371ceceb"
+PlotlyJS = "f0f68f2c-4968-5e81-91da-67840de0976a"
 
 [compat]
 Documenter = "^0.27"

docs/src/quickstart.md

@@ -2,7 +2,12 @@
 
 ## ModelicaSystem
 
-To simulate Modelica model `BouncingBall`
+To simulate Modelica model `BouncingBall` start a new [`OMJulia.OMCSession`](@ref) and create a
+new [`ModelicaSystem`](@ref) to build the BouncingBall model.
+
+!!! info
+    The BouncingBall.mo file can be found in your OpenModelica installation directory in
+    `<OpenModelcia>/share/doc/omc/testmodels/BouncingBall.mo`
 
 ```modelica
 model BouncingBall
@@ -30,31 +35,39 @@ equation
 end BouncingBall;
 ```
 
-!!! info
-    The BouncingBall.mo file can be found in your OpenModelica installation directory in
-    `<OpenModelcia>/share/doc/omc/testmodels/BouncingBall.mo`
-
-
-start a new [`OMCSession`](@ref) and create a new [`ModelicaSystem`](@ref) to build the
-BouncingBall model.
-
-```@repl
+```@repl ModelicaSystem-example
 using OMJulia
+using CSV, DataFrames, PlotlyJS
+using PlotlyDocumenter # hide
 
 mod = OMJulia.OMCSession()
-omcWorkDoir = mkpath(joinpath("docs", "omc-temp"))  # hide
-mkpath(omcWorkDoir)                                 # hide
-sendExpression(mod, "cd(\"$(omcWorkDoir)\")")       # hide
 ModelicaSystem(mod,
                joinpath("docs", "testmodels", "BouncingBall.mo"),
                "BouncingBall")
+simulate(mod,
+         resultfile = "BouncingBall_ref.csv",
+         simflags   = "-override=outputFormat=csv,stopTime=3")
+
+resultfile = joinpath(getWorkDirectory(mod), "BouncingBall_ref.csv")
+df = DataFrame(CSV.File(resultfile));
+
+plt = plot(df,
+           x=:time, y=:h,
+           mode="lines",
+           Layout(title="Bouncing Ball", height = 700))
+
+sendExpression(mod, "quit()", parsed=false)
+```
+
+```@example ModelicaSystem-example
+PlotlyDocumenter.to_documenter(plt) # hide
 ```
 
 ## Scripting API with sendExpression
 
-Start a new `OMCSession` and send
+Start a new [`OMJulia.OMCSession`](@ref) and send
 [scripting API](https://openmodelica.org/doc/OpenModelicaUsersGuide/latest/scripting_api.html)
-expressions to the omc session with `sendExpression()`.
+expressions to the omc session with [`sendExpression()`](@ref).
 
 ```@repl
 using OMJulia
@@ -66,19 +79,5 @@ mkpath(omcWorkDoir)                                 # hide
 sendExpression(omc, "cd(\"$(omcWorkDoir)\")")       # hide
 sendExpression(omc, "model a Real s; equation s=sin(10*time); end a;")
 sendExpression(omc, "simulate(a)")
-OMJulia.sendExpression(omc, "quit()", parsed=false)
+sendExpression(omc, "quit()", parsed=false)
 ```
-
-!!! info
-    Special characters in string arguments need to be escaped. E.g. `"` becomes `\"`.
-    For example scripting API call
-
-    ```modelica
-    loadFile("/path/to/M.mo")
-    ```
-
-    will translate to
-
-    ```julia
-    sendExpression(omc, "loadFile(\"/path/to/M.mo\")")
-    ```

docs/src/sendExpression.md

@@ -7,3 +7,12 @@ expressions to the omc session with `sendExpression()`.
 ```@docs
 sendExpression
 ```
+
+## Examples
+
+```@repl
+using OMJulia       # hide
+omc = OMCSession()  # hide
+version = OMJulia.sendExpression(omc, "getVersion()")
+sendExpression(omc, "quit()", parsed=false) # hide
+```

src/sendExpression.jl

@@ -34,8 +34,8 @@ See [OpenModelica User's Guide Scripting API](https://openmodelica.org/doc/OpenM
 for a complete list of all functions.
 
 !!! note
-    Special characters in argument `expr` need to be escaped.
-    E.g. `"` becomes `\"`.
+    Some characters in argument `expr` need to be escaped.
+    E.g. `"` becomes `\\"`.
     For example scripting API call
     
     ```modelica
@@ -45,8 +45,31 @@ for a complete list of all functions.
     will translate to
     
     ```julia
-    sendExpression(omc, "loadFile(\"/path/to/M.mo\")")
+    sendExpression(omc, "loadFile(\\"/path/to/M.mo\\")")
     ```
+
+!!! warn
+    On Windows path separation symbol `\\` needs to be escaped and doubled  `\\\\` to
+    prevent warnings.
+
+    ```modelica
+    loadFile("C:\\\\path\\\\to\\\\M.mo")
+    ```
+
+    translate to
+
+    ```julia
+    sendExpression(omc, "loadFile(\\"C:\\\\\\\\path\\\\\\\\to\\\\\\\\M.mo\\")")  # Windows
+    sendExpression(omc, "loadFile(\\"/c/path/to/M.mo\\")")           # Windows
+    ```
+
+## Example
+
+```julia
+using OMJulia
+omc = OMJulia.OMCSession()
+OMJulia.sendExpression(omc, "getVersion()")
+```
 """
 function sendExpression(omc, expr; parsed=true)
   if (process_running(omc.omcprocess))

test/.gitignore

@@ -0,0 +1 @@
+/test-*/

test/Manifest.toml

@@ -0,0 +1,124 @@
+# This file is machine-generated - editing it directly is not advised
+
+julia_version = "1.9.1"
+manifest_format = "2.0"
+project_hash = "9042cdb9122bd0327898aff0f2e2ca16784d4306"
+
+[[deps.ANSIColoredPrinters]]
+git-tree-sha1 = "574baf8110975760d391c710b6341da1afa48d8c"
+uuid = "a4c015fc-c6ff-483c-b24f-f7ea428134e9"
+version = "0.0.1"
+
+[[deps.Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+
+[[deps.Dates]]
+deps = ["Printf"]
+uuid = "ade2ca70-3891-5945-98fb-dc099432e06a"
+
+[[deps.DocStringExtensions]]
+deps = ["LibGit2"]
+git-tree-sha1 = "2fb1e02f2b635d0845df5d7c167fec4dd739b00d"
+uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+version = "0.9.3"
+
+[[deps.Documenter]]
+deps = ["ANSIColoredPrinters", "Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
+git-tree-sha1 = "39fd748a73dce4c05a9655475e437170d8fb1b67"
+uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+version = "0.27.25"
+
+[[deps.IOCapture]]
+deps = ["Logging", "Random"]
+git-tree-sha1 = "d75853a0bdbfb1ac815478bacd89cd27b550ace6"
+uuid = "b5f81e59-6552-4d32-b1f0-c071b021bf89"
+version = "0.2.3"
+
+[[deps.InteractiveUtils]]
+deps = ["Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
+[[deps.JSON]]
+deps = ["Dates", "Mmap", "Parsers", "Unicode"]
+git-tree-sha1 = "31e996f0a15c7b280ba9f76636b3ff9e2ae58c9a"
+uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
+version = "0.21.4"
+
+[[deps.LibGit2]]
+deps = ["Base64", "NetworkOptions", "Printf", "SHA"]
+uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
+
+[[deps.Logging]]
+uuid = "56ddb016-857b-54e1-b83d-db4d58db5568"
+
+[[deps.Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+
+[[deps.Mmap]]
+uuid = "a63ad114-7e13-5084-954f-fe012c677804"
+
+[[deps.NetworkOptions]]
+uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908"
+version = "1.2.0"
+
+[[deps.Parsers]]
+deps = ["Dates", "PrecompileTools", "UUIDs"]
+git-tree-sha1 = "716e24b21538abc91f6205fd1d8363f39b442851"
+uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+version = "2.7.2"
+
+[[deps.PrecompileTools]]
+deps = ["Preferences"]
+git-tree-sha1 = "03b4c25b43cb84cee5c90aa9b5ea0a78fd848d2f"
+uuid = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+version = "1.2.0"
+
+[[deps.Preferences]]
+deps = ["TOML"]
+git-tree-sha1 = "7eb1686b4f04b82f96ed7a4ea5890a4f0c7a09f1"
+uuid = "21216c6a-2e73-6563-6e65-726566657250"
+version = "1.4.0"
+
+[[deps.Printf]]
+deps = ["Unicode"]
+uuid = "de0858da-6303-5e67-8744-51eddeeeb8d7"
+
+[[deps.REPL]]
+deps = ["InteractiveUtils", "Markdown", "Sockets", "Unicode"]
+uuid = "3fa0cd96-eef1-5676-8a61-b3b8758bbffb"
+
+[[deps.Random]]
+deps = ["SHA", "Serialization"]
+uuid = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+
+[[deps.SHA]]
+uuid = "ea8e919c-243c-51af-8825-aaa63cd721ce"
+version = "0.7.0"
+
+[[deps.SafeTestsets]]
+git-tree-sha1 = "81ec49d645af090901120a1542e67ecbbe044db3"
+uuid = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
+version = "0.1.0"
+
+[[deps.Serialization]]
+uuid = "9e88b42a-f829-5b0c-bbe9-9e923198166b"
+
+[[deps.Sockets]]
+uuid = "6462fe0b-24de-5631-8697-dd941f90decc"
+
+[[deps.TOML]]
+deps = ["Dates"]
+uuid = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+version = "1.0.3"
+
+[[deps.Test]]
+deps = ["InteractiveUtils", "Logging", "Random", "Serialization"]
+uuid = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[[deps.UUIDs]]
+deps = ["Random", "SHA"]
+uuid = "cf7118a7-6976-5b1a-9a39-7adc72f591a4"
+
+[[deps.Unicode]]
+uuid = "4ec0a83e-493e-50e2-b9ac-8f72acf5a8f5"

test/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+SafeTestsets = "1bc83da4-3b8d-516f-aca4-4fe02f6d838f"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

test/omcTest.jl

@@ -0,0 +1,62 @@
+#=
+This file is part of OpenModelica.
+Copyright (c) 1998-2023, Open Source Modelica Consortium (OSMC),
+c/o Linköpings universitet, Department of Computer and Information Science,
+SE-58183 Linköping, Sweden.
+
+All rights reserved.
+
+THIS PROGRAM IS PROVIDED UNDER THE TERMS OF THE BSD NEW LICENSE OR THE
+GPL VERSION 3 LICENSE OR THE OSMC PUBLIC LICENSE (OSMC-PL) VERSION 1.2.
+ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS PROGRAM CONSTITUTES
+RECIPIENT'S ACCEPTANCE OF THE OSMC PUBLIC LICENSE OR THE GPL VERSION 3,
+ACCORDING TO RECIPIENTS CHOICE.
+
+The OpenModelica software and the OSMC (Open Source Modelica Consortium)
+Public License (OSMC-PL) are obtained from OSMC, either from the above
+address, from the URLs: http://www.openmodelica.org or
+http://www.ida.liu.se/projects/OpenModelica, and in the OpenModelica
+distribution. GNU version 3 is obtained from:
+http://www.gnu.org/copyleft/gpl.html. The New BSD License is obtained from:
+http://www.opensource.org/licenses/BSD-3-Clause.
+
+This program is distributed WITHOUT ANY WARRANTY; without even the implied
+warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE, EXCEPT AS
+EXPRESSLY SET FORTH IN THE BY RECIPIENT SELECTED SUBSIDIARY LICENSE
+CONDITIONS OF OSMC-PL.
+=#
+
+using Test
+import OMJulia
+
+@testset "OpenModelica" begin
+  @testset "OMCSession" begin
+    olddir = pwd()
+    try
+      workdir = abspath(joinpath(@__DIR__, "test-session"))
+      rm(workdir, recursive=true, force=true)
+      mkpath(workdir)
+      cd(workdir)
+
+      omc = OMJulia.OMCSession()
+      version = OMJulia.sendExpression(omc, "getVersion()")
+      @test startswith(version, "v1.")
+      a = OMJulia.sendExpression(omc, "model a end a;")
+      @test a == [:a]
+
+      classNames = OMJulia.sendExpression(omc, "getClassNames()")
+      @test classNames == [:a]
+      @test true == OMJulia.sendExpression(omc, "loadModel(Modelica)")
+      res = OMJulia.sendExpression(omc, "simulate(Modelica.Electrical.Analog.Examples.CauerLowPassAnalog)")
+      @test isfile(res["resultFile"])
+      @test occursin("The simulation finished successfully.", res["messages"])
+
+      @test 3 == OMJulia.sendExpression(omc, "1+2")
+
+      ret = OMJulia.sendExpression(omc, "quit()", parsed=false)
+      @test ret == "quit requested, shutting server down\n"
+    finally
+      cd(olddir)
+    end
+  end
+end