modfind.tcl.in

##########################################################################

# MODFIND.TCL, available or loaded module find procedures
# Copyright (C) 2002-2004 Mark Lakata
# Copyright (C) 2004-2017 Kent Mein
# Copyright (C) 2016-2026 Xavier Delaruelle
#
# This program 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.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

##########################################################################

# convert environment variable references in string to their values
# every local variable is prefixed by '0' to ensure they will not be
# overwritten through variable reference resolution process
proc resolvStringWithEnv {0str} {
   # fetch variable references in string
   set 0match_list [regexp -all -inline {\$[{]?([A-Za-z_][A-Za-z0-9_]*)[}]?}\
      ${0str}]
   if {[llength ${0match_list}]} {
      # put in local scope every environment variable referred in string
      for {set 0i 1} {${0i} < [llength ${0match_list}]} {incr 0i 2} {
         set 0varname [lindex ${0match_list} ${0i}]
         ##nagelfar vartype 0varname varName
         if {![info exists ${0varname}]} {
            set ${0varname} [get-env ${0varname}]
         }
      }
      # resolve variable reference with values (now in local scope)
      set 0res [subst -nobackslashes -nocommands ${0str}]
   } else {
      set 0res ${0str}
   }

   reportDebug "'${0str}' resolved to '${0res}'"

   return ${0res}
}

# in each string of a list, convert their variable reference into actual value
proc resolvStringListWithEnv {str_list} {
   set res_list {}
   foreach str $str_list {
      lappend res_list [resolvStringWithEnv $str]
   }
   return $res_list
}

# Return first string in list matching given resolved string. Strings in list
# are resolved to help comparison in case they contain an env variable ref.
proc getStringFromListMatchingResString {str_list resolved_str} {
   foreach str $str_list {
      if {$resolved_str eq [resolvStringWithEnv $str]} {
         return $str
      }
   }
}

# deduce modulepath from modulefile and module name
proc getModulepathFromModuleName {modfile modname} {
   return [string range $modfile 0 end-[string length /$modname]]
}

# deduce module name from modulefile and modulepath
proc getModuleNameFromModulepath {modfile modpath} {
   return [string range $modfile [string length $modpath/] end]
}

# check if given modulefile is hosted in one the given modulepaths
proc isModulefileInModulepathList {mod_file modulepath_list} {
   set ret 0
   foreach modulepath $modulepath_list {
      if {[string first $modulepath/ $mod_file] == 0} {
         set ret 1
         break
      }
   }
   return $ret
}

# return list of all enabled modulepaths matching given path
proc getMatchingModulepathList {path} {
   set ret {}
   foreach modulepath [getModulePathList] {
      if {[string first $path/ $modulepath] == 0} {
         lappend ret $modulepath
      }
   }
   return $ret
}

# extract module name from modulefile and currently enabled modulepaths
proc findModuleNameFromModulefile {modfile} {
   set ret {}

   foreach modpath [getModulePathList] {
      if {[string first $modpath/ $modfile/] == 0} {
         set ret [getModuleNameFromModulepath $modfile $modpath]
         break
      }
   }
   return $ret
}

# extract modulepath from modulefile and currently enabled modulepaths
proc findModulepathFromModulefile {modfile} {
   set ret {}

   foreach modpath [getModulePathList] {
      if {[string first $modpath/ $modfile/] == 0} {
         set ret $modpath
         break
      }
   }
   return $ret
}

# Determine with a name provided as argument the corresponding module name,
# version and name/version. Module name is guessed from current module name
# when shorthand version notation is used. Both name and version are guessed
# from current module if name provided is empty. If 'name_relative_tocur' is
# enabled then name argument may be interpreted as a name relative to the
# current modulefile directory (useful for module-version and module-alias
# for instance).
proc getModuleNameVersion {{name {}} {name_relative_tocur 0}} {
   set curmod [currentState modulename]
   set curmodname [file dirname $curmod]
   set curmodversion [file tail $curmod]

   if {$name eq {}} {
      set name $curmodname
      set version $curmodversion
   # check for shorthand version notation like "/version" or "./version"
   # only if we are currently interpreting a modulefile or modulerc
   } elseif {$curmod ne {} && [regexp {^\.?\/(.*)$} $name match version]} {
      # if we cannot distinguish a module name, raise error when shorthand
      # version notation is used
      if {[currentState modulefile] ne $curmod && $curmod ne {.modulerc}} {
         # name is the name of current module directory
         set name $curmodname
      } else {
         reportError "Invalid modulename '$name' found"
         return {}
      }
   } else {
      set name [string trimright $name /]
      set version [file tail $name]
      if {$name eq $version} {
         set version {}
      } else {
         set name [file dirname $name]
      }
      # name may correspond to last part of current module
      # if so name is replaced by current module name
      if {$name_relative_tocur && [file tail $curmodname] eq $name} {
         set name $curmodname
      }
   }

   if {$version eq {}} {
      set mod $name
   } else {
      set mod $name/$version
   }

   return [list $mod $name $version]
}

# Register alias or symbolic version deep resolution in a global array that
# can be used thereafter to get in one query the actual modulefile behind
# a virtual name. Also consolidate a global array that in the same manner
# list all the symbols held by modulefiles.
proc setModuleResolution {mod target {symver {}} {override_res_path 1}\
   {auto_symver 0}} {
   global g_moduleResolved g_resolvedHash g_resolvedPath g_symbolHash

   # find end-point module and register step-by-step path to get to it
   set res $target
   lappend res_path $res
   while {$mod ne $res && [info exists g_resolvedPath($res)]} {
      set res $g_resolvedPath($res)
      lappend res_path $res
   }

   # error if resolution end on initial module
   if {$mod eq $res} {
      reportError "Resolution loop on '$res' detected"
      return 0
   }

   # module name will be useful when registering symbol
   if {$symver ne {}} {
      lassign [getModuleNameVersion $mod] modfull modname
   }

   # change default symbol owner if previously given; auto symbol are defined
   # only if no default is pre-existing
   if {$symver eq {default} && !$auto_symver} {
      # alternative name "modname" is set when mod = "modname/default" both
      # names will be registered to be known for queries and resolution defs
      set modalt $modname

      if {[info exists g_moduleResolved($mod)]} {
         set prev $g_moduleResolved($mod)
         # there may not be a default in case of auto symbol
         if {[info exists g_symbolHash($prev)] && [set idx [lsearch -exact\
            $g_symbolHash($prev) default]] != -1} {
            reportDebug "remove symbol 'default' from '$prev'"
            set g_symbolHash($prev) [lreplace $g_symbolHash($prev) $idx $idx]
         }
      }
   }

   # register end-point resolution
   reportDebug "$mod resolved to $res"
   set g_moduleResolved($mod) $res
   # set first element of resolution path only if not already set or
   # scratching enabled, no change when propagating symbol along res path
   if {$override_res_path || ![info exists g_resolvedPath($mod)]} {
      set g_resolvedPath($mod) $target
   }
   lappend g_resolvedHash($res) $mod

   # also register resolution on alternative name if any
   if {[info exists modalt]} {
      reportDebug "$modalt resolved to $res"
      set g_moduleResolved($modalt) $res
      if {$override_res_path || ![info exists g_resolvedPath($modalt)]} {
         set g_resolvedPath($modalt) $target
      }
      lappend g_resolvedHash($res) $modalt
      # register name alternative to know their existence
      set ::g_moduleAltName($modalt) $mod
      set ::g_moduleAltName($mod) $modalt
   }

   # if other modules were pointing to this one, adapt resolution end-point
   set relmod_list {}
   if {[info exists g_resolvedHash($mod)]} {
      set relmod_list $g_resolvedHash($mod)
      unset g_resolvedHash($mod)
   }
   # also adapt resolution for modules pointing to the alternative name
   if {[info exists modalt] && [info exists g_resolvedHash($modalt)]} {
      lappend relmod_list {*}$g_resolvedHash($modalt)
      unset g_resolvedHash($modalt)
   }
   foreach relmod $relmod_list {
      set g_moduleResolved($relmod) $res
      reportDebug "$relmod now resolved to $res"
      lappend g_resolvedHash($res) $relmod
   }

   # register and propagate symbols to the resolution path, exception made for
   # auto symbol which are stored separately and not propagated
   if {[info exists g_symbolHash($mod)]} {
      set sym_list $g_symbolHash($mod)
   } else {
      set sym_list {}
   }
   if {$symver ne {} && $auto_symver} {
      reportDebug "define auto symbolic version '$mod' targeting $target"
      set ::g_autoSymbol($mod) $target
   } elseif {$symver ne {} && !$auto_symver} {
      # merge symbol definitions in case of alternative name
      if {[info exists modalt] && [info exists g_symbolHash($modalt)]} {
         set sym_list [lsort -dictionary -unique [list {*}$sym_list\
            {*}$g_symbolHash($modalt)]]
         reportDebug "set symbols '$sym_list' to $mod and $modalt"
         set g_symbolHash($mod) $sym_list
         set g_symbolHash($modalt) $sym_list
      }

      # dictionary-sort symbols and remove eventual duplicates
      set sym_list [lsort -dictionary -unique [list {*}$sym_list $symver]]

      # propagate symbols in g_symbolHash and g_moduleVersion toward the
      # resolution path, handle that locally if we still work on same
      # modulename, call for a proper resolution as soon as we change of
      # module to get this new resolution registered
      foreach modres $res_path {
         lassign [getModuleNameVersion $modres] modfull modresname
         if {$modname eq $modresname} {
            if {[info exists g_symbolHash($modres)]} {
               set modres_sym_list [lsort -dictionary -unique [list\
                  {*}$g_symbolHash($modres) {*}$sym_list]]
            } else {
               set modres_sym_list $sym_list
            }
            # sync symbols of alternative name if any
            if {[info exists ::g_moduleAltName($modres)]} {
               set altmodres $::g_moduleAltName($modres)
               reportDebug "set symbols '$modres_sym_list' to $modres and\
                  $altmodres"
               set g_symbolHash($altmodres) $modres_sym_list
            } else {
               reportDebug "set symbols '$modres_sym_list' to $modres"
            }
            set g_symbolHash($modres) $modres_sym_list

            # register symbolic version for querying in g_moduleVersion
            foreach symelt $sym_list {
               set modvers $modresname/$symelt
               reportDebug "module-version $modvers = $modres"
               set ::g_moduleVersion($modvers) $modres
               set ::g_sourceVersion($modvers) [currentState modulefile]
               # record eventual missing resolution
               if {![info exists g_moduleResolved($modvers)]} {
                  set g_moduleResolved($modvers) $modres
                  reportDebug "$modvers resolved to $modres"
                  lappend g_resolvedHash($modres) $modvers
               }
            }
         # as we change of module name a proper resolution call should be
         # made (see below) and will handle the rest of the resolution path
         } else {
            set need_set_res 1
            break
         }
      }
   # when registering an alias, existing symbols on alias source name should
   # be broadcast along the resolution path with a proper resolution call
   # (see below)
   } else {
      lassign [getModuleNameVersion $target] modres modresname
      set need_set_res 1
   }

   # resolution needed to broadcast symbols along resolution path without
   # altering initial path already set for these symbols
   if {[info exists need_set_res]} {
      foreach symelt $sym_list {
         set modvers $modresname/$symelt
         reportDebug "set resolution for $modvers"
         setModuleResolution $modvers $modres $symelt 0
      }
   }

   return 1
}

# retrieve all names that resolve to passed mod
proc getAllModuleResolvedName {mod {flag_type 0} {modspec {}} {filter_default\
   0}} {
   set namelist {}
   set resmodlist {}
   set icase [isIcase]

   # get parent directories of mod
   foreach modelt [split $mod /] {
      if {[info exists modroot]} {
         append modroot /
      }
      append modroot $modelt
      lappend resmodlist $modroot
   }

   set modpar [file dirname $mod]
   set moddfl $modpar/default

   # add additionally all the altnames set on directories, parents of mod
   # or on distant directories whose default version resolves to mod
   for {set i 0} {$i < [llength $resmodlist]} {incr i 1} {
      set modelt [getArrayKey ::g_resolvedHash [lindex $resmodlist $i] $icase]
      if {[info exists ::g_resolvedHash($modelt)]} {
         foreach resmod $::g_resolvedHash($modelt) {
            # if alternative name corresponds to one root name test if default
            # symbol is hidden
            set resmoddfl [expr {[lsearch -exact $resmodlist $resmod] != -1 ?\
               "$resmod/default" : {}}]
            # if alternative name corresponds to default symbol and is hidden
            # test if query matches bare module name
            set resmodpar [expr {[file tail $resmod] eq {default} ? [file\
               dirname $resmod] : {}}]

            # if modelt is not a parent directory of mod, check its resolution
            # points to mod (directly for alias/sym or indirectly for dir
            # whose default version bridge resolution toward mod)
            # if modspec arg is set, exclude hidden entries not explicitly
            # matching modspec. auto symbols cannot be hidden
            # if filter_default is asked, skip parent module name and /default
            # symbol name from result list
            if {($modspec eq {} || ([info exists ::g_autoSymbol($resmod)] &&\
               $::g_autoSymbol($resmod) eq $mod) || (![isModuleHidden $resmod\
               $modspec] && ($resmoddfl eq {} || ![isModuleHidden $resmoddfl\
               $modspec])) || [modEq $modspec $resmod eqspec] || ($resmodpar\
               ne {} && [modEq $modspec $resmodpar eqspec])) && ([modEq\
               $modelt $mod eqstart] || $::g_moduleResolved($resmod) eq $mod\
               || $mod eq [lindex [getPathToModule\
               $::g_moduleResolved($resmod) {} 0] 1]) && (!$filter_default ||\
               (![modEq $resmod $modpar] && ![modEq $resmod $moddfl]))} {
               # prefix automatically generated syms with type flag if asked
               if {$flag_type} {
                  set name_entry [list]
                  if {[info exists ::g_moduleAlias($resmod)]} {
                     lappend name_entry al
                  } elseif {[info exists ::g_autoSymbol($resmod)]} {
                     lappend name_entry as
                  }
                  lappend name_entry $resmod
               } else {
                  set name_entry $resmod
               }
               lappendNoDup namelist $name_entry

               unset modroot
               foreach reselt [split [file dirname $resmod] /] {
                  if {[info exists modroot]} {
                     append modroot /
                  }
                  append modroot $reselt
                  lappendNoDup resmodlist $modroot
               }
            }
         }
      }
   }
   return $namelist
}

# build list for a given loaded module of its alternative names plus its
# simplified names (name minus version or any subdir if this version or subdir
# are the implicit default for module)
proc getLoadedAltAndSimplifiedName {mod} {
   if {[isModuleFullPath $mod]} {
      set namelist [list $mod]
   # use already computed name list if any
   } elseif {[info exists ::g_loadedAltAndSimplifiedName($mod)]} {
      set namelist $::g_loadedAltAndSimplifiedName($mod)
   } else {
      # get recorded alternative name
      set namelist [getLoadedAltname $mod]
      # also look through modpaths for simplified mod name
      set modpathlist [getModulePathList]
      if {[llength $modpathlist]} {
         set modfile [getModulefileFromLoadedModule $mod]
         set parentmod [file dirname $mod]
         # simplify to parent name as long as it resolves to current mod
         while {$parentmod ne {.}} {
            lassign [getPathToModule $parentmod $modpathlist 0] parentfile
            if {$parentfile eq $modfile} {
               lappend namelist $parentmod
               set parentmod [file dirname $parentmod]
            } else {
               set parentmod .
            }
         }
      }
      # recorded computed name list for later use
      set ::g_loadedAltAndSimplifiedName($mod) $namelist
   }
   return $namelist
}

# return value list of a loaded module property by parsing corresponding
# environment variable
proc getEnvLoadedModulePropertyParsedList {prop} {
   set unserialize_depth [getEnvLoadedModulePropertyStructDepth $prop]
   set unserialize_proc unserialize${unserialize_depth}ModulePropertyValueList
   set char_unmap_list [getEnvLoadedModulePropertyCharUnmapList $prop]

   set serialized_value_list [getEnvLoadedModulePropertyList $prop]
   set structured_value_list [$unserialize_proc $serialized_value_list\
      $char_unmap_list]
   return $structured_value_list
}

proc getEnvLoadedModulePropertyList {prop} {
   set env_var_name [getLoadedModulePropertyEnvVarName $prop]
   return [split [get-env $env_var_name] [getState path_separator]]
}

