Parameters: detailed the prototype design sketch (see #1431)

Last week, I resumed the work that had been suspended
due to my focus on this year’s Froscon talk (on `io_uring`).
I have reconsidered my previous design ideas and sought to
arrive at a coherent design. Nevertheless, these are preliminary,
exploratory design studies that should be regarded as a basis
for future work rather....

src/lib/par/disposition.hpp

@@ -0,0 +1,51 @@
+/*
+  DISPOSITION.hpp  -  actual constitution of a parameter descriptor
+
+   Copyright (C)
+     2026             Hermann Vosseler <Ichthyostega@web.de>
+
+  **Lumiera** is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation; either version 2 of the License, or (at your
+  option) any later version. See the file COPYING for further details.
+
+*/
+
+
+/** @file disposition.hpp
+ ** Concrete configuration of a parameter descriptor with type and value provision.
+ ** This is the full definition, with all details spelled out, and what is actually
+ ** stored within the _outer shell_ of a Parameter. The publicly visible interface
+ ** of the latter is implemented by delegating to the constituents of the disposition.
+ ** 
+ ** @todo WIP-WIP-WIP can be considered an initial draft and placeholder, as of 2026
+ */
+
+
+#ifndef LIB_PAR_DISPOSITION_H
+#define LIB_PAR_DISPOSITION_H
+
+
+#include "lib/par/domain.hpp"
+#include "lib/par/provision.hpp"
+
+
+namespace lib {
+namespace par {
+  
+  
+  
+  /**
+   * A complete configuration and setup of a parameter, including a type specification
+   * with domain and scale, and a value provision. Can be generated through a builder
+   * notation and stored within the Parameter object (as a container).
+   */
+  class Disposition
+    {
+    public:
+    };
+  
+  
+  
+}} // namespace lib::par
+#endif /*LIB_PAR_DISPOSITION_H*/

src/lib/par/param-type.cpp

@@ -1,5 +1,5 @@
 /*
-  ParamType  -  parameter scale and type descriptor
+  ParamType  -  parameter type record including domain and scale
 
    Copyright (C)
      2026             Hermann Vosseler <Ichthyostega@web.de>

src/lib/par/param-type.hpp

@@ -1,5 +1,5 @@
 /*
-  PARAM-TYPE.hpp  -  parameter scale and type descriptor
+  PARAM-TYPE.hpp  -  parameter type record including domain and scale
 
    Copyright (C)
      2026             Hermann Vosseler <Ichthyostega@web.de>
@@ -37,7 +37,8 @@ namespace par {
   /**
    * Interface: represent a specific configuration of parameter value type,
    * range and scale. Every ParamType descriptor is also a _prototype_ and has
-   * an unique identity, ensured by registration, so that it acts as a type identifier. 
+   * an unique identity, ensured by registration, so that it acts as a type identifier.
+   * @todo RLY? registration??
    * Furthermore, the interface exposes allowed conversion and conforming operations.
    */
   class ParamType

src/lib/par/parameter.hpp

@@ -13,7 +13,13 @@
 
 
 /** @file parameter.hpp
- ** A generic type value that can be discovered and automated.
+ ** A generic typed value that can be discovered and automated.
+ ** The actual data type of the parameter is an opaque implementation detail,
+ ** yet value ranges and conversions are handled automatically. It is thus
+ ** both a descriptor and an opaque container. Parameter elements can be copied,
+ ** yet the presence of some specific parameter at a given point in the model
+ ** constitutes an identity -- and the parameter descriptor can be tagged
+ ** with that identity.
  ** 
  ** @todo this is a draft and placeholder, as of 2026
  */

src/lib/par/provision.hpp

@@ -0,0 +1,53 @@
+/*
+  PROVISION.hpp  -  determine how a parameter's value is given
+
+   Copyright (C)
+     2026             Hermann Vosseler <Ichthyostega@web.de>
+
+  **Lumiera** is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation; either version 2 of the License, or (at your
+  option) any later version. See the file COPYING for further details.
+
+*/
+
+
+/** @file provision.hpp
+ ** Provide access to a parameter's value, either directly or by automation.
+ ** Each parameter has a _base value_ and a time-based current value. The latter
+ ** is retrieved by evaluating an automation function.
+ ** 
+ ** @todo WIP-WIP-WIP can be considered an initial draft and placeholder, as of 2026
+ */
+
+
+#ifndef LIB_PAR_PROVISION_H
+#define LIB_PAR_PROVISION_H
+
+
+#include "lib/par/param-type.hpp"
+
+
+namespace lib {
+namespace par {
+  
+  
+  
+  /**
+   * Interface: access to a parameter's value, to adjust or evaluate automation.
+   * Conceptually, the value is decomposed into a _base value_ and possibly a
+   * time-controlled adjustment (automation). The base value can be retrieved
+   * and assigned, while the current time-based value is the result of evaluation.
+   * Any parameter value is associated to a ParamType that defines the underlying
+   * value domain and possibly a scale with range limits and metric constraints.
+   */
+  class Provision
+    {
+    public:
+      virtual ~Provision();  ///< this is an interface
+    };
+  
+  
+  
+}} // namespace lib::par
+#endif /*LIB_PAR_PROVISION_H*/

src/lib/par/scale.hpp

@@ -0,0 +1,54 @@
+/*
+  PARAM-TYPE.hpp  -  value scale to use for parameters
+
+   Copyright (C)
+     2026             Hermann Vosseler <Ichthyostega@web.de>
+
+  **Lumiera** is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation; either version 2 of the License, or (at your
+  option) any later version. See the file COPYING for further details.
+
+*/
+
+
+/** @file scale.hpp
+ ** Specification of the allowed value scale of a parameter, including range and metric.
+ ** The scale descriptor is used as delegate from the ParamType descriptor and maintained
+ ** within a global registry for sake of deduplication. It is expected that a lot of parameters
+ ** will share some common scales, like e.g. percentage values or decibels. The setup of a scale
+ ** may limit the value range, provide hints for the UI representation -- yet may possibly also
+ ** encompass nominal scales that comprise a selection of ID values.
+ ** 
+ ** @todo WIP-WIP-WIP can be considered an initial draft and placeholder, as of 2026
+ */
+
+
+#ifndef LIB_PAR_SCALE_H
+#define LIB_PAR_SCALE_H
+
+
+#include "lib/par/domain.hpp"
+
+
+namespace lib {
+namespace par {
+  
+  
+  
+  /**
+   * Interface: describe the properties of a value scale to use for parameters,
+   * including range limits and metric (linear, logarithmic). The core operation
+   * is to conform a value to this specific scale.
+   * @todo not clear if we want a virtual interface here....?
+   */
+  class Scale
+    {
+    public:
+      virtual ~Scale();  ///< this is an interface
+    };
+  
+  
+  
+}} // namespace lib::par
+#endif /*LIB_PAR_SCALE_H*/

tests/lib/par/parameter-domain-test.cpp

@@ -170,6 +170,15 @@ namespace test{
       
       /** @test base function to access the contents of an opaque buffer
        *        with known type, and convert into another target type.
+       *      - the base interface #Domain represents an opaque type
+       *      - it exposes #TypeHandler interfaces for a fixed selection
+       *        of common elementary #BaseTypes
+       *      - here we use a `BaseDomain<int>` as actual implementation,
+       *        yet knowledge regarding the type `int` is erased and any
+       *        access is based solely on a `Domain&`
+       *      - an opaque source ValBuf is passed explicitly
+       * @remark this covers the value access capability of a
+       *  type handler interface, working on external storage.
        */
       void
       verify_valueAccess()
@@ -204,6 +213,10 @@ namespace test{
       
       /** @test base function to assign a directly given data value
        *        into an opaque buffer with known (yet different) type.
+       * @remark since the type handler interface covers both reading
+       *  and writing, here the roles are reversed here, so that the
+       *  target of the assignment is the opaque buffer, whose actual
+       *  type remains hidden behind the #Domain interface.
        */
       void
       verify_valueSetting()

tests/lib/par/parameter-provision-test.cpp

@@ -0,0 +1,91 @@
+/*
+  ParameterProvision(Test)  -  verify parameter value provision and automation
+
+   Copyright (C)
+     2026,            Hermann Vosseler <Ichthyostega@web.de>
+
+  **Lumiera** is free software; you can redistribute it and/or modify it
+  under the terms of the GNU General Public License as published by the
+  Free Software Foundation; either version 2 of the License, or (at your
+  option) any later version. See the file COPYING for further details.
+
+* *****************************************************************/
+
+/** @file parameter-provision-test.cpp
+ ** unit test \ref ParameterProvision_test
+ */
+
+
+#include "test/run.hpp"
+//#include "test/test-helper.hpp"
+#include "lib/par/parameter.hpp"
+//#include "lib/format-cout.hpp"
+
+//#include <utility>
+//#include <string>
+//#include <vector>
+
+//using std::string;
+//using std::vector;
+//using std::swap;
+
+
+namespace lib {
+namespace par {
+namespace test{
+  
+//  using lumiera::error::LUMIERA_ERROR_LOGIC;
+  
+  namespace {//Test fixture....
+    
+    
+  }//(End)Test fixture
+  
+  
+  
+  
+  
+  
+  
+  
+  
+  /**************************************************************************//**
+   * @test document behaviour of paramter value provision and automation.
+   */
+  class ParameterProvision_test : public Test
+    {
+      
+      virtual void
+      run (Arg)
+        {
+          simpleUsage();
+          verify_Value();
+          verify_Function();
+        }
+      
+      
+      void
+      simpleUsage()
+        {
+        }
+      
+      
+      void
+      verify_Value()
+        {
+        }
+      
+      
+      void
+      verify_Function()
+        {
+        }
+    };
+  
+  
+  /** Register this test class... */
+  LAUNCHER (ParameterProvision_test, "unit lib");
+  
+  
+  
+}}} // namespace lib::par::test