From 3984ddde719790bbc5ce371c8e85517ea07977cf Mon Sep 17 00:00:00 2001
From: Xavier Delaruelle <xavier.delaruelle@cea.fr>
Date: Thu, 20 Apr 2023 07:18:34 +0200
Subject: [PATCH] doc: desc. mod spec filtering in EMS spec

---
 .aspell.en.pws                           |  6 ++--
 doc/source/design/extra-match-search.rst | 45 ++++++++++++++++++++++++
 2 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/.aspell.en.pws b/.aspell.en.pws
index 256a23e7..d1d712d0 100644
--- a/.aspell.en.pws
+++ b/.aspell.en.pws
@@ -1,4 +1,4 @@
-personal_ws-1.1 en 895
+personal_ws-1.1 en 897
 ABBRVLIST
 ActiveTcl
 Adrien
@@ -427,7 +427,6 @@ fullname
 func
 funcfoo
 gcc
-getavails
 getAllModuleResolvedName
 getConf
 getDirectDependentList
@@ -445,6 +444,7 @@ getSaveTagList
 getSimplifiedLoadedModuleList
 getState
 getUnmetDependentLoadedModuleList
+getavails
 getcwd
 getdents
 getenv
@@ -563,6 +563,7 @@ mmap
 modEq
 modEqStatic
 modStartNb
+modVariantCmp
 modetype
 modfile
 modquar
@@ -570,6 +571,7 @@ modrc
 modscan
 modshare
 modspec
+moduleVersSpec
 modulecache
 modulecmd
 moduledir
diff --git a/doc/source/design/extra-match-search.rst b/doc/source/design/extra-match-search.rst
index 9e977767..f1af24b1 100644
--- a/doc/source/design/extra-match-search.rst
+++ b/doc/source/design/extra-match-search.rst
@@ -254,6 +254,11 @@ produces internal representation ``{setenv FOO} {variant bar} {setenv BAR}``.
 When *OR* operation will be supported, search query ``mod/1.0 setenv:FOO,BAR``
 will produce internal representation ``{setenv FOO BAR}``.
 
+Value specified may contain a space character if it is escaped on command line
+either by quotes (``"prereq:mod@1.0 foo=bar"``) or backslash
+(``prereq:mod@1.0\ foo=bar``). This is especially useful for complex module
+specification.
+
 Filtering extra specifier results
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -284,6 +289,46 @@ When there are several extra specifiers in search query, result are the
 modules present in the value list of every matched keys (intersection of value
 list obtained for every extra specifier criterion).
 
+Specific filtering work is achieved for extra specifiers accepting a module
+specification. See next section.
+
+Filtering module specification
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some extra specifiers accept a module specification as value. It corresponds
+to all extra specifiers relative to requirements and incompatibilities
+expressed by modulefiles (*prereq*, *conflict*, etc).
+
+Module specification passed as extra specifier value has to be compared to the
+module specification set in the modulefile definition for corresponding
+command.
+
+When parsing such extra specifier value, when evaluating command line
+arguments, module specification is parsed with a specific available module
+resolution: all matching available modules are recorded into module
+specification (``g_moduleVersSpec``). It enables to fetch:
+
+* every module name and version matching a version list or range specification
+* every generic or fully qualified names
+
+Match against modulefile definitions of such extra specifiers is performed in
+the same location than for other extra specifiers. It relies on a ``modEq``
+comparison that has been adapted to also compare alternative names fetched and
+stored into module specification structure. Relying on ``modEq`` procedure,
+comparison leverages *icase* and *extended_default* features.
+
+**LIMITATIONS**: Current module specification match does not support:
+
+* Comparison of module alias or symbolic names when used in either extra
+  specifier value or in modulefile definition
+* Version range or list specified in extra specifier value is converted into
+  a list of existing modulefiles, thus a version in such specification that
+  does not correspond to an existing module will not be matched
+
+Variant value comparison is enabled on ``modEq`` test. ``modVariantCmp``
+internal test has been adapted to let a missing variant definition be
+considered as a match.
+
 Query grammar
 -------------