proc getLoadedModulePropertyEnvVarName {prop} {
   switch -- $prop {
      name {set env_var_name LOADEDMODULES}
      file {set env_var_name _LMFILES_}
      modulepath {set env_var_name MODULEPATH}
      default {set env_var_name __MODULES_LM[string toupper $prop]}
   }
   return $env_var_name
}

# return list of module paths by parsing MODULEPATH env variable
# behavior param enables to exit in error when no MODULEPATH env variable
# is set. by default an empty list is returned if no MODULEPATH set
# resolv_var param tells if environment variable references in path elements
# should be resolved or passed as-is in result list
# set_abs param applies an absolute path name conversion to path elements
# if enabled
proc getModulePathList {{behavior returnempty} {resolv_var 1} {set_abs 1}} {
   if {![isEnvVarDefined MODULEPATH] && $behavior eq {exiterronundef}} {
      reportErrorAndExit {No module path defined}
   }

   set modpath_list [list]
   foreach modpath [getEnvLoadedModulePropertyParsedList modulepath] {
      if {$resolv_var} {
         set modpath [resolvStringWithEnv $modpath]
      }
      if {$set_abs} {
         set modpath [getAbsolutePath $modpath]
      }
      lappendNoDup modpath_list $modpath
   }
   return $modpath_list
}

proc getModulepathLabel {modpath} {
   if {[info exists ::g_modulepathLabel($modpath)]} {
      return $::g_modulepathLabel($modpath)
   } else {
      return $modpath
   }
}

# return list of the configured and existing global RC files
proc getGlobalRcFileList {} {
   set rclist {}

   set rcfilelist [getConfList rcfile]
   if {[llength $rcfilelist]} {
      foreach rcfile $rcfilelist {
         # if rcfile is a dir, look at a modulerc file in it
         if {[file isdirectory $rcfile] && [file isfile $rcfile/modulerc]} {
            lappend rclist $rcfile/modulerc
         } elseif {[file isfile $rcfile]} {
            lappend rclist $rcfile
         }
      }
   }
   if {[file isfile {@etcdir@/rc}]} {
      lappend rclist {@etcdir@/rc}
   }
   # ignore user rc if relative configuration is enabled
   if {![getConf ignore_user_rc] && [isEnvVarDefined HOME] && [file isfile\
      $::env(HOME)/.modulerc]} {
      lappend rclist $::env(HOME)/.modulerc
   }

   set readable_rclist {}
   foreach rc $rclist {
      if {[file readable $rc]} {
         lappend readable_rclist $rc
      }
   }

   return $readable_rclist
}

proc getModuleTag {mod full_path_mod tag} {
   # check if tag is set on full path module designation (no prop there)
   lassign [getFullPathModuleTagSpec $full_path_mod $tag] tag_mod_spec\
      tag_props
   if {[string length $tag_mod_spec]} {
      return [list $tag $tag_props]
   }
   # look if mod matches one of the module specs applying to mod root
   foreach {tmodspec tag_props} [getModuleRootTagSpecList $mod $tag] {
      # first matching module spec wins with its properties
      if {[modEq $tmodspec $mod eqstart 1 0 1]} {
         return [list $tag $tag_props]
      }
   }
   return {}
}

proc getModuleTagRuleList {mod full_path_mod tag} {
   set rule_list {}
   lassign [getFullPathModuleTagSpec $full_path_mod $tag] tag_mod_spec\
      tag_props
   if {[string length $tag_mod_spec]} {
      lappend rule_list $tag_mod_spec
   }
   foreach {tag_mod_spec tag_props} [getModuleRootTagSpecList $mod $tag] {
      if {$tag_mod_spec ni $rule_list && [modEq $tag_mod_spec $mod eqstart 1\
         0 1]} {
         lappend rule_list $tag_mod_spec
      }
   }
   return $rule_list
}

proc getModuleRootTagSpecList {mod tag} {
   set tag_spec_list {}
   set mod_root [getModuleRootFromVersSpec $mod]
   if {[info exists ::g_moduleTagRoot($mod_root)]} {
      set idx [lsearch -exact $::g_moduleTagRoot($mod_root) $tag]
      set tag_spec_list [lindex $::g_moduleTagRootSpec($mod_root) $idx]
   }
   return $tag_spec_list
}

proc getFullPathModuleTagSpec {full_path_mod tag} {
   set tag_spec {}
   if {$full_path_mod ne {} && [info exists\
      ::g_moduleTagFullPath($full_path_mod)]} {
      set idx [lsearch -exact $::g_moduleTagFullPath($full_path_mod) $tag]
      if {$idx != -1} {
         set tag_spec [list $full_path_mod [lindex\
            $::g_moduleTagFullPathSpec($full_path_mod) $idx]]
      }
   }
   return $tag_spec
}

proc isModuleTagged {mod tag {collected 0} {fpmod {}}} {
   # retrieve tag information from collected tags or raw info
   if {$collected} {
      return [expr {$tag in [getTagList $mod $fpmod]}]
   } else {
      return [llength [getModuleTag $mod $fpmod $tag]]
   }
}

proc getTaggedLoadedModuleList {tag} {
   set modlist [list]
   foreach mod [getEnvLoadedModulePropertyParsedList name] {
      if {[isModuleTagged $mod $tag 1]} {
         lappend modlist $mod
      }
   }
   return $modlist
}

proc getModuleTagProp {mod fpmod tag prop} {
   array set tags [getModuleTag $mod $fpmod $tag]

   if {[info exists tags($tag)]} {
      array set props $tags($tag)
      if {[info exists props($prop)]} {
         return $props($prop)
      }
   }
}

# Gather all tags applying to a given module
proc collectModuleTags {mod} {
   if {[info exists ::g_tagHash($mod)]} {
      set known_tag_list $::g_tagHash($mod)
   } else {
      set known_tag_list {}
   }
   set tag_list [getMatchingTagList $mod $known_tag_list]
   if {[llength $tag_list]} {
      setModuleTag $mod {*}$tag_list
   }
}

proc getMatchingTagList {mod {known_tag_list {}}} {
   set tag_list {}
   set modroot [getModuleRootFromVersSpec $mod]
   # look if mod matches one of the module specs applying to mod root
   if {[info exists ::g_moduleTagRoot($modroot)]} {
      for {set i 0} {$i < [llength $::g_moduleTagRoot($modroot)]} {incr i} {
         set tag [lindex $::g_moduleTagRoot($modroot) $i]
         if {$tag ni $tag_list} {
            foreach {tmodspec tprops} [lindex\
               $::g_moduleTagRootSpec($modroot) $i] {
               # add tag if one modspec matches mod
               if {[modEq $tmodspec $mod eqstart 1 0 1]} {
                  lappend known_tag_list $tag
                  lappend tag_list $tag
                  break
               }
            }
         }
      }
   }
   return $tag_list
}

proc setModuleTag {mod args} {
   lappendNoDup ::g_tagHash($mod) {*}$args
}

proc setModuleAndVariantsTag {mod mod_with_vr args} {
   setModuleTag $mod {*}$args
   if {$mod_with_vr ne {} && $mod ne $mod_with_vr} {
      setModuleTag $mod_with_vr {*}$args
   }
}

proc setModuleExtraTag {mod args} {
   lappendNoDup ::g_extraTagHash($mod) {*}$args
}

proc setModuleAndVariantsExtraTag {mod mod_with_vr args} {
   setModuleExtraTag $mod {*}$args
   if {$mod_with_vr ne {} && $mod ne $mod_with_vr} {
      setModuleExtraTag $mod_with_vr {*}$args
   }
}

proc unsetModuleTag {mod args} {
   if {[info exists ::g_tagHash($mod)]} {
      lassign [getDiffBetweenList $::g_tagHash($mod) $args] diff_list
      if {[llength $args] && [llength $diff_list]} {
         set ::g_tagHash($mod) $diff_list
      } else {
         unset ::g_tagHash($mod)
      }
   }
}

proc unsetModuleAndVariantsTag {mod mod_with_vr args} {
   unsetModuleTag $mod {*}$args
   if {$mod_with_vr ne {} && $mod ne $mod_with_vr} {
      unsetModuleTag $mod_with_vr {*}$args
   }
}

proc unsetModuleExtraTag {mod args} {
   if {[info exists ::g_extraTagHash($mod)]} {
      lassign [getDiffBetweenList $::g_extraTagHash($mod) $args] diff_list
      if {[llength $args] && [llength $diff_list]} {
         set ::g_extraTagHash($mod) $diff_list
      } else {
         unset ::g_extraTagHash($mod)
      }
   }
}

proc unsetModuleAndVariantsExtraTag {mod mod_with_vr args} {
   unsetModuleExtraTag $mod {*}$args
   if {$mod_with_vr ne {} && $mod ne $mod_with_vr} {
      unsetModuleExtraTag $mod_with_vr {*}$args
   }
}

proc getTagList {mod {fpmod {}} {sort 1}} {
   set tag_list {}
   # get tags applied over module full path designation
   if {$fpmod ne {} && [info exists ::g_moduleTagFullPath($fpmod)]} {
      lappendNoDup tag_list {*}$::g_moduleTagFullPath($fpmod)
   }
   # recompute tags applying from module specification if mod is loaded but
   # not the same modulefile. tags applying to loaded mod are recorded in
   # g_tagHash but should not apply to same mod from a different modulepath
   # do not make this distinction if modulefile is not provided
   # directly check on g_loadedModules array to avoid triggering env check
   if {[string length $fpmod] && [info exists ::g_loadedModules($mod)] &&\
      $fpmod ne [getModulefileFromLoadedModule $mod]} {
      lappendNoDup tag_list {*}[getMatchingTagList $mod]
   # get collected tags applied on short designation
   } elseif {[info exists ::g_tagHash($mod)]} {
      lappendNoDup tag_list {*}$::g_tagHash($mod)
   }
   if {[llength $tag_list]} {
      if {$sort} {
         set tag_list [lsort -dictionary $tag_list]
      }
      reportDebug "'$mod' has tag list '$tag_list'"
   }
   return $tag_list
}

# return tags applying to mod that can be exported
proc getExportTagList {mod {fpmod {}}} {
   # remove loaded/hidden tags from the list to register
   lassign [getDiffBetweenList [getTagList $mod $fpmod 0] [list loaded\
      hidden]] ret
   return $ret
}

# return extra tags set on mod
proc getExtraTagList {mod} {
   if {[info exists ::g_extraTagHash($mod)]} {
      return $::g_extraTagHash($mod)
   }
}

# return rule definition of sticky/super-sticky tag on given module
proc getStickyRuleList {mod {fpmod {}}} {
   set ret {}
   foreach tag {sticky super-sticky} {
      if {[isModuleTagged $mod $tag 1]} {
         set export_sticky_rule 1
         set tag_rule_list [getModuleTagRuleList $mod $fpmod $tag]

         # skip rule export if one matches module name and version or full
         # path designation
         foreach tag_rule $tag_rule_list {
            if {[modEq $tag_rule $mod equal 1 0 1] || [modEq $tag_rule $fpmod\
               equal 1 0 1]} {
               set export_sticky_rule 0
               break
            }
         }

         if {[llength $tag_rule_list] && $export_sticky_rule} {
            lappend ret [list $tag {*}$tag_rule_list]
         }
      }
   }
   return $ret
}

# return tags set on mod to record in collection
proc getSaveTagList {mod} {
   # return all tags if pin tag is enabled, except nearly-forbidden that is
   # not intended for save
   if {[getConf collection_pin_tag]} {
      lassign [getDiffBetweenList [getExportTagList $mod] [list\
         nearly-forbidden]] ret
   } else {
      set ret [getExtraTagList $mod]
      # in addition to those set with --tag option, add tags obtained by the
      # way mod has been loaded
      if {[isModuleTagged $mod auto-loaded 1]} {
         lappend ret auto-loaded
      }
      if {[isModuleTagged $mod keep-loaded 1]} {
         lappend ret keep-loaded
      }
   }
   return $ret
}

proc abbrevTagList {taglist} {
   set ret [list]
   foreach tag $taglist {
      if {[info exists ::g_tagAbbrev($tag)]} {
         # empty string abbrev means no tag report
         if {$::g_tagAbbrev($tag) ne {}} {
            lappend ret $::g_tagAbbrev($tag)
         }
      } else {
         lappend ret $tag
      }
   }
   return [lsort -dictionary $ret]
}

proc getTagFromAbbrev {abbrev} {
   if {![array exists ::g_abbrevTag]} {
      getConf tag_abbrev
   }
   if {[info exists ::g_abbrevTag($abbrev)]} {
      return $::g_abbrevTag($abbrev)
   }
}

