module ieee1906-dot1-function {

    yang-version 1.1;

    namespace
      "urn:ieee:std:1906.1:yang:ieee1906-dot1-function";

    prefix ieee1906-dot1-function;

    import ietf-yang-metadata {
      prefix md;
    }

    organization
      "IEEE Std 1906.1-2015 - Recommended Practice for Nanoscale and
Molecular Communication Framework Working Group";

    contact
      "Stephen F. Bush <bushsf@research.ge.com>
Guillaume Mantelet <gmantelet@voltigeurnetworks.com>";

    description
      "This module aims to define YANG as a programming language, making it an embodiment
of an active networking language.

The goal of this YANG function is to use a NETCONF server to remotely execute
mathematic and logic functions. For example, one could imagine an interactive
Python or matlab console exchanging function calls through XML RPCs.

+--------------------+------------+----------------------------------------------+
| name               | type       | description                                  |
+--------------------+------------+----------------------------------------------+
| call               | rpc        | Use to call a function and get a result      |
| dynamic-programming| feature    | This server can program with YANG            |
| dynamic-assignment | feature    | This server can assign to session variables  |
| function           | grouping   | A function to call with its positional args. |
| language           | identity   | The language that is supported by the server |
| name               | annotation | XML attribute to assign to session variables |
| number             | typedef    | String representation of a number            |
| variable-name      | typedef    | String representation of a session variable  |
| variable           | typedef    | Number or unknown defined by a name          |
+--------------------+------------+----------------------------------------------+

An RPC to explicitly call a function on the server is also defined.

Defining the function behavior is out of the scope of this YANG model. This YANG
model only assumes that the functions to be used have consensus among the
community. For example, a sum should be a well known function and the XML RPC
function would look like:

If previous RPC led to the NETCONF server stores a=2 and b=3 for that session,
then:

<call>
  <function>
    <name>sum</name>
    <arg>a</arg>
    <arg>b</arg>
    <arg>1</arg>
  </function>
<call>

And the NETCONF server would return:
<call>
  <result>
    <sum>6</sum>
  </result>
</call>

An annotation provides support for dynamic assignment for the current session, and
provides hints for the NETCONF server. Annotation offering naming means that
'name' can be used as an XML attribute for leaves, functions and containers:
<call>
  <function name='c'>
    <name>sum</name>
    <arg>2</arg>
    <arg>3</arg>
  </function>
<call>

Is a hint so that the NETCONF server returns:
<call>
  <result>
    <c>5</c>
  </result>
</call>

The scope of this call is that the assignment is lost when the result is returned.
However, if 'c' had been previously defined as an assignment for this session, the
function will assign the result to 'c', and 'c' can then be retrieved later. If
<get>
 ...
 <myLeaf>c</myLeaf>  //myLeaf is of type instance-identifier or variableName
 ...
</get>

The NETCONF server would return:
<data>
  ...
  <myLeaf>5</myLeaf>
  ...
</get>
";

    revision "2020-12-07" {
      description "Initial version.";
      reference
        "";

    }

    md:annotation "name" {
      type "variable-name";
      description "This annotation allows assignment to a variable on the NETCONF server. The name
must follow the naming convention (see variableName description). An assignment
is made by defining name as an attribute of the encasing YANG node:

leaf atmospheric-pressure
{
  type si-unit:pressure;
  description  'This is how I represent the pressure in my model';
}

Assignment can be made with the following XML RPC:
<edit-config>
  <atmospheric-pressure math:name='a'>1.01325e5</atmospheric-pressure>
</edit-config>

Is equivalent to say that a = 101,325 Pa

An <rpc-error> message of type bad-attribute should be returned by the NETCONF
server if:
  1. Assignment is performed on a read only attribute (config false)
  2. Assignment is performed on a conflicting operation. For example, assigning
     a value to a leaf where the operation on the container is 'delete'

If the assignment is implicit and no operation can be resolved, then the
variable should be created.
";
    }

    feature dynamic-programming {
      description
        "NETCONF :function capability; If the server advertises the :function capability
for a session, then this feature must also be enabled for that session.
Otherwise, this feature must not be enabled.

When dynamic programming is enabled, the NETCONF server can provide interactive
consoles to the client and can execute sets of functions, and can perform
variable assignment for that session.

When this feature is enabled and advertised, NETCONF should also provide the main
language it supports as a hint for naming variables, equations and functions.
For example, if NETCONF is primarily used to interface a MATLAB simulation,
then :function:matlab should be advertised for the session. The name of the
programming language given as hint should match one of the language identities
provided by this YANG model.

If no programming language is given as a hint or if the client cannot resolve
the language naming conventions, then naming conventions should use the
instance-identifier type instead.

A NETCONF session must not be dropped because the client and the server cannot
agree on a common programming language.";
    }

    feature dynamic-assignment {
      description
        "A NETCONF server capable of dynamic assignment allows a user to access to any
physical or mathematical variable by providing an abstract name, and can
assign values to these abstract names.";
    }

    identity language {
      description
        "Base identity from which all languages are derived.";
    }

    identity programming {
      description
        "Base identity specifying the primary function of the language was for
programming a device.

If you use a language that was primarily for programming, but is now also
considered 'universal', such as Python numpy for example, do not use this base
identity.";
    }

    identity math {
      description
        "Base identity specifying the primary function of the language was for solving
mathematical problems.

If you use a language that was primarily for programming, but is now also
considered 'universal', such as Python numpy for example, do not use this base
identity.";
    }

