ENH: several improvements to foamEtcFile

- lazier evaluation of project name and version based on the directory
  name. Avoids heuristics based on directory names unless really needed.

- cope with alternative directory locations.
  For example, OpenFOAM+VERSION etc.

The combination of the two above appears to be sufficient to open up
the directory naming possibilities.

- additional -list-test option (tests for existence of directory).

bin/foamEtcFile

@@ -26,7 +26,7 @@
 #     foamEtcFile
 #
 # Description
-#     Locate user/group/shipped file with semantics similar to the
+#     Locate user/group/other files with semantics similar to the
 #     ~OpenFOAM/fileName expansion.
 #
 #     The -mode option can be used to allow chaining from
@@ -34,119 +34,175 @@
 #
 #     For example, within the user ~/.OpenFOAM/<VER>/prefs.sh:
 #     \code
-#        foamFile=$(foamEtcFile -mode go prefs.sh) && . $foamFile
+#        eval $(foamEtcFile -sh -mode=go prefs.sh)
 #     \endcode
 #
+# Environment
+#     - WM_PROJECT:         (unset defaults to OpenFOAM)
+#     - WM_PROJECT_SITE:    (unset defaults to PREFIX/site)
+#     - WM_PROJECT_VERSION: (unset defaults to detect from path)
+#
 # Note
-#     This script must exist in $FOAM_INST_DIR/OpenFOAM-<VERSION>/bin/
-#     or $FOAM_INST_DIR/openfoam<VERSION>/bin/ (for the debian version)
+#     This script must exist in one of these locations:
+#     - $WM_PROJECT_INST_DIR/OpenFOAM-<VERSION>/bin
+#     - $WM_PROJECT_INST_DIR/openfoam-<VERSION>/bin
+#     - $WM_PROJECT_INST_DIR/OpenFOAM+<VERSION>/bin
+#     - $WM_PROJECT_INST_DIR/openfoam+<VERSION>/bin
+#     - $WM_PROJECT_INST_DIR/openfoam<VERSION>/bin  (debian version)
 #
 #-------------------------------------------------------------------------------
 unset optQuiet optSilent
 usage() {
     [ "${optQuiet:-$optSilent}" = true ] && exit 1
-
     exec 1>&2
     while [ "$#" -ge 1 ]; do echo "$1"; shift; done
     cat<<USAGE
 
 Usage: foamEtcFile [OPTION] fileName
-       foamEtcFile [OPTION] -list
+       foamEtcFile [OPTION] [-list|-list-test] [fileName]
+
 options:
-  -a, -all          return all files (otherwise stop after the first match)
-  -l, -list         list the directories to be searched
-  -m, -mode MODE    any combination of u(user), g(group), o(other)
-  -p, -prefix DIR   specify an alternative installation prefix
-  -q, -quiet        suppress all normal output
-  -s, -silent       suppress stderr output, except for things that are emitted
-                    by -csh-verbose, -sh-verbose.
-  -v, -version VER  specify alternative OpenFOAM version (eg, 3.0, 1612, ...)
-  -csh | -sh        produce output suitable for a csh or sh 'eval'
-  -csh-verbose,
-  -sh-verbose       with additional verbosity
-  -help             print the usage
-
-  Locate user/group/shipped file with semantics similar to the
-  ~OpenFOAM/fileName expansion.
-
-  Many options can be specified as a single character, but must not be grouped.
-
-  Exit status
-      0  when the file is found. Print resolved path to stdout.
-      1  for miscellaneous errors.
-      2  when the file is not found.
+  -a, -all          Return all files (otherwise stop after the first match)
+  -l, -list         List directories or files to be checked
+  -list-test        List (existing) directories or files to be checked
+  -mode=MODE        Any combination of u(user), g(group), o(other)
+  -prefix=DIR       Specify an alternative installation prefix
+  -version=VER      Specify alternative OpenFOAM version (eg, 3.0, 1612, ...)
+  -csh | -sh        Produce output suitable for a csh or sh 'eval'
+  -csh-verbose | -sh-verbose
+                    As per -csh | -sh, with additional verbosity
+  -q, -quiet        Suppress all normal output
+  -s, -silent       Suppress stderr, except -csh-verbose, -sh-verbose output
+  -help             Print the usage
+
+Locate user/group/other file with semantics similar to the
+~OpenFOAM/fileName expansion.
+
+Single character options must not be grouped. Equivalent options:
+    -mode=MODE,   -mode MODE,   -m MODE
+    -prefix=DIR,  -prefix DIR,  -p DIR
+    -version=VER, -version VER, -v VER
+
+Exit status
+    0  when the file is found. Print resolved path to stdout.
+    1  for miscellaneous errors.
+    2  when the file is not found.
 
 USAGE
     exit 1
 }