proc getVariantList {mod {report 0} {excl_dflval 0} {from 0}} {
   set vrspeclist {}
   set loadedsgrkey {}
   # fetch variant information from
   switch -- $from {
      0 {
         # variant set after module being loaded
         if {[info exists ::g_loadedModuleVariant($mod)]} {
            set vrspeclist $::g_loadedModuleVariant($mod)
         }
      }
      1 {
         # module specification
         set vrspeclist {}
         foreach vrspec [getVariantListFromVersSpec $mod] {
            lassign $vrspec vrname vrnot vrvalisbool vrvalue
            lappend vrspeclist [list $vrname $vrvalue $vrvalisbool]
         }
      }
      2 {
         # variant definition collected during scan evaluation
         if {[info exists ::g_scanModuleVariant($mod)]} {
            set vrspeclist $::g_scanModuleVariant($mod)
         }
         # if module is currently loaded, gather its variant values
         if {[info exists ::g_loadedModuleVariant($mod)]} {
            foreach lovrspec $::g_loadedModuleVariant($mod) {
               lassign $lovrspec lovrname lovrvalue lovrvalisbool lovrvalisdfl
               if {$lovrvalisbool} {
                  set lovrvalue [expr {$lovrvalue ? {on} : {off}}]
               }
               set lovrarr($lovrname) $lovrvalue
            }
            # get sgr key corresponding to loaded tag (if tag reported)
            if {$report == 7 && [isEltInReport tag]} {
               set loadedkind [expr {[isModuleTagged $mod auto-loaded 1] ?\
                  {auto-loaded} : {loaded}}]
               lassign [abbrevTagList [list $loadedkind]] loadedsgrkey
            }
         }
      }
   }

   # use array to make variant unique
   foreach vrspec $vrspeclist {
      if {$from == 2} {
         # report all available variant values on avail
         lassign $vrspec vrname vrvalues vrdefdflval vrdflval
         set vrvalisbool 0
         set vrvalisdfl 0
         # build value list to output for free-variant value
         if {![llength $vrvalues]} {
            # if module is loaded, add loaded variant value
            if {[info exists lovrarr($vrname)]} {
               lappend vrvalues $lovrarr($vrname)
            }
            # if a default value is defined, add it to possible value list
            if {$vrdefdflval && $vrdflval ni $vrvalues} {
               lappend vrvalues $vrdflval
            }
            # indicate on free-value variant that all values are possible
            lappend vrvalues *
         }
      } else {
         lassign $vrspec vrname vrvalue vrvalisbool vrvalisdfl
         set vrvalues [list $vrvalue]
      }
      # correct is-default value if invalid
      if {![string is integer -strict $vrvalisdfl]} {
         set vrvalisdfl 0
      }
      # correct is-boolean value if invalid
      if {![string is boolean -strict $vrvalisbool]} {
         set vrvalisbool 0
      }
      set vrisbool($vrname) $vrvalisbool
      # correct boolean value if invalid
      if {$vrvalisbool && ![string is boolean -strict $vrvalue]} {
         set vrvalue 0
      }
      # do not return variant if value is default, unless if variant was
      # specifically set to default value (isdfl=1) and we only want to
      # exclude the automatically set default value (excl_dflval=2)
      if {$excl_dflval > 0} {
         if {$vrvalisdfl == 0 || ($excl_dflval == 2 && $vrvalisdfl == 1)} {
            set vrarr($vrname) $vrvalue
         # nullify previous duplicate definition if this one is default
         } elseif {[info exists vrarr($vrname)]} {
            unset vrarr($vrname)
         }
      } else {
         if {$report == 7} {
            # indicate what value in the list is the default one
            if {[info exists vrdefdflval]} {
               set vrdflidxarr($vrname) [expr {$vrdefdflval ? [lsearch -exact\
                  $vrvalues $vrdflval] : {-1}}]
            } else {
               set vrdflidxarr($vrname) [expr {$vrvalisdfl ? {0} : {-1}}]
            }
            # indicate what value in the list is the loaded one
            set vrloidxarr($vrname) [expr {[info exists lovrarr($vrname)] ?\
               [lsearch -exact $vrvalues $lovrarr($vrname)] : {-1}}]
            if {$vrvalisbool} {
               set vrarr($vrname) $vrvalue
            } else {
               set vrarr($vrname) $vrvalues
            }
         # is-default hint has to be transmitted on report mode '3'
         } elseif {$report == 3} {
            set vrarr($vrname) [list $vrvalue [expr {$vrvalisdfl > 0 &&\
               $vrvalisdfl < 3}]]
         } else {
            set vrarr($vrname) $vrvalue
         }
      }
   }
   # sort variant to report
   set ret {}
   foreach vrname [lsort -dictionary [array names vrarr]] {
      switch -- $report {
         4 {lappend ret $vrname $vrarr($vrname) $vrisbool($vrname)}
         3 {lappend ret $vrname [lindex $vrarr($vrname) 0] [lindex\
            $vrarr($vrname) 1]}
         2 {lappend ret [list $vrname 0 $vrisbool($vrname) $vrarr($vrname)]}
         1 - 5 - 6 {
            if {$vrisbool($vrname)} {
               if {$vrarr($vrname)} {
                  lappend ret +$vrname
                  # track if +var variant has been reported to build key
                  # unless if key should not be updated (report mode '6')
                  if {$report != 6 && ![info exists ::g_used_va(on)]} {
                     set ::g_used_va(on) 1
                  }
               } else {
                  lappend ret -$vrname
                  # track if -var variant has been reported to build key
                  # unless if key should not be updated (report mode '6')
                  if {$report != 6 && ![info exists ::g_used_va(off)]} {
                     set ::g_used_va(off) 1
                  }
               }
            # use defined shortcut to report if any set for this variant
            # ignore shortcut if report=5 (when saving collection)
            } elseif {$report != 5 && [info exists\
               ::g_variantShortcut($vrname)]} {
               set sc $::g_variantShortcut($vrname)
               lappend ret $sc$vrarr($vrname)
               # track if variant shortcut has been reported to build key
               # unless if key should not be updated (report mode '6')
               if {$report != 6 && ![info exists ::g_used_va($sc)]} {
                  set ::g_used_va($sc) $vrname
               }
            } else {
               lappend ret $vrname=$vrarr($vrname)
               # track if var=val variant has been reported to build key
               # unless if key should not be updated (report mode '6')
               if {$report != 6 && ![info exists ::g_used_va(val)]} {
                  set ::g_used_va(val) 1
               }
            }
         }
         7 {
            if {$vrisbool($vrname)} {
               if {$vrarr($vrname)} {
                  lappend ret [list $vrname {} [list +$vrname]\
                     $vrdflidxarr($vrname) $vrloidxarr($vrname) $loadedsgrkey]
                  # track if +var variant has been reported to build key
                  if {![info exists ::g_used_va(on)]} {
                     set ::g_used_va(on) 1
                  }
               } else {
                  lappend ret [list $vrname {} [list -$vrname]\
                     $vrdflidxarr($vrname) $vrloidxarr($vrname) $loadedsgrkey]
                  # track if -var variant has been reported to build key
                  if {![info exists ::g_used_va(off)]} {
                     set ::g_used_va(off) 1
                  }
               }
            # use defined shortcut to report if any set for this variant
            # ignore shortcut if report=5 (when saving collection)
            } elseif {$report != 5 && [info exists\
               ::g_variantShortcut($vrname)]} {
               set sc $::g_variantShortcut($vrname)
               lappend ret [list $vrname $sc $vrarr($vrname)\
                  $vrdflidxarr($vrname) $vrloidxarr($vrname) $loadedsgrkey]
               # track if variant shortcut has been reported to build key
               # unless if key should not be updated (report mode '6')
               if {$report != 6 && ![info exists ::g_used_va($sc)]} {
                  set ::g_used_va($sc) $vrname
               }
            } else {
               lappend ret [list $vrname $vrname= $vrarr($vrname)\
                  $vrdflidxarr($vrname) $vrloidxarr($vrname) $loadedsgrkey]
               # track if var=val variant has been reported to build key
               # unless if key should not be updated (report mode '6')
               if {$report != 6 && ![info exists ::g_used_va(val)]} {
                  set ::g_used_va(val) 1
               }
            }
         }
         0 {lappend ret $vrname $vrarr($vrname)}
      }
   }

   return $ret
}

proc isOtherVariantOfModuleLoading {mod} {
   set mod_name [getModuleNameAndVersFromVersSpec $mod]
   set mod_has_variant [expr {$mod ne $mod_name}]

   return [expr {$mod_has_variant && [isModuleLoading $mod_name] && ![string\
      length [getLoadedMatchingName $mod {} 1]]}]
}

proc isOtherVariantOfModuleLoaded {mod} {
   set mod_name [getModuleNameAndVersFromVersSpec $mod]
   set mod_has_variant [expr {$mod ne $mod_name}]

   return [expr {$mod_has_variant && [isModuleLoaded $mod_name] && ![string\
      length [getLoadedMatchingName $mod]]}]
}

proc isModuleDotHidden {mod} {
   foreach elt [split $mod /] {
      if {[string index $elt 0] eq {.}} {
         return 1
      }
   }
   return 0
}

proc getModuleHidingLevel {mod fpmod} {
   # if full path module has been hidden, this hidden level is the base level
   # value we will return
   set baselvl [expr {$fpmod ne {} && [info exists\
      ::g_moduleHideFullPath($fpmod)] ? $::g_moduleHideFullPath($fpmod) :\
      {-1}}]

   set modroot [lindex [file split $mod] 0]
   # look if mod matches one of the hidden module specs applying to mod root
   if {[info exists ::g_moduleHideRoot($modroot)]} {
      for {set lvl 2} {$lvl > -1} {incr lvl -1} {
         # no need to search anymore if we have reached same hiding level as
         # one defined on full path module designation
         if {$lvl == $baselvl} {
            break
         }
         foreach hmodspec [lindex $::g_moduleHideRoot($modroot) $lvl] {
            if {[modEq $hmodspec $mod eqstart 1 0 1 {}]} {
               return $lvl
            }
         }
      }
   }
   return $baselvl
}

proc setModspecHidingLevel {modspec lvl} {
   # skip record if an higher hiding level is already set
   if {![info exists ::g_moduleHide($modspec)] || $lvl >\
      $::g_moduleHide($modspec)} {
      reportDebug "Record hidden module specification '$modspec' (lvl=$lvl)"
      set ::g_moduleHide($modspec) $lvl

      if {[isModuleFullPath $modspec]} {
         set ::g_moduleHideFullPath($modspec) $lvl
      } else {
         # record hidden mod spec for mod root to optimize search
         set modroot [getModuleRootFromVersSpec $modspec]
         if {![info exists ::g_moduleHideRoot($modroot)]} {
            set ::g_moduleHideRoot($modroot) [list [list] [list] [list]]
         }
         # record in list corresponding to hidden level to search from
         # strongest to weakest hidden level
         set hiderootlvllist [lindex $::g_moduleHideRoot($modroot) $lvl]
         lappend hiderootlvllist $modspec
         lset ::g_moduleHideRoot($modroot) $lvl $hiderootlvllist
      }
   }
}

# test if mod is declared hidden or has one element in its name starting with
# dot character. mod is considered hidden depending on their hiding level,
# current search query and hiding threshold. when retdetails option is
# enabled, mod hiding level and query match hind are also returned
# also checks full path module designation if fpmod is set
proc isModuleHidden {mod {modspec {}} {retdetails 0} {fpmod {}}} {
   set defhidlvl [set hidlvl [getModuleHidingLevel $mod $fpmod]]
   if {$hidlvl >= [getState hiding_threshold]} {
      # soft hidden mods are considered matched if their root name matches
      # search query, other kind of hidden mods must fully matches query
      set hidmatch [expr {$hidlvl == 0 ? [modStartNb $mod $modspec] > 0 :\
         [modEq $modspec $mod eqspec]}]
   } else {
      set hidlvl -1
      set hidmatch 0
   }
   if {$hidlvl < 1 && [set isdot [isModuleDotHidden $mod]] && [getState\
      hiding_threshold] < 1} {
      set hidlvl 1
      # dot hidden are considered matched if remaining string part after
      # search query is not dot hidden
      set hidmatch [expr {[set i [modStartNb $mod $modspec]] > 0 &&\
         ![isModuleDotHidden [join [lrange [file split $mod] $i end] /]]}]
   }
   # hidden if hiding level greater or equal hiding threshold and not
   # matched or if matched hard hiding level are kept hidden
   set ishid [expr {$hidlvl != -1 && (!$hidmatch || $hidlvl > 1)}]

   # is module hidden by definition (whatever hiding threshold or match)
   set hidbydef [expr {$defhidlvl > 0 || ([info exists isdot] && $isdot)}]

   return [expr {$retdetails ? [list $hidlvl $hidmatch $hidbydef $ishid]\
      : $ishid}]
}

# check if module name is specified as a full pathname (not a name relative
# to a modulepath)
proc isModuleFullPath {mod} {
   return [regexp {^(|\.|\.\.)/} $mod]
}

# check if a module corresponds to a virtual module (module name
# does not corresponds to end of the modulefile name)
proc isModuleVirtual {mod modfile} {
   return [expr {[string first $mod $modfile end-[string length $mod]] == -1}]
}

# Return the full pathname and modulename to the module.
# Resolve aliases and default versions if the module name is something like
# "name/version" or just "name" (find default version).
proc getPathToModule {mod {indir {}} {report_issue 1} {look_loaded no}\
   {excdir {}}} {
   reportDebug "finding '$mod' in '$indir' (report_issue=$report_issue,\
      look_loaded=$look_loaded, excdir='$excdir')"

   set vrlist [getVariantList $mod 1 0 1]
   if {$mod eq {}} {
      set retlist [list {} {} {} none [getEmptyNameMsg module]]
   # try first to look at loaded modules if enabled to find matching module
   # or to find a closest match (used when switching with single name arg)
   } elseif {$look_loaded ne {no}} {
      switch -- $look_loaded {
         exact {set getLoadedNameProc getLoadedExactName}
         match {set getLoadedNameProc getLoadedEqstartName}
         close {set getLoadedNameProc getLoadedWithClosestName}
      }
      if {[set lm [$getLoadedNameProc $mod $indir]] ne {}} {
         set vrlist [getVariantList $lm 1]
         set retlist [list [getModulefileFromLoadedModule $lm] $lm]
      } else {
         set retlist [list {} [getModuleNameAndVersFromVersSpec $mod]\
            $mod notloaded]
      }
   # Check for $mod specified as a full pathname
   } elseif {[isModuleFullPath $mod]} {
      set mod [getAbsolutePath $mod]
      # note that a raw filename as an argument returns the full
      # path as the module name
      lassign [checkValidModule $mod] check_valid check_msg
      switch -- $check_valid {
         true {
            set retlist [list $mod $mod]
         }
         invalid - accesserr {
            set retlist [list {} $mod $mod $check_valid $check_msg $mod]
         }
      }
   } else {
      set dir_list [expr {$indir ne {} ? $indir : [getModulePathList\
         exiterronundef]}]
      # remove excluded directories (already searched)
      foreach dir $excdir {
         lrem dir_list $dir
      }

      set icase [isIcase]

      # Now search for $mod in module paths
      set modspec $mod
      foreach dir $dir_list {
         # get list of modules corresponding to searched query
         array unset mod_list
         array set mod_list [getModules $dir $mod 0 [list rc_defs_included\
            resolve]]

         set prevmod {}
         set mod_res {}
         # loop to resolve correct modulefile in case specified mod is a
         # directory that should be analyzed to get default mod in it
         while {$prevmod ne $mod} {
            ##nagelfar ignore Found constant
            set mod [getEqArrayKey mod_list $mod]
            set prevmod $mod
            if {[info exists mod_list($mod)]} {
               switch -- [lindex $mod_list($mod) 0] {
                  alias - version {
                     set newmod [resolveModuleVersionOrAlias $mod $icase]
                     if {[info exists mod_list($newmod)]} {
                        set mod $newmod
                     } else {
                        # add specified variants to current resolution
                        set newmod [getAndParseModuleWithVariant $newmod\
                           $vrlist]
                        # restart search on new modulename, constrained to
                        # specified dir if set, if not found in current res
                        return [getPathToModule $newmod $indir $report_issue]
                     }
                  }
                  directory {
                     # is implicit default disabled and none explicitly set?
                     if {[lindex $mod_list($mod) 1] eq {}} {
                        set retlist [list {} $mod $mod none "No default\
                           version defined for '$mod'"]
                     } else {
                        # Move to default element in directory
                        set mod $mod/[lindex $mod_list($mod) 1]
                        # restart search if default element is an hidden dir
                        if {![info exists mod_list($mod)] && [isModuleHidden\
                           $mod $modspec 0 $dir/$mod]} {
                           # add specified variants to current resolution
                           set mod [getAndParseModuleWithVariant $mod $vrlist]
                           return [getPathToModule $mod $indir $report_issue]
                        }
                     }
                  }
                  modulefile {
                     # If mod was a file in this path, return that file
                     set retlist [list $dir/$mod $mod]
                  }
                  virtual {
                     # return virtual name with file it targets
                     set retlist [list [lindex $mod_list($mod) 2] $mod]
                  }
                  invalid - accesserr {
                     # may found mod but issue, so end search with error
                     set retlist [list {} $mod $mod {*}$mod_list($mod)]
                  }
               }
            }
         }
         # break loop if found something (valid or invalid module)
         # elsewhere go to next path
         if {[info exists retlist]} {
            break
         }
      }
   }

   # set result if nothing found
   if {![info exists retlist]} {
      set retlist [list {} $mod $mod none "Unable to locate a modulefile for\
         '$mod'"]
   } else {
      # build module name and variant with variant specified
      set modnamevr [getAndParseModuleWithVariant [lindex $retlist 1] $vrlist]
      # update result if forbidden
      if {[isModuleTagged $modnamevr forbidden 0 [lindex $retlist 0]]} {
         set retlist [list {} [lindex $retlist 1] [lindex $retlist 2]\
            accesserr [getForbiddenMsg $modnamevr [lindex $retlist 0]]]
      }
   }
   if {[lindex $retlist 0] ne {}} {
      lappend retlist $modnamevr
      reportTrace "'[lindex $retlist 1]' ([lindex $retlist 0]) matching\
         '$mod'" {Select module}
   # no error if we look at loaded modules and passed mod not found loaded
   } elseif {[lindex $retlist 3] ne {notloaded} && $report_issue} {
      reportIssue {*}[lrange $retlist 3 5]
   }
   return $retlist
}

proc isModuleLoaded {mod} {
   return [info exists ::g_loadedModules($mod)]
}

proc getModulefileFromLoadedModule {mod} {
   if {[isModuleLoaded $mod]} {
      return $::g_loadedModules($mod)
   }
}

proc getModulepathFromLoadedOrLoadingModule {mod} {
   set modfile [getModulefileFromLoadingModule $mod]
   if {![string length $modfile]} {
      set modfile [getModulefileFromLoadedModule $mod]
   }
   if {[isModuleVirtual $mod $modfile]} {
      # an empty string is returned if no enabled modulepath matches modfile
      return [findModulepathFromModulefile $modfile]
   } else {
      return [getModulepathFromModuleName $modfile $mod]
   }
}

proc isModulefileLoaded {modfile} {
   return [info exists ::g_loadedModuleFiles($modfile)]
}

proc getModuleFromLoadedModulefile {modfile {idx all}} {
   if {[isModulefileLoaded $modfile]} {
      if {$idx eq {all}} {
         return $::g_loadedModuleFiles($modfile)
      } else {
         return [lindex $::g_loadedModuleFiles($modfile) $idx]
      }
   }
}

proc isModuleLoading {mod} {
   return [expr {$mod in [getLoadingModuleList]}]
}

proc isModulefileLoading {modfile} {
   return [expr {$modfile in [getLoadingModuleFileList]}]
}

