#!/bin/ksh
##
## SCRIPT NAME:  hex2ascii
##                                           in $FEDIR/scripts
##                                     where FEDIR=/apps/nns_com/fea
##
########################################################################
## PURPOSE:
##   This script reads a file (or piped data-stream) of pairs of hex-codes
##   in each line.  It translates each line of hex-codes into lines of
##   ASCII text.  The lines need not be the same length.
##
##       [In fact, this utility was originally meant to translate
##        filenames, of varying length, from a hex-code format to
##        their more normal ASCII format.]
##
##   Uses an awk program that uses a binary-search scheme on the table
##   of 256 hex-codes and ASCII characters. 
##
########################################################################
## PROCESSING LOGIC:
##
##   This script utility performs the following processing sequence.
##
##   1) GETS THE INPUT FILENAME, if passed in $1.  [Or uses 'cat' to
##      accept input piped to this script and put it in a temporary
##      file.]
##
##   2) FILE TRANSLATION (AWK-PROG):
##
##      Reads sequentially through the input file and, for each line
##      ('record') translates each pair of hex-codes in the line into
##      an ASCII character.
##
##      When the end of each line is reached (i.e. the last of the pairs
##      of hex-codes in the line is translated), the concatenated ASCII
##      characters created from that line are output as one line ('record')
##      to stdout.
##
##         [TABLE OF HEXCODES & ASCII CHARACTERS:
##          The BEGIN section of the awk program builds a table of 
##          of 256 hex-codes and 128 ASCII characters.
##
##         [BINARY SEARCH FUNTION:
##          The bottom of the awk program holds a binary-search function
##          that is called on to do a relatively fast table lookup for
##          each pair of hex-codes.
##
##              The input to the binary-search function is a pair
##              of hex-codes.  Output is an ASCII character.
##
##          NOTE: The binary-search method is sometimes referred to as
##                the 'telephone book' lookup method.]
##
########################################################################
## CALLED BY: could be called by
##            1) a script with a GUI that prompts for the name of
##               the file containing pairs of hex-codes,
##            OR
##            2) a cron job script,
##            OR
##            3) manually (via a short alias).
########################################################################
## TEST FILES:  Test files with pairs of hex codes representing
##              ASCII filenames (with slashes and periods) are in
##              in directory   /apps/nns_com/fea/demos_hex_ascii.
## 
########################################################################
## MAINTENANCE HISTORY:
## Written by: Blaise Montandon 16feb2001 Based on 'xlpps' and
##                                        'simtec_nas_tria_quad2stl_bygui'
##                                    and 'simtec_generic2Dels_2stl_awkprog'
##                                        in $FEDIR/scripts
##  
## Updated by: Blaise Montandon 19feb2001 Add '-v' (verbose) option 
##                                        and '-h' (help) option (= '-v'),
##                                        and '-d' (debug) option.
########################################################################

########################################################################
## SET THE $FEDIR DIRECTORY, for utility scripts called below,
## if the variable is not set already.
########################################################################

if test "$FEDIR" = ""
then
   FEDIR="/apps/nns_com/fea"
fi

# . $FEDIR/scripts/clearnns


#######################################################################
## If a '-v' (verbose) parm is among command options,
## set  QUIET="NO" (else  QUIET="YES").
#######################################################################
## Example from 'man getopts':
##############################################################################
##          while getopts abo: c
##          do
##               case $c in
##               a | b)    FLAG=$c;;
##               o)        OARG=$OPTARG;;
##               \?)       echo $USAGE
##                         exit 2;;
##               esac
##          done
##          shift `expr $OPTIND - 1`
##############################################################################

QUIET="YES"
DEBUG=0

## FOR TESTING:
#      echo "
#  PARM1: $1  PARM2: $2  PARM3: $3 PARM4: $4
#  "

# while getopts qc OPTION
while getopts vhd OPTION
do
    if [ $OPTION = "v" ]
    then
        QUIET="NO"
    elif [ $OPTION = "h" ]
    then
       QUIET="NO"
    elif [ $OPTION = "d" ]
    then
       DEBUG=1
    fi
done
shift `expr $OPTIND - 1`

