diff --git a/hub/changelog.rst b/hub/changelog.rst index a1fa3633a4..13e0085184 100644 --- a/hub/changelog.rst +++ b/hub/changelog.rst @@ -1,6 +1,12 @@ Changelog ========= +.. _changelog_2025-12-22: + +2025-12-22 +---------- +* Deprecated the :ref:`ni-collapse ` and :ref:`ni-expand ` DTL functions. + .. _changelog_2025-12-18: 2025-12-18 diff --git a/hub/deprecations.rst b/hub/deprecations.rst index e13222ce15..1f740361c9 100644 --- a/hub/deprecations.rst +++ b/hub/deprecations.rst @@ -196,6 +196,129 @@ DTL Functions | +.. _ni_collapse_dtl_function: + +``ni-collapse`` +--------------- + +.. list-table:: + :header-rows: 1 + :widths: 40, 60 + + * - Description + - Examples + + * - | *Arguments:* + | VALUES(value-expression{1}) + | + - | Uses the ``namespaces.default`` service metadata contents to produce a namespaced identifier from URLs. + VALUES that are not URLs are ignored (i.e. it accepts strings and URI parameters). If there is no longest + matching prefix in the ``namespaces.default`` settings, the functions will return a NI that contains the + original input (i.e. the The ``http`` and ``https`` prefixes are implicitly defined). Non-http URIs are not + supported. + NOTE: this function is experimental and is meant to work with the ``global_defaults.symmetric_namespace_collapse`` + service metadata option set to ``true``. + + | + | Given this ``namespaces.default`` mapping in the service metadata: + | + | ``{`` + ``"foo": "http://psi.test.no/",`` + ``"sesam_male": "http://sesam.io/people/male/",`` + ``"sesam_female": "http://sesam.io/people/female/",`` + ``"sesam": "http://sesam.io/people/"`` + ``}`` + | + | The following examples will produce this output: + | + | ``["ni-collapse", "http://psi.test.no/bar"]`` + | + | Returns ``"~:foo:bar"``. + | + | ``["ni-collapse", ["list", "http://psi.test.no/bar", "http://psi.test.no/baz"]]`` + | + | Returns ``["~:foo:bar", "~:foo:baz"]``. + | + | ``["ni-collapse", "http://sesam.io/people/employees"]`` + | + | Returns ``"~:sesam:employees"``. + | + | ``["ni-collapse", "http://sesam.io/people/male/john"]`` + | + | Returns ``"~:sesam_male:john"``. + | + | ``["ni-collapse", "http://sesam.io/people/female/jane"]`` + | + | Returns ``"~:sesam_female:jane"``. + | + | The ``http`` and ``https`` namespaces are implicitly defined, so a URI that doesn't match any prefix will work: + | + | ``["ni-collapse", "http://example.com/path"]`` + | + | Returns ``"~:http://example.com/path"``. + +.. _ni_expand_dtl_function: + +``ni-expand`` +------------- + +.. list-table:: + :header-rows: 1 + :widths: 40, 60 + + * - Description + - Examples + + * - | *Arguments:* + | VALUES(value-expression{1}) + | + - | Uses the ``namespaces.default`` service metadata contents to produce a URL string from a namespaced identifier. + VALUES that are not NIs are ignored. If there is no longest matching prefix in the ``namespaces.default`` + settings, the functions will return a string cast of the NI. + NOTE: this function is experimental and is meant to work with the ``global_defaults.symmetric_namespace_collapse`` + service metadata option set to ``true``. + + | + | Given this ``namespaces.default`` mapping in the service metadata: + | + | ``{`` + ``"foo": "http://psi.test.no/",`` + ``"sesam_male": "http://sesam.io/people/male/",`` + ``"sesam_female": "http://sesam.io/people/female/",`` + ``"sesam": "http://sesam.io/people/"`` + ``}`` + | + | The following examples will produce this output: + | + | ``["ni-expand", "~:foo:bar"]`` + | + | Returns ``http://psi.test.no/bar``. + | + | ``["ni-expand", ["list", "~:foo:bar", "~:foo:baz"]]`` + | + | Returns ``["http://psi.test.no/bar", "http://psi.test.no/baz"]``. + | + | ``["ni-expand", "~:sesam:employees"]`` + | + | Returns ``"http://sesam.io/people/employees"``. + | + | ``["ni-expand", "~:sesam_male:john"]`` + | + | Returns ``"http://sesam.io/people/male/john"``. + | + | ``["ni-expand", "~:sesam_female:jane"]`` + | + | Returns ``"http://sesam.io/people/female/jane"``. + | + | ``["ni-expand", "~:http://example.com/path"]`` + | + | Returns ``"http://example.com/path"``. + | + | ``["ni-expand", "~:unknown:path"]`` + | + | Returns ``"unknown:path"``. + + Sources ======= diff --git a/hub/dtl/dtl-functions-namespaced-identifiers.rst b/hub/dtl/dtl-functions-namespaced-identifiers.rst index f0b5036f4f..affb470e49 100644 --- a/hub/dtl/dtl-functions-namespaced-identifiers.rst +++ b/hub/dtl/dtl-functions-namespaced-identifiers.rst @@ -94,128 +94,6 @@ Namespaced identifiers had already been mapped to the ``unknown`` namespace then the expression would have returned ``"~:unknown:baz"``. -.. _ni_collapse_dtl_function: - -``ni-collapse`` ---------------- - -.. list-table:: - :header-rows: 1 - :widths: 40, 60 - - * - Description - - Examples - - * - | *Arguments:* - | VALUES(value-expression{1}) - | - - | Uses the ``namespaces.default`` service metadata contents to produce a namespaced identifier from URLs. - VALUES that are not URLs are ignored (i.e. it accepts strings and URI parameters). If there is no longest - matching prefix in the ``namespaces.default`` settings, the functions will return a NI that contains the - original input (i.e. the The ``http`` and ``https`` prefixes are implicitly defined). Non-http URIs are not - supported. - NOTE: this function is experimental and is meant to work with the ``global_defaults.symmetric_namespace_collapse`` - service metadata option set to ``true``. - - | - | Given this ``namespaces.default`` mapping in the service metadata: - | - | ``{`` - ``"foo": "http://psi.test.no/",`` - ``"sesam_male": "http://sesam.io/people/male/",`` - ``"sesam_female": "http://sesam.io/people/female/",`` - ``"sesam": "http://sesam.io/people/"`` - ``}`` - | - | The following examples will produce this output: - | - | ``["ni-collapse", "http://psi.test.no/bar"]`` - | - | Returns ``"~:foo:bar"``. - | - | ``["ni-collapse", ["list", "http://psi.test.no/bar", "http://psi.test.no/baz"]]`` - | - | Returns ``["~:foo:bar", "~:foo:baz"]``. - | - | ``["ni-collapse", "http://sesam.io/people/employees"]`` - | - | Returns ``"~:sesam:employees"``. - | - | ``["ni-collapse", "http://sesam.io/people/male/john"]`` - | - | Returns ``"~:sesam_male:john"``. - | - | ``["ni-collapse", "http://sesam.io/people/female/jane"]`` - | - | Returns ``"~:sesam_female:jane"``. - | - | The ``http`` and ``https`` namespaces are implicitly defined, so a URI that doesn't match any prefix will work: - | - | ``["ni-collapse", "http://example.com/path"]`` - | - | Returns ``"~:http://example.com/path"``. - -.. _ni_expand_dtl_function: - -``ni-expand`` -------------- - -.. list-table:: - :header-rows: 1 - :widths: 40, 60 - - * - Description - - Examples - - * - | *Arguments:* - | VALUES(value-expression{1}) - | - - | Uses the ``namespaces.default`` service metadata contents to produce a URL string from a namespaced identifier. - VALUES that are not NIs are ignored. If there is no longest matching prefix in the ``namespaces.default`` - settings, the functions will return a string cast of the NI. - NOTE: this function is experimental and is meant to work with the ``global_defaults.symmetric_namespace_collapse`` - service metadata option set to ``true``. - - | - | Given this ``namespaces.default`` mapping in the service metadata: - | - | ``{`` - ``"foo": "http://psi.test.no/",`` - ``"sesam_male": "http://sesam.io/people/male/",`` - ``"sesam_female": "http://sesam.io/people/female/",`` - ``"sesam": "http://sesam.io/people/"`` - ``}`` - | - | The following examples will produce this output: - | - | ``["ni-expand", "~:foo:bar"]`` - | - | Returns ``http://psi.test.no/bar``. - | - | ``["ni-expand", ["list", "~:foo:bar", "~:foo:baz"]]`` - | - | Returns ``["http://psi.test.no/bar", "http://psi.test.no/baz"]``. - | - | ``["ni-expand", "~:sesam:employees"]`` - | - | Returns ``"http://sesam.io/people/employees"``. - | - | ``["ni-expand", "~:sesam_male:john"]`` - | - | Returns ``"http://sesam.io/people/male/john"``. - | - | ``["ni-expand", "~:sesam_female:jane"]`` - | - | Returns ``"http://sesam.io/people/female/jane"``. - | - | ``["ni-expand", "~:http://example.com/path"]`` - | - | Returns ``"http://example.com/path"``. - | - | ``["ni-expand", "~:unknown:path"]`` - | - | Returns ``"unknown:path"``. - .. _ni_id_dtl_function: ``ni-id`` diff --git a/hub/quick-reference.rst b/hub/quick-reference.rst index 189ca51ca4..b7790c7af2 100644 --- a/hub/quick-reference.rst +++ b/hub/quick-reference.rst @@ -167,7 +167,10 @@ DTL Expression Functions :ref:`now ` * - Dictionaries - - :ref:`dict ` · + - :ref:`apply ` · + :ref:`apply-hops ` · + :ref:`apply-ns ` + :ref:`dict ` · :ref:`has-key ` · :ref:`is-dict ` · :ref:`items ` · @@ -175,9 +178,7 @@ DTL Expression Functions :ref:`keys ` · :ref:`values ` · :ref:`path ` · - :ref:`apply ` · - :ref:`apply-hops ` · - :ref:`apply-ns ` + :ref:`strip-ns ` * - Encryption - :ref:`decrypt ` · @@ -259,8 +260,6 @@ DTL Expression Functions * - Namespaced identifiers - :ref:`is-ni ` · :ref:`ni ` · - :ref:`ni-collapse ` · - :ref:`ni-expand ` · :ref:`ni-id ` · :ref:`ni-ns `