proc getModulefileFromLoadingModule {mod} {
   if {[isModuleLoading $mod]} {
      set idx [lsearch -exact [getLoadingModuleList] $mod]
      return [lindex [getLoadingModuleFileList] $idx]
   }
}

proc getModuleFromLoadingModulefile {modfile {idx all}} {
   if {[isModulefileLoading $modfile]} {
      set loadingmodlist [getLoadingModuleList]
      foreach i [lsearch -all -exact [getLoadingModuleFileList] $modfile] {
         lappend modlist [lindex $loadingmodlist $i]
      }

      if {$idx eq {all}} {
         return $modlist
      } else {
         return [lindex $modlist $idx]
      }
   }
}

proc isModuleRefreshQualified {mod} {
   return $::g_loadedModulesRefresh($mod)
}

proc getLoadedModulePosition {mod} {
   if {[info exists ::g_loadedModulePosition($mod)]} {
      return $::g_loadedModulePosition($mod)
   } else {
      return -1
   }
}

proc setLoadedModule {mod modfile uasked modvr refresh {build_dep_chain 1}} {
   set ::g_loadedModules($mod) $modfile
   set ::g_loadedModulePosition($mod) [array size ::g_loadedModules]
   # a loaded modfile may correspond to multiple loaded virtual modules
   lappend ::g_loadedModuleFiles($modfile) $mod

   # record if mod has been asked by user and relative loaded/auto-loaded tag
   set loadedtag [expr {$uasked ? {loaded} : {auto-loaded}}]
   setModuleAndVariantsTag $mod $modvr $loadedtag

   # is module qualified for refresh evaluation
   set ::g_loadedModulesRefresh($mod) $refresh

   # build information to more efficiently get matching loaded module
   setLoadedByModroot $mod

   if {$build_dep_chain} {
      setModuleDependency $mod
   }
}

proc unsetLoadedModule {mod modfile} {
   unset ::g_loadedModules($mod)
   unset ::g_loadedModulePosition($mod)
   # a loaded modfile may correspond to multiple loaded virtual modules
   if {[llength $::g_loadedModuleFiles($modfile)] == 1} {
      unset ::g_loadedModuleFiles($modfile)
   } else {
      lrem ::g_loadedModuleFiles($modfile) $mod
   }

   unset ::g_loadedModulesRefresh($mod)

   unsetLoadedByModroot $mod
   unsetModuleDependency $mod
}

# return the currently loaded module whose name is the closest to the
# name passed as argument. if no loaded module match at least one part
# of the passed name, an empty string is returned.
proc getLoadedWithClosestName {name modulepath_list} {
   set ret {}
   set retmax 1

   if {[isModuleFullPath $name]} {
      set fullname [getAbsolutePath $name]
      # if module is passed as full modulefile path name, get corresponding
      # short name from used modulepaths
      if {[set shortname [findModuleNameFromModulefile $fullname]] ne {}} {
         set nametosplit $shortname
      # or look at lmfile names to return the eventual exact match
      } else {
         # module may be loaded with its full path name
         if {[isModuleLoaded $fullname]} {
            set ret $fullname
         # or name corresponds to the _lmfiles_ entry of a virtual modules in
         # which case lastly loaded virtual module is returned
         } elseif {[isModulefileLoaded $fullname]} {
            set ret [getModuleFromLoadedModulefile $fullname end]
         }
      }
   } else {
      set nametosplit $name
   }

   if {[info exists nametosplit]} {
      # compare name to each currently loaded module name
      ##nagelfar ignore Found constant
      foreach mod [getEnvLoadedModulePropertyParsedList name] {
         # if module loaded as fullpath but test name not, try to get loaded
         # mod short name (with currently used modulepaths) to compare it
         if {[isModuleFullPath $mod] && [set modname\
            [findModuleNameFromModulefile $mod]] ne {}} {
            # no alt name to retrieve if module has been loaded full path
            set matchmodlist [list $modname]
         } else {
            # add alternative names of mod to the matching list
            set matchmodlist [list $mod {*}[getLoadedAltname $mod]]
         }

         # compare each element of the name to find closest answer. in case of
         # equality, last loaded module will be returned as it overwrites
         # previously found value
         foreach matchmod $matchmodlist {
            if {[set i [modStartNb $matchmod $nametosplit]] >= $retmax} {
               set retmax $i
               set ret $mod
               break
            }
         }
      }
   }

   reportDebug "'$ret' closest to '$name'"
   return $ret
}

proc getLoadedExactName {name modulepath_list} {
   return [getLoadedMatchingName $name {} 0 {} $modulepath_list eqspec]
}

proc getLoadedEqstartName {name modulepath_list} {
   return [getLoadedMatchingName $name {} 0 {} $modulepath_list]
}

# return the currently loaded module whose name is equal or include the name
# passed as argument. if no loaded module match, an empty string is returned.
# loading: look at currently loading modules instead of loaded if loading == 1
# lmlist: only take into account passed loaded module list not all loaded mods
proc getLoadedMatchingName {name {behavior {}} {loading 0} {lmlist {}}\
   {modulepath_list {}} {eqtest eqstart}} {
   set ret {}
   set retmax 0
   # get default behavior from unload_match_order config
   if {$behavior eq {}} {
      set behavior [getConf unload_match_order]
   }

   # use loading-specific procedures instead of loaded-specific ones
   if {$loading} {
      set isModulefileLoaded isModulefileLoading
      set getModuleFromLoadedModulefile getModuleFromLoadingModulefile
      set isLoadedMatchSpecificPath isLoadingMatchSpecificPath
   } else {
      ##nagelfar ignore #4 Found constant
      set isModulefileLoaded isModulefileLoaded
      set getModuleFromLoadedModulefile getModuleFromLoadedModulefile
      set isLoadedMatchSpecificPath isLoadedMatchSpecificPath
   }

   # fetch currently loaded/loading module name is no list provided
   if {![llength $lmlist]} {
      ##nagelfar ignore #2 Badly formed if statement
      set lmlist [if {$loading} {getLoadingModuleList}\
         {getLoadedMatchingModroot $name}]
   }

   # if module is passed as full modulefile path name, look at lmfile names
   # to return the eventual exact match
   if {[isModuleFullPath $name]} {
      set mod [getAbsolutePath $name]
      # if module is loaded with its full path name loadedmodules entry is
      # equivalent to _lmfiles_ corresponding entry so only check _lmfiles_
      if {[$isModulefileLoaded $mod]} {
         # a loaded modfile may correspond to multiple loaded virtual modules
         switch -- $behavior {
            returnlast {
               # the last loaded/loading module will be returned
               set ret [$getModuleFromLoadedModulefile $mod end]
            }
            returnfirst {
               # the first loaded/loading module will be returned
               set ret [$getModuleFromLoadedModulefile $mod 0]
            }
            returnall {
               # all loaded/loading modules will be returned
               set ret [$getModuleFromLoadedModulefile $mod]
            }
         }
      }
   } elseif {$name ne {}} {
      # compare name to each currently loaded/loading module name, if multiple
      # mod match name:
      foreach mod $lmlist {
         # if module loaded as fullpath but test name not, try to get loaded
         # mod short name (with currently used modulepaths) to compare it
         if {[isModuleFullPath $mod] && [set modname\
            [findModuleNameFromModulefile $mod]] ne {}} {
            set matchmod $modname
         } else {
            set matchmod $mod
         }
         # test module matches specified modulepaths
         if {![$isLoadedMatchSpecificPath $mod $modulepath_list]} {
            continue
         }
         if {[modEq $name $matchmod $eqtest 1 [expr {$loading ? 1 : 2}] 1]} {
            switch -- $behavior {
               returnlast {
                  # the last loaded module will be returned
                  set ret $mod
               }
               returnfirst {
                  # the first loaded module will be returned
                  set ret $mod
                  break
               }
               returnall {
                  # all loaded modules will be returned
                  lappend ret $mod
               }
            }
         }
      }
   }

   reportDebug "'$ret' matches '$name'"
   return $ret
}

# return if loaded mod is part of modulepath from specified constrained list
proc isLoadedMatchSpecificPath {mod modulepath_list} {
   set searchid $mod:$modulepath_list
   if {[info exists ::g_isLoadedMatchSpecificPathMemCache($searchid)]} {
      return $::g_isLoadedMatchSpecificPathMemCache($searchid)
   }
   set mod_file [getModulefileFromLoadedModule $mod]
   set ::g_isLoadedMatchSpecificPathMemCache($searchid)\
      [isModulefileMatchSpecificPath $mod_file $modulepath_list]
}

proc isLoadingMatchSpecificPath {mod modulepath_list} {
   set searchid $mod:$modulepath_list
   if {[info exists ::g_isLoadingMatchSpecificPathMemCache($searchid)]} {
      return $::g_isLoadingMatchSpecificPathMemCache($searchid)
   }
   set mod_file [getModulefileFromLoadingModule $mod]
   set ::g_isLoadingMatchSpecificPathMemCache($searchid)\
      [isModulefileMatchSpecificPath $mod_file $modulepath_list]
}

proc isModulefileMatchSpecificPath {mod_file modulepath_list} {
   if {[llength $modulepath_list]} {
      return [isModulefileInModulepathList $mod_file $modulepath_list]
   } else {
      return 1
   }
}

proc setLoadedSourceSh {mod args} {
   foreach arg $args {
      # each arg is a list with source-sh call string at index 0 and resulting
      # modulefile commands at all later index positions
      set modcontent [lassign $arg shtomodargs]
      if {![llength [getLoadedSourceShScriptContent $mod $shtomodargs]]} {
         # filter alias/function/complete definition not to record them
         set shtomod_entry [list $shtomodargs]
         foreach modcmdlist $modcontent {
            set modcmd [lindex $modcmdlist 0]
            switch -- $modcmd {
               set-alias - set-function {
                  # set an empty body to make valid unset-* call
                  lappend shtomod_entry [list {*}[lrange $modcmdlist 0 1] {}]
               }
               complete {
                  set complist [lrange $modcmdlist 0 2]
                  # ensure only one order is recorded for each shell-name
                  if {![info exists filtcomp($complist)]} {
                     lappend shtomod_entry [list {*}$complist {}]
                     set filtcomp($complist) 1
                  }
               }
               default {
                  lappend shtomod_entry $modcmdlist
               }
            }
         }
         lappend ::g_loadedModuleSourceSh($mod) $shtomod_entry
      }
   }
}

proc unsetLoadedSourceSh {mod} {
   if {[info exists ::g_loadedModuleSourceSh($mod)]} {
      unset ::g_loadedModuleSourceSh($mod)
   }
}

proc getLoadedSourceSh {mod} {
   if {[info exists ::g_loadedModuleSourceSh($mod)]} {
      return $::g_loadedModuleSourceSh($mod)
   }
}

proc getLoadedSourceShScriptContent {mod script} {
   set content {}
   foreach shtomod_entry [getLoadedSourceSh $mod] {
      if {$script eq [lindex $shtomod_entry 0]} {
         set content [lrange $shtomod_entry 1 end]
         break
      }
   }
   return $content
}

proc setLoadedConflict {mod args} {
   lappendNoDup ::g_loadedModuleConflict($mod) {*}$args
   setLoadedConflictByModroot $mod {*}$args
}

proc setLoadedConflictByModroot {mod args} {
   foreach con_spec $args {
      # record lower case mod root if icase is enabled
      set con_mod_root [getModuleRootFromVersSpecLowerIfIcase $con_spec]
      lappend ::g_loadedConflictByModroot($con_mod_root) $mod $con_spec
      lappendNoDup ::g_modrootByLoadedConflict($mod) $con_mod_root
   }
}

proc unsetLoadedConflict {mod} {
   if {[info exists ::g_loadedModuleConflict($mod)]} {
      unset ::g_loadedModuleConflict($mod)
   }
   unsetLoadedConflictByModroot $mod
}

proc unsetLoadedConflictByModroot {mod} {
   if {[info exists ::g_modrootByLoadedConflict($mod)]} {
      foreach mod_root $::g_modrootByLoadedConflict($mod) {
         set with_con_spec_list {}
         foreach {with_mod con_spec} $::g_loadedConflictByModroot($mod_root) {
            if {$with_mod ne $mod} {
               lappend with_con_spec_list $with_mod $con_spec
            }
         }
         if {[llength $with_con_spec_list]} {
            set ::g_loadedConflictByModroot($mod_root) $with_con_spec_list
         } else {
            unset ::g_loadedConflictByModroot($mod_root)
         }
      }
      unset ::g_modrootByLoadedConflict($mod)
   }
}

proc getLoadedConflict {mod} {
   if {[info exists ::g_loadedModuleConflict($mod)]} {
      return $::g_loadedModuleConflict($mod)
   }
}

proc getLoadedConflictMatchingModroot {mod} {
   set with_con_spec_list {}
   set mod_root_list [getLoadedAllModroot $mod]
   foreach mod_root $mod_root_list {
      if {[info exists ::g_loadedConflictByModroot($mod_root)]} {
         lappend with_con_spec_list {*}$::g_loadedConflictByModroot($mod_root)
      }
   }
   return $with_con_spec_list
}

proc getModuleLoadedConflict {mod {modulepath_list {}}} {
   set mod_con_list {}
   # get module short name if loaded by its full pathname
   ##nagelfar ignore #2 Badly formed if statement
   set mod_name [if {[isModuleFullPath $mod]} {findModuleNameFromModulefile\
      $mod} {return -level 0 $mod}]

   # is some loaded or loading modules correspond to conflict defined by mod
   if {[info exists ::g_loadedModuleConflict($mod)]} {
      foreach with_mod $::g_loadedModuleConflict($mod) {
         # skip own reflexive conflict (look at mod main and alternative
         # names) and those already known
         if {![modEq $with_mod $mod_name eqstart 1 2 1] && ([set\
            lm_mod_list [getLoadedMatchingName $with_mod returnall]] ne {}\
            || [set lm_mod_list [getLoadedMatchingName $with_mod returnall\
            1]] ne {})} {
            # multiple loaded module may match conflict declared name
            lappendNoDup mod_con_list {*}$lm_mod_list
         }
      }
   }

   # check if any other loaded module has declared a conflict with mod
   foreach {with_mod con_spec} [getLoadedConflictMatchingModroot $mod] {
      # skip already found and own reflexive conflict
      if {$with_mod ni $mod_con_list && $with_mod ne $mod} {
         if {[modEq $con_spec $mod_name eqstart 1 2 1]} {
            lappend mod_con_list $with_mod
         }
      }
   }

   if {[isOtherVariantOfModuleLoaded $mod] || ([isModuleLoaded $mod] &&\
      ![isLoadedMatchSpecificPath $mod $modulepath_list])} {
      lappend mod_con_list [getModuleNameAndVersFromVersSpec $mod]
   }

   reportDebug "'$mod' conflicts with '$mod_con_list'"
   return $mod_con_list
}

proc setLoadedPrereq {mod args} {
   lappendNoDup ::g_loadedModulePrereq($mod) {*}$args
}

proc unsetLoadedPrereq {mod} {
   if {[info exists ::g_loadedModulePrereq($mod)]} {
      unset ::g_loadedModulePrereq($mod)
   }
}

proc getLoadedPrereq {mod} {
   if {[info exists ::g_loadedModulePrereq($mod)]} {
      return $::g_loadedModulePrereq($mod)
   }
}

proc setLoadedPrereqPath {mod args} {
   lappendNoDup ::g_loadedModulePrereqPath($mod) {*}$args
}

proc unsetLoadedPrereqPath {mod} {
   if {[info exists ::g_loadedModulePrereqPath($mod)]} {
      unset ::g_loadedModulePrereqPath($mod)
   }
}

proc getLoadedPrereqPath {mod {prereq {}}} {
   if {[info exists ::g_loadedModulePrereqPath($mod)]} {
      if {![string length $prereq]} {
         return $::g_loadedModulePrereqPath($mod)
      }
      # return specific entry for given prereq
      array set prereq_path_arr $::g_loadedModulePrereqPath($mod)
      if {[info exists prereq_path_arr($prereq)]} {
         return $prereq_path_arr($prereq)
      }
   }
}

proc setLoadedAltname {mod args} {
   foreach arg $args {
      switch -- [lindex $arg 0] {
         al {
            lappendNoDup ::g_loadedModuleAliasAltname($mod) [lindex $arg 1]
         }
         as {
            lappendNoDup ::g_loadedModuleAutoAltname($mod) [lindex $arg 1]
         }
         default {
            lappendNoDup ::g_loadedModuleAltname($mod) [lindex $arg 0]
         }
      }
   }
}