-#-------------------------------------------------------------------------------
 
-# The bin dir:
-binDir="${0%/*}"
+# Report error and exit
+die()
+{
+    [ "${optQuiet:-$optSilent}" = true ] && exit 1
+    exec 1>&2
+    echo
+    echo "Error encountered:"
+    while [ "$#" -ge 1 ]; do echo "    $1"; shift; done
+    echo
+    echo "See 'foamEtcFile -help' for usage"
+    echo
+    exit 1
+}
+
+#-------------------------------------------------------------------------------
+binDir="${0%/*}"                # The bin dir
+projectDir="${binDir%/bin}"     # The project dir
+prefixDir="${projectDir%/*}"    # The prefix dir (same as $WM_PROJECT_INST_DIR)
 
-# The project dir:
-projectDir="${binDir%/bin}"
+# Could not resolve projectDir, prefixDir? (eg, called as ./bin/foamEtcFile)
+if [ "$prefixDir" = "$projectDir" ]
+then
+    binDir="$(cd $binDir && pwd -L)"
+    projectDir="${binDir%/bin}"
+    prefixDir="${projectDir%/*}"
+fi
+projectDirName="${projectDir##*/}"      # The project directory name
 
-# The prefix dir (same as $FOAM_INST_DIR):
-prefixDir="${projectDir%/*}"
+projectName="${WM_PROJECT:-OpenFOAM}"   # The project name
+projectVersion="$WM_PROJECT_VERSION"    # Empty? - will be treated later
 
-# The name used for the project directory
-projectDirName="${projectDir##*/}"
 
-# The versionNum is used for debian packaging
-unset versionNum
+#-------------------------------------------------------------------------------
 
-#
+# Guess project version or simply get the stem part of the projectDirName.
 # Handle standard and debian naming conventions.
-# - projectDirBase: projectDirName without the version
-# - version
-# - versionNum (debian only)
 #
-case "$projectDirName" in
-OpenFOAM-* | openfoam-*)        # OpenFOAM-<VERSION> or openfoam-<VERSION>
-    projectDirBase="${projectDirName%%-*}-"
-    version="${projectDirName#*-}"
-    ;;
+# - projectVersion: update unless already set
+#
+# Helper variables:
+# - dirBase (for reassembling name) == projectDirName without the version
+# - versionNum (debian packaging)
+unset dirBase versionNum
+guessVersion()
+{
+    local version
+
+    case "$projectDirName" in
+    (OpenFOAM-* | openfoam-*)
+        # Standard naming: OpenFOAM-<VERSION> or openfoam-<VERSION>
+        dirBase="${projectDirName%%-*}-"
+        version="${projectDirName#*-}"
+        version="${version%%*-}" # Extra safety, eg openfoam-version-packager
+        ;;
+
+    (OpenFOAM+* | openfoam+*)
+        # Alternative naming: OpenFOAM+<VERSION> or openfoam+<VERSION>
+        dirBase="${projectDirName%%+*}+"
+        version="${projectDirName#*+}"
+        version="${version%%*-}" # Extra safety, eg openfoam-version-packager
+        ;;
+
+    (openfoam[0-9]*)
+        # Debian naming: openfoam<VERSION>
+        dirBase="openfoam"
+        version="${projectDirName#openfoam}"
+        versionNum="$version"
+
+        # Convert digits version number to decimal delineated
+        case "${#versionNum}" in (2|3|4)
+            version=$(echo "$versionNum" | sed -e 's@\([0-9]\)@\1.@g')
+            version="${version%.}"
+            ;;
+        esac
 
-openfoam[0-9]*)                 # Debian: openfoam<VERSION>
-    projectDirBase="openfoam"
-    versionNum="${projectDirName#openfoam}"
-    case "${#versionNum}" in
-    (2|3|4) # Convert digits version number to decimal delineated
-        version=$(echo "$versionNum" | sed -e 's@\([0-9]\)@\1.@g')
-        version="${version%.}"
+        # Ignore special treatment if no decimals were inserted.
+        [ "${#version}" -gt "${#versionNum}" ] || unset versionNum
         ;;
 
