#--------------------------------------------------------------------------------
#
# printLine   ( tag, string ) 
#
# Purpose : Print a line to the screen 
#       eg. "Rio_Write: Write 0xff81 = 65409 @Mst#0/Slv#0/Slt#08/Chp#0/Reg#0"
#           and optionally a copy is written to the logfile (if previously opened) 
#           with a leading dollar sign "$"
#
# Arguments :
#        optional string    tag : 
#           Leading message tag that will be padded to 9 characters
#           and followed by a colon plus a space character ": " 
#           to separate the tag from the message string
#           If tag is longer than 9 characters, it is not
#           truncated, and only relative alignment with other
#           lines is degraded. 
#           If message tag is omitted, this field remains blank.
#
#        optional string string : message string
#           If the message string tag is omitted, no column
#           is added to the message tag, which then becomes
#           the whole message line.
#
# Return value :
#        no return value
#
#--------------------------------------------------------------------------------
#
# startLogFile ( FileName, AddDate , AddVersion ) 
#
# Purpose : Open a Log File which will receive a copy of all screen output
#           created by printLine
#           The logfile can also be written to directly.
#
# Arguments :
#        optional string FileName :
#           This is the name of the file to open 
#           or it will be used as the base string to build the file name.
#           If this file name is modifed (cf. arguments below), the 
#           file extension is preserved.
#           Default is FileName = 'Py_App.log'
#        optional string AddDate :
#           Values allowed are "yes" (case sensitive) or "no" (in fact anything but "yes")
#           This option will insert the string "_YYYYMMDD" before the "." of the extension.
#           The default is 'yes'
#           
#        optional string AddVersion : 
#           Values allowed are "yes" (case sensitive) or "no" (in fact anything but "yes")
#           This option will append (and manage) a version number in the VMS form 
#           of a trailing semicolon and a number 
#           This will try to create a file name not yet existing by incrementing
#           the version number (from 1 to 99) or overwrite the last version (i.e. 99)
#           The default is 'yes'
#
# Return value :
#        string : Name of the logfile
#                 or empty string in case of failure
#
#--------------------------------------------------------------------------------
#
# flushLogFile ( ) 
#
# Purpose : Force all recent lines that my still be buffered by OS
#           to be written to logfile
#
# Arguments :
#        No arguments
#
# Return value :
#        no return value
#
#--------------------------------------------------------------------------------
#
# writeLogFile ( Line ) 
#
# Purpose : Write one "line" to the logfile directly (no screen output)
#           A time stamp is appended to the end of the line starting at character #109
#           e.g. "%%05-Apr-2005-16:37:03"
#           If a line is longer than 111 character, it is broken up into 
#           one or more continuation lines (with date stamps as well) 
#           and the continuation line(s) will start with an underscore character "_"
#
# Arguments :
#        string Line :
#           message string
#
# Return value :
#        no return value
#
#--------------------------------------------------------------------------------
#
# haveLogFile ( ) 
#
# Purpose : Test the existence of a logfile
#
# Arguments :
#        No arguments
#
# Return value :
#        integer 0 : no logfile (not yet open, or open failure)
#                1 : logfile exist 
#
#--------------------------------------------------------------------------------

"""
Utility: Print_Utils

Screen and file print utilities

"""

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------

import time 
import os.path

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------

LogFileOpened = 0

MaxVersion    = 99 # try to find unique file name from ";1" to ";MaxVersion" 
                   # or overwrite ";MaxVersion"

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------
def printLine   ( tag='', 
                  string='' ) :

    thisLine = tag + (9-len(tag))*' '

    if ( len(string) <> 0 ) : thisLine = thisLine + ": " 

    thisLine = thisLine + string 

    print thisLine 

    if haveLogFile () : 
    
        writeLogFile ( "$" + thisLine ) 

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------
def startLogFile ( FileName    = '',
                   AddDate     = 'yes',
                   AddVersion  = 'yes' ) :

    if ( FileName == '' ) : 
        FileName = 'Py_App.log'
    
    if ( AddDate  == 'yes' ) :
        File_Name, \
        File_Ext = os.path.splitext ( FileName )
        TimeTag  = time.strftime ( "%y%m%d", time.localtime( time.time() ) ) 
        FileName = File_Name + "_" + TimeTag + File_Ext

    if ( AddVersion == 'yes' ) :

        for Version in range ( MaxVersion ) : 
            TryFileName = '%s;%d'  %  ( FileName, Version+1 )
            if not os.path.isfile( TryFileName ) : break # file des not exist, we are done

        FileName  = TryFileName 

    global LogFile ; LogFile = file ( FileName, 'w' )

    if ( LogFile != 0 ) : 
        global LogFileOpened ; LogFileOpened = 1

    LogFile.write (  "\n" )
    LogFile.write (  "---------------------------------------------------------------\n" )
    LogFile.write ( time.strftime ( "%a-%d-%b-%Y-%X", # e.g. 'Wed-14-Jul-1999-00:24:23'
                                     time.localtime( time.time() ) ) )
    LogFile.write (  "    LogFile : %s"  %  os.path.split ( FileName ) [1] )
    LogFile.write (  "\n------------------------\n" )
    LogFile.write (  "\n" )

    if haveLogFile ( ) :
        return FileName
    else :
        return ''

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------

def haveLogFile ( ) : 

    if ( LogFileOpened != 0 ) : 

        return 1

    else : 

        return 0

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------

def flushLogFile ( ) :

    if haveLogFile ( ) :

        LogFile.flush ()

#--------------------------------------------------------------------------------
#--------------------------------------------------------------------------------

def writeLogFile ( Line ) :

    if haveLogFile ( ) :
    
        dateStampBegin = 109    # leave room for e.g. '%%14-Jul-1999-16:24:23'

        if ( len( Line ) > dateStampBegin ) :  

            beginLine =       Line [:dateStampBegin]
            endLine   = "_" + Line [dateStampBegin:]

            writeLogFile ( beginLine ) 
            writeLogFile ( endLine ) 

        else : 

            DateStamp = time.strftime ( "%d-%b-%Y-%X", time.localtime( time.time() ) ) 

            Line = Line + (dateStampBegin-len(Line))*' ' 
            Line = Line + "%%" + DateStamp 

            LogFile.write ( Line + '\n' )