## FOR TESTING:
#   echo "
# PARM1: $1  PARM2: $2  PARM3: $3
# "

######################################################################
## GET THE INPUT --- via a file ($1) or from stdin (via 'cat').
######################################################################
##  LOAD THE INPUT TO 'hex2ascii' INTO A TEMPORARY FILE,
##  $LOCDIR/....temp_hex2ascii.hex
######################################################################
##  Accept either   $1   OR   pipe (|)   OR   redirect (<) .
##
##  If $1 is not-provided (or empty),
##
##         'cat' stdin into the tempfile
##         AND  load the tempfile name into  HEX_FILENAME
##  else 
##         load $1 into  HEX_FILENAME.
######################################################################

if test "$1" = ""
then

   #######################################################################
   ## If a '-v' (verbose) parm is among command options ("$QUIET" = "NO"), 
   ## display a 'usage' message.
   #######################################################################

   if test "$QUIET" = "NO"
   then
        echo "
Usage:  hex2ascii <hexcodes-filename>
   OR   pipe hexcodes-datastream into hex2ascii

'hex2ascii' reads from standard input or a file.
You may Alt-Break if 'hex2ascii' is waiting for keyboard input here."

   fi

   ############################################################
   ## SET var LOCDIR to /local/scratch/$USER --- if possible -- 
   ## for holding stdin-input captured via the 'cat' utility.
   ############################################################
   #  . $FEDIR/scripts/set_localuserdir
   ############################################################
   
   if test -d  /local/scratch
   then
      TEMPfile=/local/scratch/${USER}_hex2ascii_tempin.hex
   else
      TEMPfile=$HOME/hex2ascii_tempin.hex
   fi

   rm -f $TEMPfile
   touch $TEMPfile
 
   ##################################################
   ##  A SLOOOOWWWW... way of reading the input file.
   ##  (BADDDDD to use a file-reading loop in an
   ##  interpreted script.)
   ##################################################
   #        while read line
   #        do
   #           echo "$line" >> $TEMPfile
   #        done
   ##################################################

     LINES2=1
     LINES1=0
     while test $LINES2 -gt $LINES1
     do

        LINES1=`wc -l < $TEMPfile`
        cat >> $TEMPfile
        LINES2=`wc -l < $TEMPfile`

     done

     HEX_FILENAME="$TEMPfile"

else
     HEX_FILENAME="$1"
fi

export HEX_FILENAME

## FOR TESTING:
#  echo "Input Filename:" $HEX_FILENAME


#########################################################################
## AWK-PROG:
## TRANSLATE THE HEX-CODES FILES TO ASCII RECORDS (sent to stdout).
#########################################################################

##############
## FOR TESTING:
##############
#   set -x   


##############
## FOR TESTING:
##############
  TESTOUTFILE="$HOME/hex2ascii_testoutput.ascii"


#########################################################################
#########################################################################
## HERE IS THE AWK-PROG CALL.
#########################################################################
#########################################################################
##############
## FOR TESTING:  Use awk-var DE_BUG to SET DEBUG=1 in the BEGIN section of
##               the following awkprog .
##############

if test $DEBUG = 1 
then

#   awk -v FILE_IN="$HEX_FILENAME" -v DE_BUG=$DEBUG \
#   -f $FEDIR/scripts/hex2ascii_awkprog_NEW \
#   $HEX_FILENAME > $TESTOUTFILE

    awk -v FILE_IN="$HEX_FILENAME" -v DE_BUG=$DEBUG \
    -f $FEDIR/scripts/hex2ascii_awkprog \
    $HEX_FILENAME > $TESTOUTFILE

else

    awk -v FILE_IN="$HEX_FILENAME" -v DE_BUG=$DEBUG \
    -f $FEDIR/scripts/hex2ascii_awkprog \
    $HEX_FILENAME

fi

##############
## FOR TESTING:
##############
##  set -

##############
## FOR TESTING:
## SHOW TEST OUTPUT FILE -- via 'nedit' in read-only mode.
##############

if test $DEBUG = 1 
then
# nedit -read $TESTOUTFILE &
  nedit -read $TESTOUTFILE
fi