-    (*) # Fallback - use current environment setting
-        version="$WM_PROJECT_VERSION"
+    (*)
+        die "unknown/unsupported naming convention for '$projectDirName'"
         ;;
     esac
-    ;;
 
-*)
-    echo "foamEtcFile error: unknown/unsupported naming convention" 1>&2
-    exit 1
-    ;;
-esac
+    # Set projectVersion if required
+    : ${projectVersion:=$version}
+}
 
 
-# Set version and update versionNum, projectDirName accordingly
+# Set projectVersion and update versionNum, projectDirName accordingly
 setVersion()
 {
-    version="$1"
+    projectVersion="$1"
 
-    # Convert x.y.z -> xyz version (if installation looked like debian)
-    [ -n "$versionNum" ] && versionNum=$(echo "$version" | sed -e 's@\.@@g')
+    # Need dirBase when reassembling projectDirName
+    [ -n "$dirBase" ] || guessVersion
 
-    projectDirName="$projectDirBase${versionNum:-${version}}"
+    # Debian: update x.y.z -> xyz version
+    if [ -n "$versionNum" ]
+    then
+        versionNum=$(echo "$projectVersion" | sed -e 's@\.@@g')
+    fi
+
+    projectDirName="$dirBase${versionNum:-$projectVersion}"
 }
 
 
-# Default mode is always 'ugo'
-mode=ugo
-unset optAll optList optShell
+optMode=ugo         # Default mode is always 'ugo'
+unset optAll optList optShell optVersion
 
-# parse options
+# Parse options
 while [ "$#" -gt 0 ]
 do
     case "$1" in
@@ -161,34 +217,38 @@ do
         optList=true
         unset optShell
         ;;
+    -list-test)
+        optList='test'
+        unset optShell
+        ;;
     -csh | -sh | -csh-verbose | -sh-verbose)
         optShell="${1#-}"
         unset optAll
         ;;
     -mode=[ugo]*)