proc unsetLoadedAltname {mod} {
   if {[info exists ::g_loadedModuleAltname($mod)]} {
      unset ::g_loadedModuleAltname($mod)
   }
   if {[info exists ::g_loadedModuleAliasAltname($mod)]} {
      unset ::g_loadedModuleAliasAltname($mod)
   }
   if {[info exists ::g_loadedModuleAutoAltname($mod)]} {
      unset ::g_loadedModuleAutoAltname($mod)
   }
}

proc getLoadedAltname {mod {typelist {sym alias autosym}} {with_type 0}} {
   set ret {}
   if {[info exists ::g_loadedModuleAltname($mod)] && {sym} in $typelist} {
      if {$with_type} {
         foreach altname $::g_loadedModuleAltname($mod) {
            lappend ret [list $altname]
         }
      } else {
         set ret $::g_loadedModuleAltname($mod)
      }
   }
   if {[info exists ::g_loadedModuleAliasAltname($mod)] && {alias} in\
      $typelist} {
      if {$with_type} {
         foreach altname $::g_loadedModuleAliasAltname($mod) {
            lappend ret [list al $altname]
         }
      } else {
         lappend ret {*}$::g_loadedModuleAliasAltname($mod)
      }
   }
   if {[info exists ::g_loadedModuleAutoAltname($mod)] && {autosym} in\
      $typelist} {
      if {$with_type} {
         foreach altname $::g_loadedModuleAutoAltname($mod) {
            lappend ret [list as $altname]
         }
      } else {
         lappend ret {*}$::g_loadedModuleAutoAltname($mod)
      }
   }
   return $ret
}

proc getLoadedAllModroot {mod} {
   set name_list [list $mod {*}[getLoadedAltname $mod]]
   # get module short name if it is loaded as fullpath and modulepath is used
   if {[isModuleFullPath $mod]} {
      set name [findModuleNameFromModulefile $mod]
      if {[string length $name]} {
         lappend name_list $name
      }
   }
   set mod_root_list {}
   foreach name $name_list {
      # mod root recorded lower case if icase is enabled
      lappendNoDup mod_root_list [getModuleRootFromVersSpecLowerIfIcase $name]
   }
   return $mod_root_list
}

# get all names of loaded module "mod" and set structure to find all root name
# this loaded module matches. use this information to more efficiently get
# matching loaded module: only fully test match with modules matching the root
# name of search query
proc setLoadedByModroot {mod} {
   set mod_root_list [getLoadedAllModroot $mod]
   foreach mod_root $mod_root_list {
      lappend ::g_loadedByModroot($mod_root) $mod
   }
   # set special structure to easily unset main one on module unload
   set ::g_modrootByLoaded($mod) $mod_root_list
}

proc getLoadedMatchingModroot {name} {
   # mod root recorded lower case if icase is enabled
   set mod_root [getModuleRootFromVersSpecLowerIfIcase $name]
   if {[info exists ::g_loadedByModroot($mod_root)]} {
      return $::g_loadedByModroot($mod_root)
   }
}

proc unsetLoadedByModroot {mod} {
   foreach mod_root $::g_modrootByLoaded($mod) {
      lrem ::g_loadedByModroot($mod_root) $mod
   }
   unset ::g_modrootByLoaded($mod)
}

proc setLoadedVariant {mod args} {
   lappend ::g_loadedModuleVariant($mod) {*}$args
}

proc unsetLoadedVariant {mod} {
   if {[info exists ::g_loadedModuleVariant($mod)]} {
      unset ::g_loadedModuleVariant($mod)
   }
}

proc getLoadedVariant {mod} {
   if {[info exists ::g_loadedModuleVariant($mod)]} {
      return $::g_loadedModuleVariant($mod)
   }
}

proc getLoadedModuleWithVariantList {} {
   set modvrlist [list]
   foreach mod [getEnvLoadedModulePropertyParsedList name] {
      set modvr [list $mod]
      set vrlist [getVariantList $mod 5]
      if {[llength $vrlist]} {
         lappend modvr {*}$vrlist
      }
      lappend modvrlist $modvr
   }
   return $modvrlist
}

proc getLoadedModuleWithVariantSaveTagArrayList {} {
   array set tag_arr {}
   foreach mod [getEnvLoadedModulePropertyParsedList name] {
      set modvr [list $mod]
      set vrlist [getVariantList $mod 1]
      if {[llength $vrlist]} {
         lappend modvr {*}$vrlist
      }
      # create entry in array only if tags set
      set tag_list [getSaveTagList $mod]
      if {[llength $tag_list]} {
         set tag_arr($modvr) $tag_list
      }
   }
   return [array get tag_arr]
}

proc getAndParseLoadedModuleWithVariant {mod} {
   set vr_list [getVariantList $mod 1]
   return [getAndParseModuleWithVariant $mod $vr_list]
}

proc getAndParseModuleWithVariant {mod vr_list} {
   if {[llength $vr_list]} {
      lassign [parseModuleSpecification 0 0 0 0 $mod {*}$vr_list] mod_vr
   } else {
      set mod_vr $mod
   }
   return $mod_vr
}

proc setLoadedUse {mod args} {
   lappendNoDup ::g_loadedModuleUse($mod) {*}$args
}

proc unsetLoadedUse {mod} {
   if {[info exists ::g_loadedModuleUse($mod)]} {
      unset ::g_loadedModuleUse($mod)
   }
}

proc getLoadedUse {mod} {
   if {[info exists ::g_loadedModuleUse($mod)]} {
      return $::g_loadedModuleUse($mod)
   }
}

proc getViaModuleForModulepath {modpath} {
   lassign [getAllLoadedModuleUsingModulepath $modpath] via
   if {![string length $via] && $modpath ni [getModulePathList]} {
      # get via information collected from spider processing
      set via [getModuleUsingModulepath $modpath]
   }
   return $via
}

proc getModuleUsingModulepath {modpath} {
   foreach mod [array names ::g_loadedModuleUse] {
      # no need to resolve variable reference in used path as this resolution
      # as already been performed when recording in global structure during
      # spider processing
      if {$modpath in $::g_loadedModuleUse($mod)} {
         return $mod
      }
   }
}

# Return all loaded module that enables given modulepath. Reference counter
# is checked to detect if modulepath was enabled prior loading the modules in
# which case modulepath is considered not enabled by loaded modules. modpath
# may not be currently enabled.
proc getAllLoadedModuleUsingModulepath {modpath} {
   set mod_list {}
   foreach mod [getEnvLoadedModulePropertyParsedList name] {
      if {$modpath in [resolvStringListWithEnv [getLoadedUse $mod]]} {
         lappend mod_list $mod
      }
   }
   set ref_count [getPathReferenceCount MODULEPATH $modpath [getState\
      path_separator] 1]
   if {$ref_count <= [llength $mod_list]} {
      return $mod_list
   }
}

proc unsetEnvLoadedModuleProperty {mod_name prop} {
   set prop_env_var [getLoadedModulePropertyEnvVarName $prop]
   set env_loaded_prop_list [getEnvLoadedModulePropertyList $prop]
   set mod_pattern_in_env_loaded_prop [escapeGlobChars $mod_name][getState\
      sub1_separator]*

   set mod_env_loaded_prop [lsearch -glob -inline $env_loaded_prop_list\
      $mod_pattern_in_env_loaded_prop]

   if {[string length $mod_env_loaded_prop]} {
      remove-path $prop_env_var $mod_env_loaded_prop
   }
}

proc setEnvLoadedModuleProperty {mod_name prop value_list} {
   set serialize_depth [getEnvLoadedModulePropertyStructDepth $prop]
   set serialize_proc serialize${serialize_depth}ModulePropertyValue
   set char_map_list [getEnvLoadedModulePropertyCharMapList $prop]
   set prop_env_var [getLoadedModulePropertyEnvVarName $prop]

   if {[llength $value_list]} {
      set serialized_value_list [$serialize_proc $mod_name $value_list\
         $char_map_list]
      append-path $prop_env_var $serialized_value_list
   }
}

proc getEnvLoadedModulePropertyStructDepth {prop} {
   switch -- $prop {
      file - init - modulepath - name - refresh {
         return 0Lvl
      }
      conflict - extratag - tag - use {
         return 1Lvl
      }
      altname - prereq - prereqpath - sourcesh - stickyrule - variant {
         return 2Lvl
      }
   }
}

proc getEnvLoadedModulePropertyCharUnmapList {prop} {
   set char_unmap_list {}
   foreach {char mapped} [getEnvLoadedModulePropertyCharMapList $prop] {
      lappend char_unmap_list $mapped $char
   }
   return $char_unmap_list
}

proc getEnvLoadedModulePropertyCharMapList {prop} {
   return [switch -- $prop {
      sourcesh {
         list [getState path_separator] <EnvModEscPS>\
            [getState sub1_separator] <EnvModEscS1>\
            [getState sub2_separator] <EnvModEscS2>
      }
      default {
         list : <
      }
   }]
}

proc serialize2LvlModulePropertyValue {mod structured_value_list\
   char_map_list} {
   set sub2_sepa [getState sub2_separator]
   set serialized_value_list [list]
   foreach structured_value $structured_value_list {
      set mapped_structured_value [string map $char_map_list\
         $structured_value]
      lappend serialized_value_list [join $mapped_structured_value $sub2_sepa]
   }
   # no character translation as it already occurred here
   return [serialize1LvlModulePropertyValue $mod $serialized_value_list {}]
}

proc serialize1LvlModulePropertyValue {mod structured_value_list\
   char_map_list} {
   set serialized_value [join [list $mod {*}$structured_value_list] [getState\
      sub1_separator]]
   return [string map $char_map_list $serialized_value]
}

proc unserialize2LvlModulePropertyValueList {serialized_value_list\
   char_unmap_list} {
   set lvl1_serialized_value_list [unserialize1LvlModulePropertyValueList\
      $serialized_value_list {}]
   set structured_value_list {}
   set sub2_sepa [getState sub2_separator]
   foreach lvl1_serialized_value $lvl1_serialized_value_list {
      set lvl1_strutured_value {}
      set first 1
      foreach lvl2_serialized_value $lvl1_serialized_value {
         # keep first element as string (module name)
         if {$first} {
            set lvl2_structured_value [string map $char_unmap_list\
               $lvl2_serialized_value]
            set first 0
         } else {
            set lvl2_structured_value {}
            foreach value [split $lvl2_serialized_value $sub2_sepa] {
               lappend lvl2_structured_value [string map $char_unmap_list\
                  $value]
            }
         }
         lappend lvl1_strutured_value $lvl2_structured_value
      }
      lappend structured_value_list $lvl1_strutured_value
   }
   return $structured_value_list
}

proc unserialize1LvlModulePropertyValueList {serialized_value_list\
   char_unmap_list} {
   set structured_value_list {}
   set sub1_sepa [getState sub1_separator]
   foreach serialized_value $serialized_value_list {
      set structured_value {}
      foreach value [split $serialized_value $sub1_sepa] {
         if {[string length $value]} {
            lappend structured_value [string map $char_unmap_list $value]
         }
      }
      # ignore empty element (1 is meaningless as first elt is loaded mod)
      if {[llength $structured_value] > 1} {
         lappend structured_value_list $structured_value
      }
   }
   return $structured_value_list
}

proc unserialize0LvlModulePropertyValueList {serialized_value_list\
   char_unmap_list} {
   set value_list {}
   foreach serialized_value $serialized_value_list {
      if {[string length $serialized_value]} {
         lappend value_list [string map $char_unmap_list $serialized_value]
      }
   }
   return $value_list

}

# get current loaded state to record it as the virtual init collection
proc getLoadedInit {} {
   set ret [formatCollectionContent [getModulePathList returnempty 0]\
      [getLoadedModuleWithVariantList]\
      [getLoadedModuleWithVariantSaveTagArrayList] {}]

   # remove ending newline in collection output
   set ret [string trimright $ret \n]

   # get init state as a string that can be registered in an env var translate
   # tag list separator ':' into '<' and line split '\n' into ':'
   return [string map {: < \n :} $ret]
}

# get all modules from all enabled modulepaths that matches a specification
proc getAllAvailModule {mod} {
   array set mod_list {}
   # search is done from lowest to greatest priority path (if result array
   # content is kept later on, it will hold accurate priority information)
   foreach dir [lreverse [getModulePathList]] {
      array set mod_list [getModules $dir $mod 0 [list rc_defs_included]]
   }
   return [array names mod_list]
}

# register conflict violation state between loaded modules
proc setModuleConflictViolation {mod modconlist} {
   reportDebug "set conflict violation state for '$mod'"
   set ::g_conflictViolation($mod) $modconlist
   # also update violation state for loaded mod conflicting with mod
   foreach lmmod $modconlist {
      if {[lappendNoDup ::g_conflictViolation($lmmod) $mod]} {
         reportDebug "set/update conflict violation state for '$lmmod'"
      }
   }
}

# unregister conflict violation state between modules
proc unsetModuleConflictViolation {mod} {
   if {[info exists ::g_conflictViolation($mod)]} {
      # also update violation state for loaded mod conflicting with mod
      foreach lmmod $::g_conflictViolation($mod) {
         set convio [replaceFromList\
            $::g_conflictViolation($lmmod) $mod]
         reportDebug "unset/update conflict violation state for '$lmmod'"
         if {![llength $convio]} {
            unset ::g_conflictViolation($lmmod)
         } else {
            set ::g_conflictViolation($lmmod) $convio
         }
      }
      reportDebug "unset conflict violation state for '$mod'"
      unset ::g_conflictViolation($mod)
   }
}

