Ticket #894: escSeqs.d

/**
* Copyright: Copyright © 2007-2008 Diggory Hardy.
* Authors: Diggory Hardy, diggory.hardy@gmail.com
* License: as for tango (BSD)
*
* Merge this into whatever module it fits best in.
*/
module escSeqs;

/******************************************************************************
* Given a character from an escape sequence returns the
* character the escape sequence represents.
*
* Supported escape sequences are the following subset of those supported by D:
* \" \' \\ \a \b \f \n \r \t \v
*
* Param:
*     c The second character of a two-letter escape sequence (e.g. 't' from \t).
*
* Returns:
*     The character represented by the escape sequence (e.g. tab).
*
* Throws:
*     Throws a <typeofexception> exception when c is not a character from a
*     recognised escape sequence.
*
* Example usage:
* -----------------------------------------------------------------------------
* char[] str;
* for (uint i = 0; i < str.length; ++i) {
*     if (str[i] == '\\') {
*         if (i + 1 >= str.length) throw new Exception ("Invalid escape sequence");
*         str = str[0..i] ~ replaceEscapedChar (str[i+1]) ~ str[i+2..$];
*     }
* }
* -----------------------------------------------------------------------------
******************************************************************************/
char replaceEscapedChar (char c)
{
    static char[char] escChars;
    static bool escCharsFilled; // will be initialised false
    
    if (!escCharsFilled) {
        // map of all supported escape sequences (cannot be static?)
        escChars = ['"'  : '"', '\'' : '\'',
                    '\\' : '\\', 'a' : '\a',
                    'b'  : '\b', 'f' : '\f',
                    'n'  : '\n', 'r' : '\r',
                    't'  : '\t', 'v' : '\v'];
        escCharsFilled = true;
    }
    
    char* r = c in escChars;
    if (r != null) return *r;
    else throw new Exception ("Invalid escape sequence: \\"~c); // FIXME: make an appropriate escape sequence type
}


/******************************************************************************
* Given an escapable character returns the second character of its escape
* sequence.
*
* Supported escape sequences are the following subset of those supported by D:
* \" \' \\ \a \b \f \n \r \t \v
*
* Param:
*     c A character representable by an escape sequence (e.g. tab).
*
* Returns:
*     The second character of the corresponding two-letter escape sequence
*     (e.g. 't' from \t).
*
* Remarks:
*     ASSUMES the character has an escape sequence − no built-in check.
*
* Example usage:
* -----------------------------------------------------------------------------
* char[] str;
* for (uint i = 0; i < str.length; ++i) {
*     if (isEscapableChar(str[i])) {
*         str = str[0..i] ~ '\\' ~ replaceEscapableChar (str[i]) ~ str[i+1..$];
*         ++i;
*     }
* }
* -----------------------------------------------------------------------------
******************************************************************************/
// Warning: this DOES NOT check c is escapable
char replaceEscapableChar (char c) {
    static char[char] escCharsRev;  // reversed escChars
    static bool escCharsRevFilled;  // will be initialised false
    
    if (!escCharsRevFilled) {   // only do this once
        // map of all supported escape sequences
        escCharsRev = ['"' : '"', '\'' : '\'',
                       '\\' : '\\', '\a' : 'a',
                       '\b' : 'b', '\f' : 'f',
                       '\n' : 'n', '\r' : 'r',
                       '\t' : 't', '\v' : 'v'];
        escCharsRevFilled = true;
    }
    
    return escCharsRev[c];
}
/** Companion function to replaceEscapableChar to check whether the character is escapable.
*
* Param:
*     c As for replaceEscapableChar().
*
* Returns:
*     true if character is escapable.
*/
bool isEscapableChar (char c) {
    return ((c <= '\r' && c >= '\a') || c == '\"' || c == '\'' || c == '\\');
}