Added sound speed profile models

.github/workflows/CI.yml

@@ -23,7 +23,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.11'
+          - '1.11.0-rc2'
         os:
           - ubuntu-latest
           - windows-latest
@@ -49,7 +49,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v2
         with:
-          version: '1.11'
+          version: '1.11.0-rc2'
       - uses: julia-actions/cache@v2
       - name: Configure doc environment
         shell: julia --project=docs --color=yes {0}

Manifest.toml

@@ -2,6 +2,18 @@
 
 julia_version = "1.11.0-rc2"
 manifest_format = "2.0"
-project_hash = "d24e626c29044625dcf8938b35b79cb5121fab5f"
+project_hash = "d0c62af25f1e334dc974e47fa84a9579455bd7a6"
 
-[deps]
+[[deps.Base64]]
+uuid = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
+version = "1.11.0"
+
+[[deps.InteractiveUtils]]
+deps = ["Markdown"]
+uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+version = "1.11.0"
+
+[[deps.Markdown]]
+deps = ["Base64"]
+uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
+version = "1.11.0"

Project.toml

@@ -3,5 +3,9 @@ uuid = "03019ade-4524-4ecd-af79-46d4f04a1b56"
 authors = ["Aaron Kaw <[email protected]> and contributors"]
 version = "1.0.0-DEV"
 
+[deps]
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+
 [compat]
+InteractiveUtils = "1.11.0"
 julia = "1.10"

docs/Manifest.toml

@@ -172,6 +172,7 @@ uuid = "ca575930-c2e3-43a9-ace4-1e988b2c1908"
 version = "1.2.0"
 
 [[deps.OceanSonar]]
+deps = ["AbstractTrees", "InteractiveUtils"]
 path = "C:\\Users\\Aaron\\.julia\\dev\\OceanSonar"
 uuid = "03019ade-4524-4ecd-af79-46d4f04a1b56"
 version = "1.0.0-DEV"

docs/make.jl

@@ -1,33 +1,39 @@
 using OceanSonar
 using Documenter
-
-sidebar_title(path::String) = if isdir(path)
-    basename(path)[4:end]
-elseif isfile(path)
-    basename(path)[4:end-3]
-else
-    error("What even is $path?")
-end |> titletext
+using Base.Filesystem: basename, path_separator
 
 src_dir = joinpath(@__DIR__, "src")
 
-function populate_pages(current_path)
-    return if isfile(current_path)
-        current_path[length(src_dir)+2 : end]
-    elseif isdir(current_path)
+hell = 1
+
+function sidebar_title(abs_subpath)
+    abs_subpath
+    filename = basename(abs_subpath)
+    @assert !isempty(filename)
+    first = findfirst(r"[A-Z]|[a-z]", filename)[1]
+    final = contains(filename, ".") ? findlast('.', filename)[1] - 1 : length(filename)
+    return filename[first:final] |> titletext
+end
+
+function populate_pages(abs_path)
+    return if isfile(abs_path)
+        replace(abs_path, src_dir * path_separator => "")
+
+    elseif isdir(abs_path)
         [
-            sidebar_title(subpath) => populate_pages(joinpath(current_path, subpath))
-            for subpath in readdir(current_path, join = true, sort = true)
-            if !contains(subpath, "index.md")
+            sidebar_title(abs_subpath) => populate_pages(abs_subpath)
+            for abs_subpath in readdir(abs_path, join = true, sort = true)
+            if abs_subpath != joinpath(src_dir, "index.md")
         ]
+
     else
-        error("What even is $current_path?")
+        error("Unrecognised path: $abs_path.")
     end
 end
 