# build dependency chain between loaded modules based on registered prereqs
proc setModuleDependency {mod} {
   set deplist {}
   set depnpolist {}

   foreach prereq_match_aftmatch [getLoadedModulePrereqListAndLoadedMatch\
      $mod] {
      set prereq_item_match_aftmatch_list [lassign $prereq_match_aftmatch\
         prereq prereq_path_list]

      set lmprelist {}
      set lmnpolist {}
      foreach {prereq_mod_item bef_loaded_mod_match aft_loaded_mod_match}\
         $prereq_item_match_aftmatch_list {
         if {[string length $bef_loaded_mod_match]} {
            lappendNoDup lmprelist $bef_loaded_mod_match
            lappendNoDup lmnpolist $bef_loaded_mod_match
         } else {
            reportDebug "set an unmet requirement on '$prereq_mod_item' for\
               '$mod'"
            lappend ::g_moduleUnmetDep($mod) $prereq_mod_item
            lappend ::g_unmetDepHash($prereq_mod_item) $mod $prereq_path_list
         }

         # is requirement loaded after mod (in *No Particular Order*)
         if {[string length $aft_loaded_mod_match]} {
            lappendNoDup lmnpolist $aft_loaded_mod_match
         }
      }

      switch -- [llength $lmprelist] {
         0 {
            # prereq not satisfied
            reportDebug "set prereq violation state for '$mod'"
            lappend ::g_prereqViolation($mod) $prereq
         }
         1 {
            set lmmod [lindex $lmprelist 0]
            lappend deplist [list $lmmod]
            # set 'is depended by' relations
            lappend ::g_dependHash($lmmod) [list $mod]
         }
         default {
            lappend deplist $lmprelist
            # many modules in prereq list, means they all set an optional dep
            foreach lmmod $lmprelist {
               lappend ::g_dependHash($lmmod) [list $mod 1]
            }
         }
      }

      # build 'is depended by' relations not taking loading order into account
      switch -- [llength $lmnpolist] {
         0 {
            # even on No Particular Order mode, prereq is not satisfied
            reportDebug "set NPO prereq violation state for '$mod'"
            lappend ::g_prereqNPOViolation($mod) $prereq
         }
         1 {
            set lmmod [lindex $lmnpolist 0]
            lappend depnpolist [list $lmmod]
            # set 'is depended by' relations
            lappend ::g_dependNPOHash($lmmod) [list $mod]
         }
         default {
            lappend depnpolist $lmnpolist
            # many modules in prereq list, means they all set an optional dep
            foreach lmmod $lmnpolist {
               lappend ::g_dependNPOHash($lmmod) [list $mod 1]
            }
         }
      }
   }

   # conflict not satisfied
   set modconlist [getModuleLoadedConflict $mod]
   if {[llength $modconlist]} {
      setModuleConflictViolation $mod $modconlist
   }

   # update eventual registered unmet dependencies
   foreach modpre [array names ::g_unmetDepHash] {
      if {[modEq $modpre $mod eqstart 1 2 1]} {
         reportDebug "refresh requirements targeting '$modpre'"
         foreach {lmmod prereq_path_list} $::g_unmetDepHash($modpre) {
            if {![isLoadedMatchSpecificPath $mod $prereq_path_list]} {
               continue
            }
            if {$mod in [getDependentLoadedModuleList [list $lmmod] 0 0]} {
               reportDebug "skip deps refresh for '$lmmod' as dep cycle\
                  detected with '$mod'"

               # remove dependency link in no particular order structs to
               # avoid cycle first in 'is depended by' struct
               if {[info exists ::g_dependNPOHash($mod)]} {
                  set depmodlist $::g_dependNPOHash($mod)
                  for {set i 0} {$i < [llength $depmodlist]} {incr i 1} {
                     if {[lindex [lindex $depmodlist $i] 0] eq $lmmod} {
                        set depmodlist [lreplace $depmodlist $i $i]
                        break
                     }
                  }
                  set ::g_dependNPOHash($mod) $depmodlist
                  reportDebug "update NPO dependent of '$mod' to\
                     '$depmodlist'"
               }
               # then update 'depend on' struct
               set lmmoddepnpolist {}
               foreach depmodlist $::g_moduleNPODepend($lmmod) {
                  if {[set depidx [lsearch -exact $depmodlist $mod]] != -1} {
                     set depmodlist [lreplace $depmodlist $depidx $depidx]
                     # implies to update consistently alternate requirement or
                     # violation state if no alternative loaded
                     switch -- [llength $depmodlist] {
                        0 {
                           # do not know exact prereq name, so use correspond.
                           # loaded module matching it
                           lappend ::g_prereqNPOViolation($lmmod) $mod
                           reportDebug "set NPO prereq violation state for\
                              '$lmmod'"
                        }
                        1 {
                           # update alternate loaded mod which became a strong
                           # requirement
                           set altmod [lindex $depmodlist 0]
                           set ::g_dependNPOHash($altmod) [replaceFromList\
                              $::g_dependNPOHash($altmod) [list $lmmod 1]\
                              $lmmod]
                           reportDebug "update NPO dependent of '$altmod' to\
                              '$::g_dependNPOHash($altmod)'"
                        }
                     }
                  }
                  lappend lmmoddepnpolist $depmodlist
               }
               reportDebug "update NPO requirement of '$lmmod' to\
                  '$lmmoddepnpolist'"
               set ::g_moduleNPODepend($lmmod) $lmmoddepnpolist
            } else {
               # refresh actual dependencies of targeting mod
               unsetModuleDependency $lmmod
               setModuleDependency $lmmod
            }
         }
      }
   }

   # set 'depends on' relation
   reportDebug "set requirements of '$mod' to '$deplist'"
   set ::g_moduleDepend($mod) $deplist
   reportDebug "set NPO requirements of '$mod' to '$depnpolist'"
   set ::g_moduleNPODepend($mod) $depnpolist
}

# update dependency chain when unloading module
proc unsetModuleDependency {mod} {
   foreach lmmodlist $::g_moduleDepend($mod) {
      set manymod [expr {[llength $lmmodlist] > 1}]

      # unset 'is depended by' mod relations
      foreach lmmod $lmmodlist {
         if {[info exists ::g_dependHash($lmmod)]} {
            if {$manymod} {
               set hashdep [list $mod 1]
            } else {
               set hashdep [list $mod]
            }
            lrem ::g_dependHash($lmmod) $hashdep
            if {![llength $::g_dependHash($lmmod)]} {
               unset ::g_dependHash($lmmod)
            }
         }
      }
   }
   # unset mod's 'depends on' relation
   reportDebug "unset requirements of '$mod'"
   unset ::g_moduleDepend($mod)

   foreach lmmodlist $::g_moduleNPODepend($mod) {
      set manymod [expr {[llength $lmmodlist] > 1}]

      # unset 'is depended by' mod relations
      foreach lmmod $lmmodlist {
         if {[info exists ::g_dependNPOHash($lmmod)]} {
            if {$manymod} {
               set hashdep [list $mod 1]
            } else {
               set hashdep [list $mod]
            }
            lrem ::g_dependNPOHash($lmmod) $hashdep
            if {![llength $::g_dependNPOHash($lmmod)]} {
               unset ::g_dependNPOHash($lmmod)
            }
         }
      }
   }
   # unset mod's No Particular Order 'depends on' relation
   reportDebug "unset NPO requirements of '$mod'"
   unset ::g_moduleNPODepend($mod)

   # unset eventual violation states
   if {[info exists ::g_prereqViolation($mod)]} {
      reportDebug "unset prereq violation state for '$mod'"
      unset ::g_prereqViolation($mod)
   }
   if {[info exists ::g_prereqNPOViolation($mod)]} {
      reportDebug "unset NPO prereq violation state for '$mod'"
      unset ::g_prereqNPOViolation($mod)
   }
   unsetModuleConflictViolation $mod

   # unset eventual registered unmet dependencies
   if {[info exists ::g_moduleUnmetDep($mod)]} {
      foreach ummod $::g_moduleUnmetDep($mod) {
         if {[info exists ::g_unmetDepHash($ummod)]} {
            set idx [lsearch -exact $::g_unmetDepHash($ummod) $mod]
            set ::g_unmetDepHash($ummod) [lreplace $::g_unmetDepHash($ummod)\
               $idx $idx+1]
            if {![llength $::g_unmetDepHash($ummod)]} {
               unset ::g_unmetDepHash($ummod)
            }
         }
      }
      reportDebug "unset unmet requirements for '$mod'"
      unset ::g_moduleUnmetDep($mod)
   }

   # unset mod's 'is depended by' relations
   set hashdeplist [getDirectDependentList $mod]
   if {[llength $hashdeplist]} {
      reportDebug "refresh dependent of '$mod'"
      foreach lmmod $hashdeplist {
         # refresh actual dependencies of targeting mod
         unsetModuleDependency $lmmod
         setModuleDependency $lmmod
      }
   }
}

# get from provided loaded module list the one before and the one after
# provided loaded position. loaded before will be the lastly loaded before or
# the firstly loaded before, depending on ret_last_bef argument
proc getLoadedBeforeAndAfter {loaded_mod_list mod_idx ret_last_bef} {
   set bef_mod {}
   set aft_mod {}
   foreach loaded_mod $loaded_mod_list {
      set loaded_mod_idx [getLoadedModulePosition $loaded_mod]
      # if mod is loading (idx=-1), no after mod match
      # if mod has a requirement on itself, add it to the before list
      if {$mod_idx == -1 || $loaded_mod_idx <= $mod_idx} {
         # record first or last loaded before mod (depends on ret_last_bef)
         if {![info exists bef_idx] ||\
            ($ret_last_bef && $loaded_mod_idx > $bef_idx) ||\
            (!$ret_last_bef && $loaded_mod_idx < $bef_idx)} {
            set bef_mod $loaded_mod
            set bef_idx $loaded_mod_idx
         }
      } else {
         # record first loaded after mod
         if {![info exists aft_idx] || $loaded_mod_idx < $aft_idx} {
            set aft_mod $loaded_mod
            set aft_idx $loaded_mod_idx
         }
      }
   }
   return [list $bef_mod $aft_mod]
}

# return the list of prereqs of a loaded or loading module and the associated
# loaded module corresponding to these prereq definitions. The list of each
# prereq is returned, each entry is a list of each prereq item definition
# associated to the matching module loaded prior passed mod and loaded after
proc getLoadedModulePrereqListAndLoadedMatch {mod} {
   set prereq_match_aftmatch_list {}
   set prereq_list [getLoadedPrereq $mod]

   set via_mod_list {}
   if {[getConf require_via]} {
      set modpath [getModulepathFromLoadedOrLoadingModule $mod]
      set via_mod_list [getAllLoadedModuleUsingModulepath $modpath]
   }

   # skip processing if no prereq defined
   if {![llength $prereq_list] && ![llength $via_mod_list]} {
      return
   }

   set mod_idx [getLoadedModulePosition $mod]
   # do we need lastly loaded before or firsly loaded before
   set ret_last_bef [expr {[getConf unload_match_order] eq {returnlast}}]

   foreach prereq $prereq_list {
      set prereq_path_list [getLoadedPrereqPath $mod $prereq]
      set prereq_match_aftmatch [list $prereq $prereq_path_list]

      foreach prereq_mod_item $prereq {
         # get all loaded modules matching requirement
         set loaded_mod_match_list {}
         # compare with loaded mods matching root instead of all loaded mods
         foreach loaded_mod [getLoadedMatchingModroot $prereq_mod_item] {
            if {[isLoadedMatchSpecificPath $loaded_mod $prereq_path_list] &&\
               [modEq $prereq_mod_item $loaded_mod eqstart 1 2 1]} {
               lappend loaded_mod_match_list $loaded_mod
            }
         }
         # find before and after matching loaded mod
         lassign [getLoadedBeforeAndAfter $loaded_mod_match_list $mod_idx\
            $ret_last_bef] bef_loaded_mod_match aft_loaded_mod_match

         lappend prereq_match_aftmatch $prereq_mod_item $bef_loaded_mod_match\
            $aft_loaded_mod_match
      }

      lappend prereq_match_aftmatch_list $prereq_match_aftmatch
   }

   # add via module requirement if enabled and if any
   if {[llength $via_mod_list]} {
      lassign [getLoadedBeforeAndAfter $via_mod_list $mod_idx $ret_last_bef]\
         bef_loaded_mod_match aft_loaded_mod_match

      # use "<VIA>" string as prereq specification, this value is used for
      # unsatisfied requirement, which does not exist for via requirement
      lappend prereq_match_aftmatch_list [list <VIA> {} <VIA>\
         $bef_loaded_mod_match $aft_loaded_mod_match]
   }

   return $prereq_match_aftmatch_list
}

# returns if any loaded module (if passed mod is empty) or passed mod and all
# its requirement chain satisfy their loading constraints (prereq & conflict)
proc areModuleConstraintsSatisfied {{mod {}} {nporeq 0}} {
   set ret 1

   # are requirements loaded after their dependent included or not
   if {$nporeq} {
      set reqVioVar ::g_prereqNPOViolation
      set reqListVar ::g_moduleNPODepend
   } else {
      set reqVioVar ::g_prereqViolation
      set reqListVar ::g_moduleDepend
   }

   # check if any loaded module violates its prereq or conflict constraints
   ##nagelfar vartype reqVioVar varName
   if {$mod eq {}} {
      if {[array size ::g_conflictViolation] || [array size $reqVioVar]} {
         set ret 0
      }
   } else {
      set fulllist [list $mod]
      for {set i 0} {$i < [llength $fulllist]} {incr i 1} {
         set depmod [lindex $fulllist $i]

         # check if depmod violates its prereq or conflict constraints
         ##nagelfar ignore +2 Suspicious variable name
         if {[info exists ::g_conflictViolation($depmod)] || [info exists\
            ${reqVioVar}($depmod)]} {
            # found violation among the requirement chain of mod so the
            # constraint of mod are not satisfied
            set ret 0
            break
         }
         # add requirements of depmod to the module to check list
         ##nagelfar ignore #2 Suspicious variable name
         if {[info exists ${reqListVar}($depmod)]} {
            foreach lmmodlist [set ${reqListVar}($depmod)] {
               lappendNoDup fulllist {*}$lmmodlist
            }
         }
      }
   }

   return $ret
}

# parse loaded modules information (should be called only once)
proc cacheCurrentModules {} {
   # mark specific as well as generic modules as loaded
   set i 0
   set modfilelist [getEnvLoadedModulePropertyParsedList file]
   set modlist [getEnvLoadedModulePropertyParsedList name]
   set refreshlist [getEnvLoadedModulePropertyParsedList refresh]

   if {[llength $modlist] == [llength $modfilelist]} {
      # cache declared variant of loaded modules
      foreach modvrspec [getEnvLoadedModulePropertyParsedList variant] {
         setLoadedVariant {*}$modvrspec
         # prepare modvr designation of loaded mod needed in next steps
         set mod [lindex $modvrspec 0]
         set vrlist [getVariantList $mod 6]
         set modvr [list $mod {*}$vrlist]
         set modvrarr($mod) $modvr
      }

      # cache declared tags of loaded modules
      foreach modtag [getEnvLoadedModulePropertyParsedList tag] {
         set tag_list [lassign $modtag mod]
         if {[info exists modvrarr($mod)]} {
            set mod_with_vr $modvrarr($mod)
         } else {
            set mod_with_vr {}
         }
         setModuleAndVariantsTag $mod $mod_with_vr {*}$tag_list
      }
      foreach modtag [getEnvLoadedModulePropertyParsedList extratag] {
         set tag_list [lassign $modtag mod]
         if {[info exists modvrarr($mod)]} {
            set mod_with_vr $modvrarr($mod)
         } else {
            set mod_with_vr {}
         }
         setModuleAndVariantsExtraTag $mod $mod_with_vr {*}$tag_list
      }
      foreach modstickyrule [getEnvLoadedModulePropertyParsedList\
         stickyrule] {
         set mod [lindex $modstickyrule 0]
         foreach modtagspeclist [lrange $modstickyrule 1 end] {
            set modspec_list [lassign $modtagspeclist modtag]
            foreach modspec $modspec_list {
               lassign [parseModuleSpecification 0 0 0 0 {*}$modspec]\
                  parsed_modspec
               # record tag definition on given module specification
               setModspecTag $parsed_modspec $modtag
            }
         }
      }

      # cache declared alternative names of loaded modules
      foreach modalt [getEnvLoadedModulePropertyParsedList altname] {
         setLoadedAltname {*}$modalt
      }

      # cache declared source-sh of loaded modules
      foreach modsrcsh [getEnvLoadedModulePropertyParsedList sourcesh] {
         setLoadedSourceSh {*}$modsrcsh
      }

      # cache declared conflict of loaded modules
      foreach modcon [getEnvLoadedModulePropertyParsedList conflict] {
         # parse module version specification to record translation
         foreach modconelt [lrange $modcon 1 end] {
            parseModuleSpecification 0 0 0 0 {*}$modconelt
         }
         setLoadedConflict {*}$modcon
      }

      # cache declared prereq of loaded modules, prior to setLoadedModule
      # which triggers dependency chain build
      foreach modpre [getEnvLoadedModulePropertyParsedList prereq] {
         # parse module version specification to record translation
         foreach modpreeltlist [lrange $modpre 1 end] {
            foreach modpreelt $modpreeltlist {
               parseModuleSpecification 0 0 0 0 {*}$modpreelt
            }
         }
         setLoadedPrereq {*}$modpre
      }
      foreach modpre_path [getEnvLoadedModulePropertyParsedList prereqpath] {
         setLoadedPrereqPath {*}$modpre_path
      }

      foreach moduse [getEnvLoadedModulePropertyParsedList use] {
         setLoadedUse {*}$moduse
      }

      foreach mod $modlist {
         # get all tags also recorded on mod and vr designation
         if {[info exists modvrarr($mod)]} {
            set modvr $modvrarr($mod)
         } else {
            set modvr {}
         }
         setLoadedModule $mod [lindex $modfilelist $i] [expr\
            {![isModuleTagged $mod auto-loaded 1]}] $modvr [expr {$mod in\
            $refreshlist}] 0
         incr i
      }

      # all positions and mod root search structure are required prior
      # building dependency chains
      foreach mod $modlist {
         setModuleDependency $mod
      }

      reportDebug "$i loaded"
   } else {
      reportErrorAndExit "Loaded environment state is\
         inconsistent\nLOADEDMODULES=$modlist\n_LMFILES_=$modfilelist"
   }
}

# This proc resolves module aliases or version aliases to the real module name
# and version.
proc resolveModuleVersionOrAlias {name icase} {
   set name [getArrayKey ::g_moduleResolved $name $icase]
   if {[info exists ::g_moduleResolved($name)]} {
      set ret $::g_moduleResolved($name)
   } else {
      set ret $name
   }

   reportTrace "'$name' into '$ret'" Resolve
   return $ret
}