-        mode="${1#*=}"
+        optMode="${1#*=}"
         ;;
     -prefix=/*)
         prefixDir="${1#*=}"
         prefixDir="${prefixDir%/}"
         ;;
     -version=*)
-        setVersion "${1#*=}"
+        optVersion="${1#*=}"
         ;;
     -m | -mode)
-        mode="$2"
+        optMode="$2"
+        shift
         # Sanity check. Handles missing argument too.
-        case "$mode" in
-        [ugo]*)
+        case "$optMode" in
+        ([ugo]*)
             ;;
-        *)
-            usage "invalid mode '$mode'"
+        (*)
+            die "invalid mode '$optMode'"
             ;;
         esac
-        shift
         ;;
     -p | -prefix)
-        [ "$#" -ge 2 ] || usage "'$1' option requires an argument"
+        [ "$#" -ge 2 ] || die "'$1' option requires an argument"
         prefixDir="${2%/}"
         shift
         ;;
@@ -199,8 +259,8 @@ do
         optSilent=true
         ;;
     -v | -version)
-        [ "$#" -ge 2 ] || usage "'$1' option requires an argument"
-        setVersion "$2"
+        [ "$#" -ge 2 ] || die "'$1' option requires an argument"
+        optVersion="$2"
         shift
         ;;
     --)
@@ -208,7 +268,7 @@ do
         break
         ;;
     -*)
-        usage "unknown option: '$1'"
+        die "unknown option: '$1'"
         ;;
     *)
         break
@@ -217,12 +277,27 @@ do
     shift
 done
 
-# Update projectDir accordingly
+
+#-------------------------------------------------------------------------------
+
+if [ -n "$optVersion" ]
+then
+    setVersion $optVersion
+elif [ -z "$projectVersion" ]
+then
+    guessVersion
+fi
+
+# Updates:
+# - projectDir  for changes via -prefix or -version
+# - projectSite for changes via -prefix
 projectDir="$prefixDir/$projectDirName"
+projectSite="${WM_PROJECT_SITE:-$prefixDir/site}"
+
 
 # Debugging:
 # echo "Installed locations:" 1>&2
-# for i in projectDir prefixDir projectDirName version versionNum
+# for i in projectDir prefixDir projectDirName projectVersion
 # do
 #     eval echo "$i=\$$i" 1>&2
 # done
@@ -235,19 +310,17 @@ fileName="${1#~OpenFOAM/}"
 
 # Define the various places to be searched:
 unset dirList
-case "$mode" in (*u*)   # (U)ser
-    dir="$HOME/.${WM_PROJECT:-OpenFOAM}"
-    dirList="$dirList $dir/$version $dir"
+case "$optMode" in (*u*) # (U)ser
+    dirList="$dirList $HOME/.$projectName/$projectVersion $HOME/.$projectName"
     ;;
 esac
 
-case "$mode" in (*g*)   # (G)roup == site
-    dir="${WM_PROJECT_SITE:-$prefixDir/site}"
-    dirList="$dirList $dir/$version $dir"
+case "$optMode" in (*g*) # (G)roup == site
+    dirList="$dirList $projectSite/$projectVersion $projectSite"
     ;;
 esac
 
-case "$mode" in (*o*)   # (O)ther == shipped
+case "$optMode" in (*o*) # (O)ther == shipped
     dirList="$dirList $projectDir/etc"
     ;;
 esac
@@ -259,30 +332,54 @@ set -- $dirList
 #
 
 exitCode=0
-if [ "$optList" = true ]
+if [ -n "$optList" ]
 then
 
     # List directories, or potential file locations
-    [ "$nArgs" -le 1 ] || usage
+    [ "$nArgs" -le 1 ] || \
+    die "-list expects 0 or 1 filename, but $nArgs provided"
 
     # A silly combination, but -quiet does have precedence
     [ -n "$optQuiet" ] && exit 0
 
-    for dir
-    do
+    # Test for directory or file too?
+    if [ "$optList" = "test" ]
+    then
+        exitCode=2  # Fallback to a general error (file not found)
+
         if [ "$nArgs" -eq 1 ]
         then
-            echo "$dir/$fileName"
+            for dir
+            do
+                resolved="$dir/$fileName"
+                if [ -f "$resolved" ]
+                then
+                    echo "$resolved"
+                    exitCode=0  # OK
+                fi
+            done
         else
-            echo "$dir"
+            for dir
+            do
+                if [ -d "$dir" ]
+                then
+                    echo "$dir"
+                    exitCode=0  # OK
+                fi
+            done
         fi
-    done
+    else
+        for dir
+        do
+            echo "$dir${fileName:+/}$fileName"
+        done
+    fi
 
 else
 
-    [ "$nArgs" -eq 1 ] || usage
+    [ "$nArgs" -eq 1 ] || die "One filename expected - $nArgs provided"
 
-    exitCode=2  # Fallback to a general error, eg file not found
+    exitCode=2  # Fallback to a general error (file not found)
 
     for dir
     do
@@ -316,7 +413,6 @@ else
 
 fi
 
-
 exit $exitCode
 
 #------------------------------------------------------------------------------

bin/foamExec

@@ -26,7 +26,7 @@
 #     foamExec
 #
 # Description
-#     Usage: foamExec [-v foamVersion] <foamCommand> ...
+#     Usage: foamExec [-version=foamVersion] <foamCommand> ...
 #
 #     Runs the <foamVersion> version of executable <foamCommand>
 #     with the rest of the arguments.
@@ -34,7 +34,7 @@
 #     Can also be used for parallel runs. For example,
 #     \code
 #         mpirun -np <nProcs> \
-#             foamExec -version <foamVersion> <foamCommand> ... -parallel
+#             foamExec -version=VERSION <foamCommand> ... -parallel
 #     \endcode
 #
 # Note
@@ -55,34 +55,29 @@ usage() {
 Usage: ${0##*/} [OPTION] <application> ...
 
 options:
