Pipelines stage API - CCharacterString class

CCharacterString class

Pipelines v1.6

Description

The CCharacterString class object is used by the ParseForCharacter() and ParseForCharacterString() functions; to extract a single ASCII character, hexadecimal character or binary character definition and a delimited literal character string, hexadecimal string or binary string from your stage command argument. You need not be concerned with the actual format of the character definition or string specified; the functions, which determine this format automatically; extract the definition, convert it to an ASCII character value and stores it at the address specified in the CCharacterString member m_pszTarget.

Definition

The following class definition is an edited version; it details only those members which are accessible and of use to you. In addition; any examples that may be shown in this document are only intended as a demonstration of how certain functions might be used, they may not represent best practice and they may not take into account the scope and de-allocation of class objects.

#define _STRING_TYPE_CHARACTER_   0

#define _STRING_TYPE_HEXADECIMAL_ 1

#define _STRING_TYPE_BINARY_      2

class CCharacterString

    public:

    CCharacterString( CProcess &a_Process ) :

        m_Process( a_Process ),

        m_bRequired( false ),

        m_nReturnCode( _RC_SUCCESS_ ),

        m_pszSource( NULL ),

        m_pszTarget( NULL ),

        m_bNull( false ),

        m_dwMinLength( 1 ),

        m_dwMaxLength( _MAX_INT_ )

        m_nType( _STRING_TYPE_CHARACTER_ ),

        m_bSkipLeading( true ),

        m_szLeadingDelim( " \n\t" ),

        m_bSkipTrailing( true ),

        m_szTrailingDelim( " \n\t" ) {}

    void Reset( void )

        m_bRequired = false;

        m_bNull = false;

        m_dwMinLength = 1;

        m_dwMaxLength = _MAX_INT_;

        m_nType = _STRING_TYPE_CHARACTER_;

        m_bSkipLeading = true;

        m_szLeadingDelim = " \n\t";

        m_bSkipTrailing = true;

        m_szTrailingDelim = m_szLeadingDelim;

    CProcess &m_Process;

    bool m_bRequired;

    int m_nReturnCode;

    const char **m_pszSource;

    CString *m_pszTarget;

    bool m_bNull;

    DWORD m_dwMinLength;

    DWORD m_dwMaxLength;

    int m_nType;

    bool m_bSkipLeading;

    CString m_szLeadingDelim;

    bool m_bSkipTrailing;

    CString m_szTrailingDelim;

};

Member variables

●

CProcess &m_Process

[in] Your CStage (*this ) pointer.

●

bool m_bRequired

[in,opt] Set this option to true if the character or character string is a required stage command argument and must be present, otherwise false; which indicates that the argument is an optional and may or may not be present.

●

int m_nReturnCode

[out] The returncode set by the function which uses this object.

●

const char **m_pszSource

[in,out] The address of a pointer to your stage command argument.

●

CString *m_pszTarget

[in,out] The address of a buffer in which to store the extracted ASCII character or ASCII character string.

●

bool m_bNull

[in,opt] Set this option to true if the character string can be a null string; ie) a string of zero length. When set to true; the ParseForCharacterString() function ignores the value in the m_dwMinLength member variable; allowing a zero length character string as a valid stage operand.

●

DWORD m_dwMinLength

[in,opt] The minimum required length of the ASCII format of the character string.

●

DWORD m_dwMaxLength

[in,opt] The maximum allowed length of the ASCII format of the character string.

●

int m_nType

[out] The type of source string that has been extracted; a delimited character string, a string of hexadecimal characters or a string of binary characters.

m_nType	Value

_STRING_TYPE_CHARACTER_	0
_STRING_TYPE_HEXADECIMAL_	1
_STRING_TYPE_BINARY_	2

●

bool m_bSkipLeading

[in,opt] Set this option to true if leading delimiters are to be skipped.

●

CString m_szLeadingDelim

[in,opt] A list of characters; any of which are considered to be leading delimiters. By default; the list contains a space, a tab character and new-line character.

●

bool m_bSkipTrailing

[in,opt] Set this option to true if trailing delimiters are to be skipped.

●

CString m_szTrailingDelim

[in,opt] A list of characters; any of which are considered to be trailing delimiters. By default; the list contains a space, a tab character and a new-line character.

Member functions

CCharacterString::CCharacterString(

    _in                             CProcess &a_Process );

●

Purpose

Use CCharacterString() to create a string parser object.

The CCharacterString class object is used by the ParseForCharacterString() function to extract a literal character string from your stage command argument. Simply initialise the members as you require and call the ParseForCharacterString() function to extract the string.

●

Parameters

●	CProcess &a_Process *[in] Your CStage (this ) pointer.**

●

Returns

n/a

●

Messages

None

●

Usage

To extract a literal character string from your stage command argument:

bool CMyStage::Initialise( void )

    // Access the manager.

    CStageManager *pManager = Manager();

    // Access my stage.

    CStage *pStage = pManager->GetStage( *this );

...

    // Point to my stage command argument.

    const char *pszArgument = pStage->Argument();

    // My stage requires a literal string as its stage command

    // argument. The string may be a null string.

    CString szString;

    CCharacterString *pCharString = new CCharacterString( *this );

    pCharString->m_bRequired = true;

    pCharString->m_pszSource = &pszArgument;

    pCharString->m_pszTarget = &szString;

    pCharString->m_bNull = true;

    // Extract the string.

    if( !pManager->ParseForCharacterString( pCharString ) )

        return( false );

...

    return( true );

void CCharacterString::Reset( void );

●

Purpose

Use Reset() to reset the default extraction settings.

The function will reset the extraction switches and re-initialise the delimiter definitions with their default values, but, leaving the m_Process and m_pszSource members unchanged; you can re-use a CCharacterString parser object when extracting string arguments, one after another.

●

Parameters

●

void

●

Returns

●

void

●

Messages

None

●

Usage

The Reset() function clears the CCharacterString class object’s extraction settings, but leaves the m_Process and m_pszSource members unchanged; which means that you only need provide these values the first time that you use the object. The m_pszSource member (common to all the parsing class types; CCharacterString, CIntegerString, etc..) automatically keeps track of your stage command argument pointer. Provided that you use the ParseFor…() functions to extract tokens, strings and ranges from your stage command argument; the m_pszSource member will always be pointing to the next stage command argument position.

bool CMyStage::Initialise( void )

    // Access the manager.

    CStageManager *pManager = Manager();

    // Access my stage.

    CStage *pStage = pManager->GetStage( *this );

...

    // Point to my stage command argument.

    const char *pszArgument = pStage->Argument();

    CString szString;

    CCharacterString *pCharString = new CCharacterString( *this );

    // My stage requires two literal string commands; the first is

    // a simple literal value and the second, which is optional; is a

    // regular expression definition.

    pCharString->m_bRequired = true;

    pCharString->m_pszSource = &pszArgument;

    pCharString->m_pszTarget = &szString;

    // Extract the string.

    if( !pManager->ParseForCharacterString( pCharString ) )

        return( false );

...

    // Reset the object.

    pCharString->Reset();

    // Extract the string.

    if( pManager->ParseForCharacterString( pCharString ) )

        // Parse and assign the regular expression.

        CRegExpression *pRegExp = new CRegExpression;

        pRegExp->m_RegExp.Expression = szString;

        if( !pManager->ParseForRegExp( *this, pRegExp, pStage->Casei() ) )

            return( false );

...

...

    return( true );