Yet another kwargs: "equals" in savename (#252)

* equals kwarg

* real world examples

* Update docs/src/real_world.md to use backticks

* bump version + changelog

Co-authored-by: George Datseris <[email protected]>

Author: JonasIsensee

CHANGELOG.md

@@ -1,3 +1,5 @@
+# 2.0.3
+* Added a kwarg `equals` to `savename` to extend applicability.
 # 2.0
 ## Breaking
 * DrWatson has moved entirely on using JLD2.jl instead of BSON.jl for saving files, and also suggests the same to its users through the documentation.

Project.toml

@@ -1,7 +1,7 @@
 name = "DrWatson"
 uuid = "634d3b9d-ee7a-5ddf-bec9-22491ea816e1"
 repo = "https://github.com/JuliaDynamics/DrWatson.jl.git"
-version = "2.0.2"
+version = "2.0.3"
 
 [deps]
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"

docs/src/real_world.md

@@ -465,3 +465,52 @@ end
 
 special_list = [largestthree,]
 ```
+
+### Using `savename` to produce logfiles
+
+When your code runs for a long time or even runs on different machines such as a cluster
+environment it becomes important to produce logfiles. Logfiles allow you to
+view the progress of your program while it is still running, or check later
+on if everything went according to plan.
+
+```julia
+using Dates
+
+function logmessage(n, error)
+    # current time
+    time = Dates.format(now(UTC), dateformat"yyyy-mm-dd HH:MM:SS")
+
+    # memory the process is using 
+    maxrss = "$(round(Sys.maxrss()/1048576, digits=2)) MiB"
+
+    logdata = (; 
+        n, # iteration n
+        error, # some super important progress update
+        maxrss) # lastly the amount of memory being used
+
+    println(savename(time, logdata; connector=" | ", equals=" = ", sort=false, digits=2))
+end
+
+function expensive_computation(N)
+
+    for n = 1:N
+        sleep(1) # heavy computation
+        error = rand()/n # some super import progress update
+        logmessage(n, error)
+    end
+
+end
+```
+
+This yields output that is both easy to read *and* machine parseable.
+If you ever end up with too many logfiles to read, there is still `parse_savename` to
+help you.
+ 
+```julia
+julia> expensive_computation(5)
+2021-05-19 19:20:25 | n = 1 | error = 0.65 | maxrss = 326.27 MiB
+2021-05-19 19:20:26 | n = 2 | error = 0.48 | maxrss = 326.27 MiB
+2021-05-19 19:20:27 | n = 3 | error = 0.08 | maxrss = 326.27 MiB
+2021-05-19 19:20:28 | n = 4 | error = 0.11 | maxrss = 326.27 MiB
+2021-05-19 19:20:29 | n = 5 | error = 0.15 | maxrss = 326.27 MiB
+```

src/naming.jl

@@ -60,6 +60,8 @@ See also [`parse_savename`](@ref) and [`@savename`](@ref).
   called with its default arguments (so customization here is possible only
   by rolling your own container type). Containers leading to empty `savename`
   are skipped.
+* `equals = "="` : Connector between name and value. Can be useful to modify for 
+  adding space `" = "`.
 
 ## Examples
 ```julia
@@ -69,6 +71,7 @@ savename("n", d) == "n_a=0.153_b=5_mode=double"
 savename(d, "n") == "a=0.153_b=5_mode=double.n"
 savename("n", d, "n"; connector = "-") == "n-a=0.153-b=5-mode=double.n"
 savename(d, allowedtypes = (String,)) == "mode=double"
+savename(d, connector=" | ", equals=" = ") == "a = 0.153 | b = 5 | mode = double"
 
 rick = (never = "gonna", give = "you", up = "!");
 savename(rick) == "give=you_never=gonna_up=!" # keys are sorted!
@@ -85,7 +88,7 @@ function savename(prefix::String, c, suffix::String;
                   connector = "_", expand::Vector{String} = default_expand(c),
                   sigdigits::Union{Int,Nothing}=nothing,
                   val_to_string = nothing,
-                  sort = true)
+                  sort = true, equals = "=")
 
     if any(sep in prefix for sep in ['/', '\\'])
         @warn """
@@ -116,11 +119,11 @@ function savename(prefix::String, c, suffix::String;
         if any(x -> (t <: x), allowedtypes)
             if label ∈ expand
                 isempty(val) && continue
-                sname = savename(val; connector=",", digits=digits, sigdigits=sigdigits)
+                sname = savename(val; connector=",", digits=digits, sigdigits=sigdigits, equals = equals)
                 isempty(sname) && continue
-                entry = label*"="*'('*sname*')'
+                entry = label*equals*'('*sname*')'
             else
-                entry = label*"="*val2string(val)
+                entry = label*equals*val2string(val)
             end
             !first && (s *= connector)
             s *= entry

test/naming_tests.jl

@@ -11,6 +11,8 @@ d = (a = 0.153456453, b = 5, mode = "double")
 @test savename("n", d, "n") == "n_a=0.153_b=5_mode=double.n"
 @test savename("n", d, "n"; connector = "-") == "n-a=0.153-b=5-mode=double.n"
 @test savename(d, allowedtypes = (String,)) == "mode=double"
+@test savename(d, connector=" | ", equals=" = ") == "a = 0.153 | b = 5 | mode = double"
+
 tday = today()
 @test savename(@dict(tday)) == "tday=$(string(tday))"