    identity matlab {
      base language;math;
      description
        "Equation and variable names are written in native MATLAB format.";
    }

    identity mathematica {
      base language;math;
      description
        "Equation and variable names are written in native Mathematica format.";
    }

    identity maple {
      base language;math;
      description
        "Equation and variable names are written in native Maple format.";
    }

    identity octave {
      base language;math;
      description
        "Equation and variable names are written in native Octave format.";
    }

    identity fortran {
      base language;programming;
      description
        "Equation and variable names are written in native Fortran format.";
    }

    identity c {
      base language;programming;
      description
        "Equation and variable names are written in native C or C++ format.";
    }

    identity python {
      base language;programming;
      description
        "Equation and variable names are written in native Python format.";
    }

    identity numpy {
      base language;
      description
        "Equation and variable names are written in Python numpy format.";
    }

    typedef variable-name {
      type union {
        type string {
          pattern
            '[A-Za-z._:][A-Za-z0-9._:]*';
        }
        type instance-identifier;
      }
      description
        "A generic representation of a variable name. This type validates that the string
identifying a variable is correct from the perspective of many languages.

The implementation is expected having a smart looking up table. For example, we
know that python can get any attribute of a target instance or module by calling
the getattr() function, and providing it the string name of this attribute.

The format of the variable representation is outside of the scope of this YANG
model, and can be language dependent. XML XPath representation can be used if
the NETCONF server has the XPath capability to resolve the variable name. If
the implementation is coded in Python, a path with dot can be used to represent
the target instance. For example 'foo.bar' would refer to attribute 'bar' in
instance or module 'foo'.

The type restriction of this name is believed to encompass as many language
conventions as possible, and must not override the string pattern of a number.
Consequently, a valid name must:
  1. Start with an alphabetical character, a dot, a colon, or an underscore
  2. Is followed by any number of alphanumerical character, dots, colons and
     underscore
  3. Prohibit dash and space

It is the XML naming convention, but this restriction allows that the name
starts with 'xml'. For example 'xml12' is a valid variable name (but it is not a
valid xml tag).

When the naming convention cannot be one of the popular languages, then this
type automatically falls back to an instance-identifier, and the name should
correspond to an instance in the data tree, otherwise the NETCONF server will
raise an <rpc-error> message.
";
    }

    typedef number {
      type string {
        pattern
          '[-+]?[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?(\s*[-+]\s*[0-9]*\.?[0-9]+([eE][-+]?[0-9]+)?[ij])?';
      }
      description
        "A generic representation of a number. This type does not make any assumption
about the precision to reach (simple, double etc., decimal32, 64) on the target
computer.

The number format is a string, so the implementation is expected to have parsing
options to convert this value into an appropriate format on the system. For
example, we know that Python is flexible enough to convert such a string into a
float number.

Examples of numbers that can be represented with this type:
-1, 2, 0, +4.5e4, -.5e4, -1.2e-5, 0.34, -5.6e-4 - 16e3j

We want to use this generic representation of a number to express any physical
body without the need for specifying number limit representation (such as
fraction-digit in decimal64 types). This way we can reuse a 'mass' to express
the 'mass of Sun' or a 'mass of a proton' by keeping the same fundamental
unit.

NOTE: For Python users, spaces are allowed in this pattern to make a clear
      distinction between the real and the imaginary parts. complex() does not
      accept -5.6e-4 - 16e3j as valid format, but prefers -5.6e-4-16e3j. Spaces
      need to be replaced first.";
    }

    typedef variable {
      type union {
        type number;
        type variable-name;
      }
      description
        "A variable is a mathematical or physical entity that can be referred to either
as a number for constants, or a name for variables.

This union type helps assign or get values based on numbers or abstract names.
Namespace design needs a special care as name conflict mitigation is outside the
scope of this YANG model. For example, namespace conflict can be solved by using
dots or underscores (see YANG 1.1 instance-reference for XPath resolution).

NOTE: name is an alias, and is not necessarily connected to any variable name on
      implementation. The NETCONF server should store a mapping between variable
      names and the corresponding attributes on the implementation. This is also
      outside the scope of this YANG model.

The NETCONF server should return an <rpc-error> with an error of type
'bad-element' if the variable name cannot be retrieved.";
    }

    grouping function {
      description
        "A reusable function definition.";
      container function {
        description
          "A function is identified by its name and a variable list of positional
arguments. For example, 1 + 2 can be translated into sum(1, 2), and then
becomes an XML RPC of the following format:
<name>sum</name>
<arg>1</arg>
<arg>2</arg>

Order is important because in some mathematical spaces 1 + 2 != 2 + 1.";
        choice name-type {
          description
            "name-type gives the choice to name a function by a generic name or by a
path in a target machine.";
          leaf name {
            type string;
            description
              "The function name if it is a builtin or a well-known function such as sum,
add, divides, langevin etc.";
          }
          leaf id {
            type string;
            description
              "An identifier so that the NETCONF server knows what function to call, if
the user has enough privileges to call this function. For example,
os.path.isfile in Python.";
          }
        }  // choice name-type

        leaf-list arg {
          type variable;
          ordered-by user;
          description
            "A list of positional arguments. The order is important.";
        }
      }  // container function
    }  // grouping function

    rpc call {
      description
        "Calling a target function for this session and getting the returned value.";
      input {
        uses function;
      }

      output {
        anyxml result {
          description
            "The returned value of the function that is called.";
        }
      }
    }  // rpc call
  }  // module ieee1906-dot1-function