-  -prefix <dir>     specify an alternative installation prefix
+  -mode=MODE        Any combination of u(user), g(group), o(other)
+  -prefix=DIR       Specify an alternative installation prefix
                     pass through to foamEtcFile and set as FOAM_INST_DIR
-  -version <ver>    specify an alternative OpenFOAM version
+  -version=VER      Specify alternative OpenFOAM version (eg, 3.0, 1612, ...)
                     pass through to foamEtcFile
-  -help             print the usage
+  -help             Print the usage
 
-* run a particular OpenFOAM version of <application>
+Run a particular OpenFOAM version of <APPLICATION>
 
 USAGE
     exit 1
 }
 
 #-------------------------------------------------------------------------------
+binDir="${0%/*}"                # The bin dir
+projectDir="${binDir%/bin}"     # The project dir
+prefixDir="${projectDir%/*}"    # The prefix dir (same as $WM_PROJECT_INST_DIR)
 
-# the bin dir:
-binDir="${0%/*}"
+## projectDirName="${projectDir##*/}"      # The project directory name
 
-# the project dir:
-projectDir="${binDir%/bin}"
+version="${WM_PROJECT_VERSION:-unknown}"
 
-# the prefix dir (same as $FOAM_INST_DIR):
-prefixDir="${projectDir%/*}"
-
-# # the name used for the project directory
-# projectDirName="${projectDir##*/}"
-
-
-unset etcOpts version
+unset etcOpts
 # parse options
 while [ "$#" -gt 0 ]
 do
@@ -90,6 +85,17 @@ do
     -h | -help)
         usage
         ;;
+    -mode=*)
+        etcOpts="$etcOpts $1"       # pass-thru to foamEtcFile
+        ;;
+    -prefix=/*)
+        etcOpts="$etcOpts $1"       # pass-thru to foamEtcFile
+        prefixDir="${1#*=}"
+        ;;
+    -version=*)
+        etcOpts="$etcOpts $1"       # pass-thru to foamEtcFile
+        version="${1#*=}"
+        ;;
     -m | -mode)
         [ "$#" -ge 2 ] || usage "'$1' option requires an argument"
         etcOpts="$etcOpts $1 $2"    # pass-thru to foamEtcFile
@@ -127,15 +133,15 @@ done
 #
 sourceRc()
 {
-    foamDotFile="$($binDir/foamEtcFile $etcOpts bashrc)" || {
-        echo "Error : bashrc file could not be found for OpenFOAM-${version:-${WM_PROJECT_VERSION:-???}}" 1>&2
+    rcFile="$($binDir/foamEtcFile $etcOpts bashrc)" || {
+        echo "Error : bashrc file could not be found for OpenFOAM-$version" 1>&2
         exit 1
     }
 
     # set to consistent value before sourcing the bashrc
     export FOAM_INST_DIR="$prefixDir"
 
-    . $foamDotFile $FOAM_SETTINGS
+    . $rcFile $FOAM_SETTINGS
 }
 
 

etc/config.csh/example/paraview

@@ -38,7 +38,7 @@
 # Use other (shipped) paraview with a different ParaView_VERSION
 #
 
-set foamFile=`$WM_PROJECT_DIR/bin/foamEtcFile -mode o config.csh/paraview`
+set foamFile=`$WM_PROJECT_DIR/bin/foamEtcFile -mode=o config.csh/paraview`
 if ( $status == 0 ) source $foamFile ParaView_VERSION=5.0.1
 
 unset foamFile