-pages=[
+pages = [
     "Home" => "index.md",
-    populate_pages(joinpath(@__DIR__, "src"))...
+    populate_pages(src_dir)...
 ]
 
 DocMeta.setdocmeta!(OceanSonar, :DocTestSetup, :(using OceanSonar); recursive=true)

docs/src/00_new_users.md → docs/src/000_new_users.md

@@ -3,7 +3,7 @@
 "New" could apply to users as some combination of:
 
 ```@contents
-Pages = ["00_new_users.md"]
+Pages = ["000_new_users.md"]
 Depth = 2:2
 ```
 

docs/src/00_preamble/00_introduction.md

@@ -0,0 +1,6 @@
+# Generic Implementations
+
+The many implementations in `OceanSonar`
+depend on implementations not specific to the field of ocean sonar.
+Such generic implementations that are also `export`ed or otherwise `public`
+are documented here under Auxiliary.

docs/src/01_oceanography/00_introduction.md

@@ -0,0 +1,7 @@
+# Sonar Oceanography
+
+The field of sonar oceanography concerns itself with
+properties and characteristics intrinsic to the ocean environment
+as is related to acoustics.
+Of significant influence to ocean acoustics
+are the ocean boundaries --- that is, the atmosphere and seabed.

docs/src/01_oceanography/01_ocean/00_introduction.md

@@ -0,0 +1 @@
+# The Ocean Volume

docs/src/01_oceanography/01_ocean/01_sound_speed.md

@@ -0,0 +1,5 @@
+# Ocean Sound Speed
+
+```@docs
+sound_speed_profile
+```

docs/src/99_postamble/01_implementation.md

@@ -0,0 +1,74 @@
+# Implementation
+
+## Repository Contents
+
+The filesystem for the package code and documentation texts
+are organised in such a way as to be added in
+alphanumeric folder-then-contents order.
+This way, the complicated contents does not have to be
+managed by a plethora of `include` call managements for `src/OceanSonar.jl`,
+or the `pages` keyword for `docs/make.jl`.
+
+## `OceanSonar` Modelling Types
+
+The field of ocean sonar consists of many metrics,
+each of which have many alternative contexts and methods for calculation.
+For simplicity of usage and the avoidance of namespace overpopulation,
+`OceanSonar` implements a collection of types
+that do much of the heavy lifting in the background.
+
+Firstly:
+
+```@docs
+Model
+```
+
+The implementation of `Model` is such that a basic user will never need to be aware of it.
+It is a specialised version of [`Base.Val`](https://docs.julialang.org/en/v1/base/base/#Base.Val) defined specially for this package.
+`Model` cooperates with types defined in `OceanSonar`
+so users can call models by their name in a string or a symbol.
+For example:
+
+```@repl
+using OceanSonar
+import OceanSonar: sound_speed_profile
+sound_speed_profile(::Model{:MyModel}, z) = 1500 + exp(-z^2)
+sound_speed_profile(:MyModel, 1e3)
+sound_speed_profile("My Model", 1e3)
+```
+
+Thus `Model` behaves as both a dispatching tool and a convenience enabler.
+For more advanced users,
+it is also accessible for easily extending `MetricFunction` instances.
+
+To [avoid piracy](https://docs.julialang.org/en/v1/manual/style-guide/#Avoid-type-piracy),
+this convenience behaviour is only defined for subtypes of `OceanSonar.MetricFunction`:
+
+```@docs; canonical = false
+OceanSonar.MetricFunction
+```
+
+All metric functions defined by `@implement_metric_function` are listed in `metric_functions`:
+
+```@docs; canonical = false
+OceanSonar.metric_functions
+```
+
+```@example
+using OceanSonar
+OceanSonar.metric_functions
+```
+
+For each `MetricFunction`, you can view the `Model`s implemented for it
+by running `listmodels`:
+
+```@docs
+listmodels
+```
+
+For each `Model` of a `MetricFunction`, you can view its inputs and parameters
+with `listarguments`:
+
+```@docs
+listarguments
+```

src/00_preamble/01_general/02_textstyles.jl

@@ -2,7 +2,7 @@ export textstyle
 export titletext
 export snaketext
 export pascaltext
-# public keeptokens
+public keeptokens
 
 """
 ```
@@ -78,10 +78,10 @@ end
 """
 ```
 textstyle(
-    newstyle::Union{Symbol, AbstractString},
-    oldtext::AbstractString
+    newstyle :: Union{Symbol, <:AbstractString},
+    oldtext :: Union{Symbol, <:AbstractString, <:Model{M}} where {M}
     ;
-    keeptokens::AbstractVector{<:AbstractString} = OceanSonar.keeptokens
+    keeptokens :: AbstractVector{<:AbstractString} = OceanSonar.keeptokens
 )
 ```
 
@@ -95,8 +95,8 @@ Implemented text styles:
 * `:camel`: As `:pascal` but the very first character of `text` is lowercase.
 * `:Snake`: Underscore-delimited tokens; tokens' first character uppercased except `keeptokens` preserved.
 * `:snake`: Underscore-delimited tokens; tokens' first character lowercased except `keeptokens` preserved.
-* `:Kebab`: Dash-delimited tokens; tokens' first character uppercased except `keeptokens`.
-* `:kebab`: Dash-delimited tokens; tokens' first character lowercased except `keeptokens`.
+* `:Kebab`: Hyphen-delimited tokens; tokens' first character uppercased except `keeptokens`.
+* `:kebab`: Hyphen-delimited tokens; tokens' first character lowercased except `keeptokens`.
 
 Examples of implemented text styles:
 
@@ -193,6 +193,10 @@ function textstyle(::Val{:title}, text::AbstractString; keeptokens = keeptokens)
     return textstyle(Val(:Space), text; keeptokens = keeptokens)
 end
 
+function textstyle(val::Val, text::Union{Symbol, <:AbstractString}; keeptokens = keeptokens)
+    return textstyle(val, text |> String; keeptokens = keeptokens)
+end
+
 """
 ```
 titletext(text) -> ::AbstractString
@@ -205,10 +209,16 @@ Converts the inputted `text` to the named text case style.
 Convenience functions for [`textstyle`](@ref),
 internally calls e.g. `textstyle(:title, text)`.
 """
-function titletext(text) textstyle(Val(:title), text) end
+function titletext(text; keeptokens = keeptokens)
+    return textstyle(Val(:title), text; keeptokens = keeptokens)
+end
 
 @doc (@doc titletext)
-function pascaltext(text) textstyle(Val(:pascal), text) end
+function pascaltext(text; keeptokens = keeptokens)
+    return textstyle(Val(:pascal), text; keeptokens = keeptokens)
+end
 
 @doc (@doc titletext)
-function snaketext(text) textstyle(Val(:snake), text) end
+function snaketext(text; keeptokens = keeptokens)
+    return textstyle(Val(:snake), text; keeptokens = keeptokens)
+end

src/00_preamble/02_modelling/01_naming.jl

@@ -0,0 +1,64 @@
+export Model
+
+"""
+```
+Model(name::AbstractString)
+Model(name::Symbol)
+```
+
+Return `Model{name}()`
+which is used to dispatch functions by model names.
+
+The `name` is stored as a `Symbol` in [`pascaltext`](@ref) style,
+i.e. only alphanumerals.
+"""
+struct Model{M}
+    function Model(model::AbstractString)
+        # check = @. isalphanumeric(model) || ismember(model, OceanSonar.textstyleseps |> values)
+        valids = [
+            isalphanumeric(ch) || ch in values(OceanSonar.textstyleseps)
+            for ch in model
+        ]
+
+        if any(@. !valids)
+            error("Invalid model name: $model. See the documentation of `Model` for more information.")
+        end
+
+        return new{
+            model |> pascaltext |> Symbol
+        }()
+    end
+end
+
+Model(model::Symbol) = Model(model |> string)
+
+Model(model::Model) = model
+
+Model{M}() where {M} = Model(M)
+
+"""
+```
+
+```
+
+Overload of `Core.Symbol` for `OceanSonar.Model` types and instances.
+"""
+Symbol(::Type{Model{M}}) where {M} = M::Symbol
+Symbol(model::Model) = model |> typeof |> Symbol
+
+"""
+```
+```
+
+Overload of `Core.Symbol` for `OceanSonar.Model types and instances`.
+"""
+String(::Type{Model{M}}) where {M} = M |> String
+String(model::Model) = model |> typeof |> String
+
+function textstyle(val::Val, ModelType::Type{Model{M}}; keeptokens = keeptokens) where {M}
+    return textstyle(val, ModelType |> String; keeptokens = keeptokens)
+end
+
+function textstyle(val::Val, model::Model{M}; keeptokens = keeptokens) where {M}
+    return textstyle(val, model |> typeof; keeptokens = keeptokens)
+end