proc parseAccessIssue {modfile} {
   # retrieve and return access issue message
   if {[regexp {POSIX .* \{(.*)\}$} $::errorCode match errMsg]} {
      return "[string totitle $errMsg] on '$modfile'"
   } else {
      return "Cannot access '$modfile'"
   }
}

proc checkValidModule {modfile} {
   # test file only once, cache result obtained to minimize file query
   # consider modfile valid without reading it if mcookie_check < always
   return [expr {[info exists ::g_modfileValid($modfile)]\
      ? $::g_modfileValid($modfile)\
      : [set ::g_modfileValid($modfile) [expr {[getConf mcookie_check] eq\
         {always} ? [getModuleValidy $modfile] : [list true {}]}]]}]
}

# get file modification time, cache it at first query, use cache afterward
proc getFileMtime {fpath} {
   if {[info exists ::g_fileMtime($fpath)]} {
      return $::g_fileMtime($fpath)
   } else {
      # protect 'file mtime' call in case we do not know what we are checking
      # when mcookie is not checked
      if {[catch {
         set mtime [file mtime $fpath]
      } errMsg ]} {
         reportError [parseAccessIssue $fpath]
         set mtime {}
      }
      return [set ::g_fileMtime($fpath) $mtime]
   }
}

# define proc that will be used as fallback to command provided by extension
# library in case this library is not loaded
proc __readFile {filename {firstline 0} {must_have_cookie 0}} {
   set fid [open $filename r]
   if {$firstline} {
      set fdata [gets $fid]
   } else {
      # read a first data chunk and check if magic cookie is there if
      # mandatory. skip read of any additional content if mandatory cookie is
      # not found
      set fdata [read $fid 4096]
      if {![eof $fid] && (!$must_have_cookie || [string equal -length 8\
         $fdata {#%Module}])} {
         append fdata [read $fid]
      }
   }
   close $fid
   return $fdata
}

proc getModuleValidy {modfile} {
   if {[catch {lassign [getModuleHeaderAndContent $modfile 1] header}]} {
      set msg [parseAccessIssue $modfile]
      set valid accesserr
   } else {
      lassign [getModuleHeaderValidity $header] valid msg
   }
   return [list $valid $msg]
}

proc getModuleHeaderAndContent {modfile {only_get_header 0}} {
   if {[info exists ::g_modfileContent($modfile)]} {
      set res $::g_modfileContent($modfile)
   } else {
      # only read beginning of file if just checking validity and not asked to
      # always fully read files. when full file should be read cookie is
      # checked if asked to avoid to fully read non modfile
      set content [readFile $modfile [expr {$only_get_header &&\
         ![currentState always_read_full_file]}] 1]
      # extract magic cookie (first word of modulefile)
      set header [string trimright [lindex [split [string range $content 0\
         32]] 0] #]
      set res [list $header $content]
      # cache full file read to minimize file operations
      if {!$only_get_header || [currentState always_read_full_file]} {
         set ::g_modfileContent($modfile) $res
      }
   }
   return $res
}

proc getModuleHeaderValidity {header} {
   if {![string equal -length 8 $header {#%Module}]} {
      set msg {Magic cookie '#%Module' missing}
      set valid invalid
   # check if specified min version requirement is met
   } elseif {[string length $header] > 8 && [getConf mcookie_version_check]\
      && [versioncmp [getState modules_release] [string range $header 8 end]]\
      < 0} {
      set msg "Modulefile requires at least Modules version [string range\
         $header 8 end]"
      set valid invalid
   } else {
      set msg {}
      set valid true
   }
   return [list $valid $msg]
}

proc getModuleContent {mod_file} {
   if {[catch {lassign [getModuleHeaderAndContent $mod_file] mod_header\
      mod_content}]} {
      error [parseAccessIssue $mod_file] {} MODULES_ERR_READ
   }
   # raise error if module is not valid
   lassign [getModuleHeaderValidity $mod_header] mod_valid valid_msg
   if {$mod_valid ne {true}} {
      error $valid_msg {} MODULES_ERR_VALIDITY
   }
   return $mod_content
}

# If given module maps to default or other symbolic versions, a list of
# those versions is returned. This takes module/version as an argument.
proc getVersAliasList {mod} {
   set sym_list {}
   if {[info exists ::g_symbolHash($mod)]} {
      set sym_list $::g_symbolHash($mod)
      # withdraw hidden symbol from list
      if {[info exists ::g_hiddenSymHash($mod)]} {
         lassign [getDiffBetweenList $sym_list $::g_hiddenSymHash($mod)]\
            sym_list
      }
   }

   reportDebug "'$mod' has symbolic version list '$sym_list'"
   return $sym_list
}

proc doesModuleHaveSym {mod} {
   # is there any non-hidden symbol for mod
   return [expr {[info exists ::g_symbolHash($mod)] && (![info exists\
      ::g_hiddenSymHash($mod)] || [llength [lindex [getDiffBetweenList\
      $::g_symbolHash($mod) $::g_hiddenSymHash($mod)] 0]])}]
}

# get list of elements located in a directory passed as argument. a flag is
# set after each element to know if it is considered hidden or not. a
# fetch_dotversion argument controls whether .version file should be looked at
# in directory .proc will be used as a fallback to command provided by
# extension library
proc __getFilesInDirectory {dir fetch_dotversion} {
   set dir_list [list]

   set elt_list [glob -nocomplain -directory $dir *]

   # Add each element in the current directory to the list
   foreach elt $elt_list {
      lappend dir_list $elt 0 [file isdirectory $elt]
   }

   # search for hidden files
   foreach elt [glob -nocomplain -types hidden -directory $dir -tails *] {
      switch -- $elt {
         . - .. { }
         .modulerc - .version {
            if {($fetch_dotversion || $elt ne {.version}) && [file readable\
               $dir/$elt]} {
               lappend dir_list $dir/$elt 0 0
            }
         }
         default {
            lappend dir_list $dir/$elt 1 [file isdirectory $dir/$elt]
         }
      }
   }

   return $dir_list
}

# check if an existing findModules cache entry matches current search by
# evaluating search ids. if an exact match cannot be found, look at saved
# searches that contains current search (superset of looked elements), extra
# elements will be filtered-out by GetModules
proc findModulesInMemCache {searchid} {
   # exact same search is cached
   if {[info exists ::g_foundModulesMemCache($searchid)]} {
      set match_searchid $searchid
      set mod_list $::g_foundModulesMemCache($searchid)
   # look for a superset search
   } else {
      set match_searchid {}
      set mod_list {}
      foreach cacheid [array names ::g_foundModulesMemCache] {
         # cache id acts as pattern to check if it contains current search
         if {[string match $cacheid $searchid]} {
            set match_searchid $cacheid
            set mod_list $::g_foundModulesMemCache($cacheid)
            break
         }
      }
   }

   return [list $match_searchid $mod_list]
}

# Walk through provided list of directories and files to find modules
proc findModulesFromDirsAndFiles {dir full_list depthlvl fetch_mtime\
   res_arrname {indir_arrname {}} {hidden_listname {}} {fknown_arrname {}}\
   {dknown_arrname {}}} {
   # link to variables/arrays from upper context
   upvar $res_arrname mod_list
   if {$indir_arrname ne {}} {
      upvar $indir_arrname modfile_indir
   }
   if {$hidden_listname ne {}} {
      upvar $hidden_listname hidden_list
   }
   if {$fknown_arrname ne {}} {
      upvar $fknown_arrname fknown_arr
   }
   if {$dknown_arrname ne {}} {
      upvar $dknown_arrname dknown_arr
   }

   foreach igndir [getConf ignored_dirs] {
      set ignored_dirs($igndir) 1
   }
   array set mod_list {}
   for {set i 0} {$i < [llength $full_list]} {incr i 1} {
      set element [lindex $full_list $i]
      set tail [file tail $element]
      set modulename [getModuleNameFromModulepath $element $dir]
      set parentname [file dirname $modulename]
      set moddepthlvl [llength [file split $modulename]]
      # check if element is a directory if we do not already know if it is a
      # dir or a file from transmitted structures
      if {[info exists dknown_arr($modulename)] || (![info exists\
         fknown_arr($modulename)] && [file isdirectory $element])} {
         if {![info exists ignored_dirs($tail)]} {
            if {[catch {
               set elt_list [getFilesInDirectory $element 1]
            } errMsg]} {
               set mod_list($modulename) [list accesserr [parseAccessIssue\
                  $element] $element]
            } else {
               # Add each element in the current directory to the list
               foreach {fpelt hid isdir} $elt_list {
                  lappend full_list $fpelt
                  # Flag hidden files
                  if {$hid} {
                     set hidden_list($fpelt) 1
                  }
                  # Record file type to avoid later stat calls
                  set fpeltname [getModuleNameFromModulepath $fpelt $dir]
                  if {$isdir} {
                     set dknown_arr($fpeltname) 1
                  } else {
                     set fknown_arr($fpeltname) 1
                  }
               }
            }
         }
      } else {
         switch -glob -- $tail {
            .modulerc {
               set mod_list($modulename) [list modulerc]
            }
            .version {
               # skip .version file from different depth level than search
               # targets if no in depth mode is enabled
               if {$depthlvl == 0 || $moddepthlvl == $depthlvl} {
                  set mod_list($modulename) [list modulerc]
               }
            }
            .modulecache - *~ - *,v - \#*\# { }
            default {
               # skip modfile in no in depth mode search if it does not relate
               # to targeted depth level and one valid modfile has already be
               # found for the dirs lying at other depth level
               if {$depthlvl == 0 || $moddepthlvl == $depthlvl || ![info\
                  exists modfile_indir($parentname)]} {
                  lassign [checkValidModule $element] check_valid check_msg
                  switch -- $check_valid {
                     true {
                        set mtime [expr {$fetch_mtime ? [getFileMtime\
                           $element] : {}}]
                        set mod_list($modulename) [list modulefile $mtime\
                           $element]

                        # a valid modfile has been found in directory
                        if {![info exists hidden_list($element)]} {
                           set modfile_indir($parentname) 1
                        }
                     }
                     default {
                        # register check error and relative message to get it
                        # in case of direct access of this module element, but
                        # no registering in parent directory structure as
                        # element is not valid
                        set mod_list($modulename) [list $check_valid\
                           $check_msg $element]
                     }
                  }
               }
            }
         }
      }
   }
}

# finds all module-related files matching mod in the module path dir
proc findModules {dir mod depthlvl fetch_mtime} {
   reportDebug "finding '$mod' in $dir (depthlvl=$depthlvl,\
      fetch_mtime=$fetch_mtime)"

   # generated search id (for cache search/save) by compacting given args
   set searchid $dir:$mod:$depthlvl:$fetch_mtime

   # look at memory cache for a compatible result
   lassign [findModulesInMemCache $searchid] cache_searchid cache_list
   if {$cache_searchid ne {}} {
      reportDebug "use cache entry '$cache_searchid'"
      return $cache_list
   }

   # look at modulepath cache file
   lassign [findModulesInCacheFile $dir $mod $depthlvl $fetch_mtime] cache_ok\
      cache_list
   if {$cache_ok} {
      # record cache file findinds in memory cache
      reportDebug "create cache entry '$searchid'"
      set ::g_foundModulesMemCache($searchid) $cache_list
      return $cache_list
   }

   defineModEqStaticProc [isIcase] [getConf extended_default] $mod

   # every entries are requested
   set findall [expr {$mod eq {} || $mod eq {*}}]

   # use catch protection to handle non-readable and non-existent dir
   if {[catch {
      set full_list {}
      array set init_fknown {}
      array set init_dknown {}
      foreach {fpelt hid isdir} [getFilesInDirectory $dir 0] {
         set elt [file tail $fpelt]
         # include any .modulerc file found at the modulepath root
         if {$elt eq {.modulerc} || $findall || [modEqStatic $elt match]} {
            lappend full_list $fpelt
            # record file type to avoid later stat calls
            set eltname [getModuleNameFromModulepath $fpelt $dir]
            if {$isdir} {
               set init_dknown($eltname) 1
            } else {
               set init_fknown($eltname) 1
            }
         }
      }
   }]} {
      return {}
   }

   # walk through list of dirs and files to find modules
   findModulesFromDirsAndFiles $dir $full_list $depthlvl $fetch_mtime \
      mod_list {} {} init_fknown init_dknown

   reportDebug "found [array names mod_list]"

   # cache search results
   reportDebug "create cache entry '$searchid'"
   set found_list [array get mod_list]
   set ::g_foundModulesMemCache($searchid) $found_list

   return $found_list
}

proc getModules {dir {mod {}} {fetch_mtime 0} {search {}} {filter {}}} {
   global g_sourceAlias g_sourceVersion g_sourceVirtual g_rcAlias\
      g_moduleAlias g_rcVersion g_moduleVersion g_rcVirtual g_moduleVirtual\
      g_rcfilesSourced

   reportDebug "get '$mod' in $dir (fetch_mtime=$fetch_mtime, search=$search,\
      filter=$filter)"

   # generated search id (for cache search/save) by compacting given args
   set searchid $dir:$mod:$fetch_mtime:$search:$filter

   # look at memory cache for a compatible result
   if {[info exists ::g_gotModulesMemCache($searchid)]} {
      reportDebug "use cache entry '$searchid'"
      return $::g_gotModulesMemCache($searchid)
   }

   # extract one module name from query
   set modqe [getOneModuleFromVersSpec $mod]

   # perform an in depth search or not
   set indepth [expr {{noindepth} ni $search}]

   # set a default if none defined on directory entries
   set implicitdfl [getConf implicit_default]

   # automatically define latest and default sym for all modules
   # disable when implicit default or advanced version spec are disabled or
   # if search query does not contain a module name and version but variant
   set autosymbol [expr {$implicitdfl && [getConf advanced_version_spec] &&\
      ![isSpecWildWithVariant $mod]}]

   # match passed name against any part of avail module names
   set contains [expr {{contains} in $search}]
   set mtest [expr {$contains ? {matchin} : {match}}]

   set icase [isIcase]

   set wild [expr {{wild} in $search}]

   # will only keep default or latest elts in the end or remove plain dirs
   set filtering [expr {$filter eq {noplaindir}}]
   set keeping [expr {!$filtering && $filter ne {}}]

   # check search query string corresponds to directory
   set querydir [string trimright $modqe *]
   set isquerydir [expr {[string index $querydir end] eq {/}}]
   set querydir [string trimright $querydir /]
   set querydepth [countChar $modqe /]

   # get directory relative to module name
   set moddir [getModuleNameFromVersSpec $mod]
   set hasmoddir [expr {$moddir ne {.}}]
   set modroot [getModuleRootFromVersSpec $mod]

   # get all in case of contains search or if provided-aliases are included
   set find_all [expr {$contains || [isEltInReport provided-alias 0]}]

   set earlyfilter [expr {!$find_all && !$wild && $modroot eq [string\
      map {* {} ? {}} $modroot]}]

   # are result entries gathered in a resolution context ?
   set resctx [expr {{resolve} in $search}]

   # need to perform an extra match search?
   set ems_required [isExtraMatchSearchRequired $mod]

   # if search for global or user rc alias only, no dir lookup is performed
   # and aliases from g_rcAlias are returned
   if {{rc_alias_only} in $search} {
      set add_rc_defs 1
      array set found_list {}
   } else {
      # find modules by searching mod root name in order to catch all module
      # related entries to correctly computed auto symbols afterward

      if {$find_all} {
         set findmod *
      } else {
         set findmod $modroot
         # if searched mod is an empty or flat element append wildcard
         # character to match anything starting with mod
         if {$wild && !$hasmoddir && [string index $findmod end] ne {*}} {
            append findmod *
         }
      }

      # add alias/version definitions from global or user rc to result
      set add_rc_defs [expr {{rc_defs_included} in $search}]

      # if no indepth mode search, pass the depth level of the search query
      # unless EMS need to be performed (findModules should fetch everything)
      set depthlvl [expr {$indepth || $ems_required ? 0 : $querydepth + 1}]

      array set found_list [findModules $dir $findmod $depthlvl $fetch_mtime]
   }

   # Phase #1: consolidate every kind of entries (directory, modulefile,
   # symbolic version, alias and virtual module) in found_list

   array set err_list {}
   array set versmod_list {}

   foreach elt [lsort [array names found_list]] {
      switch -- [lindex $found_list($elt) 0] {
         modulerc {
            # process rc files them remove them from found_list
            if {![info exists g_rcfilesSourced($dir/$elt)]} {
               execute-modulerc $dir/$elt $elt $elt
               # Keep track of already sourced rc files not to run them again
               set g_rcfilesSourced($dir/$elt) 1
            }
            unset found_list($elt)
         }
         modulefile {
         }
         default {
            # flag entries with error
            set err_list($elt) 1
         }
      }
   }

   # add all versions found when parsing .version or .modulerc files in this
   # directory or in global or user rc definitions
   foreach vers [array names g_moduleVersion] {
      set versmod $g_moduleVersion($vers)
      if {($dir ne {} && [string first $dir/ $g_sourceVersion($vers)] == 0)\
         || [info exists g_rcVersion($vers)]} {
         set found_list($vers) [list version $versmod]

         # build module symbol list
         lappend versmod_list($versmod) $vers
      # add global/user rc def to module symbol list in any cases
      } elseif {!$add_rc_defs && [info exists g_rcVersion($vers)]} {
         lappend versmod_list($versmod) $vers
      }
   }

   # add aliases found when parsing .version or .modulerc files in this
   # directory (skip aliases not registered from this directory except if
   # global or user rc definitions should be included)
   foreach alias [array names g_moduleAlias] {
      if {($dir ne {} && [string first $dir/ $g_sourceAlias($alias)] == 0)\
         || ($add_rc_defs && [info exists g_rcAlias($alias)])} {
         ##nagelfar ignore Found constant
         set found_list($alias) [list alias $g_moduleAlias($alias)]
      }
   }

   # add virtual mods found when parsing .version or .modulerc files in this
   # directory (skip virtual mods not registered from this directory except if
   # global or user rc definitions should be included)
   foreach virt [array names g_moduleVirtual] {
      if {($dir ne {} && [string first $dir/ $g_sourceVirtual($virt)] == 0)\
         || ($add_rc_defs && [info exists g_rcVirtual($virt)])} {
         lassign [checkValidModule $g_moduleVirtual($virt)] check_valid\
            check_msg
         switch -- $check_valid {
            true {
               set mtime [expr {$fetch_mtime ? [getFileMtime\
                  $g_moduleVirtual($virt)] : {}}]
               # set mtime at index 1 like a modulefile entry
               set found_list($virt) [list virtual $mtime\
                  $g_moduleVirtual($virt)]
            }
            default {
               # register check error and relative message to get it in
               # case of direct access of this module element
               set found_list($virt) [list $check_valid $check_msg\
                  $g_moduleVirtual($virt)]
               set err_list($virt) 1
            }
         }
      }
   }

   # Phase #2: early filtering of non-matching elements

   if {$earlyfilter} {
      foreach elt [array names found_list] {
         if {![modEq $modroot $elt eqstart]} {
            unset found_list($elt)
         }
      }
   }

   # Phase #3: scan modulefiles if extra match search is needed

   if {$ems_required} {
      scanExtraMatchSearch $dir $mod found_list
      if {[isEltInReport provided-alias 0]} {
         insertProvidedAliases $dir found_list
      }
   }

   # Phase #4: filter-out dynamically hidden or expired elements

   # define module name and version comparison procs
   defineModEqStaticProc $icase [getConf extended_default] $mod

   # remove hidden elements unless they are (or their symbols) targeted by
   # search query.
   foreach elt [array names found_list] {
      if {[lassign [isModuleHidden $elt $mod 1 [lindex $found_list($elt) 2]]\
         hidlvl hidmatch hidbydef]} {
         # is there a symbol that matches query (bare module name query
         # matches default symbol on resolve context or if onlydefaults filter
         # is applied)
         if {!$hidmatch && [info exists versmod_list($elt)]} {
            foreach eltsym $versmod_list($elt) {
               if {[modEqStatic $eltsym] || (($resctx || $filter eq\
                  {onlydefaults}) && "$mod/default" eq $eltsym)} {
                  set hidmatch 1
                  break
               }
            }
         }
         # consider 'default' symbols are explicitly specified if
         # onlydefaults filter applied or resolving bare module name
         if {!$hidmatch && [lindex $found_list($elt) 0] eq {version} && [file\
            tail $elt] eq {default} && ($filter eq {onlydefaults} || ($resctx\
            && "$mod/default" eq $elt))} {
            set hidmatch 1
         }

         # not hidden if matched unless if hard hiding apply
         if {!$hidmatch || $hidlvl > 1} {
            # record hidden symbol, not to display it in listModules
            if {[lindex $found_list($elt) 0] eq {version}} {
               lappend ::g_hiddenSymHash([lindex $found_list($elt) 1]) [file\
                  tail $elt]
            }
            # transform forbidden module in error entry if it specifically
            # matches search query
            if {$hidlvl == 2 && $hidmatch && [isModuleTagged $elt forbidden 0\
               $dir/$elt]} {
               set found_list($elt) [list accesserr [getForbiddenMsg $elt\
                  $dir/$elt]]
               set err_list($elt) 1
            } else {
               unset found_list($elt)
            }
         }
      }
      # apply hidden tag if an hidden definition apply to module
      if {$hidbydef} {
         setModuleTag $elt hidden
      }
   }

   # Phase #5: elaborate directory content with default element selection

   array set dir_list {}
   array set autosym_list {}

   # build list of elements contained in each directory
   foreach elt [array names found_list] {
      # add a ref to element in its parent directory unless element has error
      # or is a symbolic version then recursively add parent element until
      # reaching top directory
      if {![info exists err_list($elt)] && [lindex $found_list($elt) 0] ne\
         {version}} {
         set direlt $elt
         while {[set pardir [file dirname $direlt]] ne {.}} {
            lappendNoDup dir_list($pardir) [file tail $direlt]
            set direlt $pardir
         }
      }
   }

   # determine default element for each directory and record sorted elt list
   # unless if an alias or a virtual module has overwritten directory entry
   # but override alias entry if extra match search is required (as it
   # withdrawn module aliases)
   foreach elt [array names dir_list] {
      if {![info exists found_list($elt)] || ($ems_required && [lindex\
         $found_list($elt) 0] eq {alias})} {
         set dir_list($elt) [lsort -dictionary $dir_list($elt)]
         # get default element: explicitly defined default (whether it exists
         # or is in error) or implicit default if enabled
         if {[info exists found_list($elt/default)] && [lindex\
            $found_list($elt/default) 0] eq {version}} {
            set dfl [file tail [lindex $found_list($elt/default) 1]]
         } elseif {$implicitdfl} {
            set dfl [lindex $dir_list($elt) end]
         } else {
            set dfl {}
         }
         # record directory properties
         set found_list($elt) [list directory $dfl {*}$dir_list($elt)]

         # automatically define symbols for all modules matching query if
         # these names do not exist yet or if in error, in which case only
         # auto symbol resolution is set
         if {$autosymbol && (!$hasmoddir || [modEq $modroot $elt eqstart])} {
            if {![info exists found_list($elt/default)] || [info exists\
               err_list($elt/default)]} {
               if {![info exists found_list($elt/default)]} {
                  set found_list($elt/default) [list version $elt/$dfl]
                  lappend versmod_list($elt/$dfl) $elt/default
                  set autosym_list($elt/default) 1
               }
               setModuleResolution $elt/default $elt/$dfl default 1 1
            }
            if {![info exists found_list($elt/latest)] || [info exists\
               err_list($elt/latest)]} {
               set lat [lindex $dir_list($elt) end]
               if {![info exists found_list($elt/latest)]} {
                  set found_list($elt/latest) [list version $elt/$lat]
                  lappend versmod_list($elt/$lat) $elt/latest
                  set autosym_list($elt/latest) 1
               }
               setModuleResolution $elt/latest $elt/$lat latest 1 1
            }
         }
      }
   }

   # Phase #6: perform extra match search filtering

   if {$ems_required} {
      filterExtraMatchSearch $dir $mod found_list versmod_list
   }

   # Phase #7: filter results to keep those matching search query

   # define module name and version comparison procs
   defineDoesModMatchAtDepthProc $contains $querydepth $mtest

   # element to include in output
   set report_indesym [isEltInReport indesym 0]
   set report_dirwsym [expr {!$report_indesym && [isEltInReport dirwsym]}]

   array set mod_list {}
   array set fdir_list {}
   array set keep_list {}

   # keep element matching query, add directory of element matching query,
   # also add directory to result if query name finishes with trailing slash;
   # only keep auto syms if fully matched or version not specified in query;
   # (hidden elements have been filtered on phase 2)
   foreach elt [array names found_list] {
      set elt_type [lindex $found_list($elt) 0]
      if {(($wild && [doesModMatchAtDepth $elt]) || (!$wild && ([modEqStatic\
         $elt match /*] || [modEqStatic $elt match] || ($hasmoddir &&\
         $elt_type eq {directory} && [modEq $moddir $elt]))) || ($isquerydir\
         && $elt_type eq {directory} && [modEq $querydir $elt match 0])) &&\
         (![info exists autosym_list($elt)] || ([countChar $elt /]\
         != $querydepth && !$contains) || [modEqStatic $elt]) && ![info\
         exists mod_list($elt)]} {
         if {$elt_type eq {directory}} {
            # add matching directory to the result list, its entries will be
            # computed in a second time and directory will be dropped if it
            # has no entry in the end
            set mod_list($elt) [list directory]
            # add dir to the filter dir list to enable its removal in next
            # step if dir is empty
            if {![info exists fdir_list($elt)]} {
               set fdir_list($elt) {}
            }
         } else {
            set mod_list($elt) $found_list($elt)
         }

         # version may matches query but not its target, so it should be in
         # this case manually added to result (if it exists and unless if
         # versions should be reported independently)
         if {$elt_type eq {version} && !$report_indesym} {
            # resolve eventual icase target
            set versmod [getArrayKey found_list [lindex $mod_list($elt) 1]\
               $icase]
            # add target to dir struct (not version) if not already recorded
            set direlt .

            # recursively add targets to result (process directory content if
            # target is a directory
            set tgt_list [list $versmod]
            for {set i 0} {$i < [llength $tgt_list]} {incr i} {
               set tgt [lindex $tgt_list $i]

               if {![info exists mod_list($tgt)]} {
                  if {[info exists found_list($tgt)]} {
                     set mod_list($tgt) $found_list($tgt)
                     # version target is directory: recursively add content
                     if {[lindex $mod_list($tgt) 0] eq {directory}} {
                        foreach tgtelt $dir_list($tgt) {
                           lappend tgt_list $tgt/$tgtelt
                        }
                        # add dir to the filter dir list to enable its removal
                        # in next step if dir is empty
                        if {![info exists fdir_list($tgt)]} {
                           set fdir_list($tgt) {}
                        }
                     }
                  }

                  # record target in dir struct if part of found elts or if
                  # hidden but should not be in error
                  set pardir [file dirname $tgt]
                  # do not test if full path module is hidden as full path
                  # designation cannot be computed (target not in found_list)
                  if {([info exists found_list($tgt)] || ($pardir ne {.} &&\
                     ![info exists found_list($pardir)] && [isModuleHidden\
                     $tgt $mod])) && ![info exists err_list($tgt)]} {
                     # create parent directory if it does not exist
                     if {$pardir ne {.} && ![info exists\
                        found_list($pardir)]} {
                        set found_list($pardir) [list directory]
                        set mod_list($pardir) [list directory]
                     }

                     if {$i == 0} {
                        set direlt $tgt
                     } else {
                        lappend fdir_list([file dirname $tgt]) [file tail\
                           $tgt]
                     }
                  }
               }
            }
         # skip adding element to directory content if in error
         } elseif {[info exists err_list($elt)]} {
            set direlt .
         } else {
            set direlt $elt
         }

         # track directory content, as directory are also reported to their
         # parent directory the directory structure is also tracked
         if {[set pardir [file dirname $direlt]] ne {.}} {
            lappend fdir_list($pardir) [file tail $direlt]
         # track top level entries that will be kept if result is filtered
         } elseif {$keeping && $direlt ne {.} && $elt_type ne {directory}} {
            set keep_list($elt) 1
         }
      }
   }

   # determine default element for each directory and record sorted element
   # list unless directory entry has been overwritten by a different module
   # kind or unless only matching directory should be part of result
   foreach elt [lsort -decreasing [array names fdir_list]] {
      if {[lindex $found_list($elt) 0] eq {directory} && ([info exists\
         mod_list($elt)] || $keeping)} {
         set fdir_list($elt) [lsort -dictionary $fdir_list($elt)]
         # get default element: explicitly defined default if included in
         # result or not found or implicit default if enabled
         if {[info exists found_list($elt/default)] && [lindex\
            $found_list($elt/default) 0] eq {version} && ([info exists\
            mod_list([set versmod [lindex $found_list($elt/default) 1]])] ||\
            ![info exists found_list($versmod)])} {
            set dfl [file tail $versmod]
         } elseif {$implicitdfl} {
            set dfl [lindex $fdir_list($elt) end]
         } else {
            set dfl {}
         }
         # remove empty dirs
         if {![llength $fdir_list($elt)]} {
            unset mod_list($elt)
            unset fdir_list($elt)
            # remove unset dir reference in parent directory. parent dir
            # will be treated after unset dir (due to decreasing sort) if it
            # needs to get in turn unset
            if {[set pardir [file dirname $elt]] ne {.}} {
               lrem fdir_list($pardir) [file tail $elt]
            }
         } else {
            # record directory properties
            set mod_list($elt) [list directory $dfl {*}$fdir_list($elt)]

            # list elements to keep for filtering step
            if {$keeping} {
               if {$filter eq {onlylatest}} {
                  set keepelt $elt/[lindex $fdir_list($elt) end]
               } elseif {$dfl ne {}} {
                  set keepelt $elt/$dfl
               } else {
                  set keepelt {}
               }

               # keep directory if its element depth is deeper than query
               if {!$indepth && [countChar $keepelt /] > $querydepth} {
                  set keep_list($elt) 1
               # otherwise only keep existing modules (not directories)
               } elseif {[info exists mod_list($keepelt)] && [lindex\
                  $mod_list($keepelt) 0] ne {directory}} {
                  set keep_list($keepelt) 1
               }
            # when noplaindir filtering, only keep dirs with syms when indepth
            # enabled or if corresponds to query depth when indepth disabled
            } elseif {$filtering && $filter eq {noplaindir} &&\
               (($indepth && (!$report_dirwsym || ![doesModuleHaveSym $elt]))\
               || (!$indepth && [countChar $elt /] != $querydepth))} {
               unset mod_list($elt)
            }
         }
      }
   }

   # now all matching modulefiles are settled, only keep those found at search
   # query depth level if 'noindepth' mode asked
   if {!$indepth} {
      # remove entries with more filename path separator than query pattern
      foreach elt [array names mod_list] {
         if {[countChar $elt /] > $querydepth} {
            unset mod_list($elt)
         }
      }
   }

   # if result should be filtered, only keep marked elements
   if {$keeping} {
      foreach elt [array names mod_list] {
         if {![info exists keep_list($elt)]} {
            unset mod_list($elt)
         }
      }
   }

   # Phase #6: consolidate tags set for retained modules

   # skip collecting tags if already performed for this modulepath or command
   # is different than avail/spider
   if {[currentState commandname] in {avail spider} && $dir ni [getState\
      tags_collected_in]} {
      foreach elt [array names mod_list] {
         switch -- [lindex $mod_list($elt) 0] {
            alias - modulefile - virtual {
               # gather all tags applying to elt
               collectModuleTags $elt
            }
         }
      }
   }

   reportTrace "{[array names mod_list]} matching '$mod' in '$dir'" {Get\
      modules}

   # cache search results
   reportDebug "create cache entry '$searchid'"
   set got_list [array get mod_list]
   set ::g_gotModulesMemCache($searchid) $got_list

   return $got_list
}

proc getMatchingAnyModules {dir pattern_list fetch_mtime search filter} {
   set mod_list {}
   foreach pattern $pattern_list {
      lappend mod_list {*}[getModules $dir $pattern $fetch_mtime $search\
         $filter]
   }
   return $mod_list
}

# ;;; Local Variables:
# ;;; Mode: tcl-mode
# ;;; tcl-indent-level: 3
# ;;; tcl-continued-indent-level: 3
# ;;; indent-tabs-mode: nil
# ;;; End:
# vim:set tabstop=3 shiftwidth=3 expandtab autoindent: