CToken class

Pipelines v1.6

 

Member variables, Member functions

Home

 

Description

 

The CToken class object is used by the ParseForToken() function to extract a token or delimited phrase from your stage command argument. The ParseForToken() function, which can skip leading and or trailing delimiters; extracts the token or phrase and stores it at the address specified in the m_pszTarget member.

 

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 are only intended as a demonstration of how certain functions might be used, they do not represent best practice nor do they take into account the scope and de-allocation of class objects.

 

class CToken
{
    public:
 
    CToken( CProcess &a_Process ) : m_Process( a_Process ),
                                    m_pszSource( NULL ),
                                    m_pszTarget( NULL ),
                                    m_bSkipLeading( true ),
                                    m_szLeadingDelim( " \n\t" ),
                                    m_bSkipTrailing( true ),
                                    m_szTrailingDelim( " \n\t" ) {}
 
    void Reset( void )
    {
        m_bSkipLeading = true;
        m_szLeadingDelim = " \n\t";
        m_bSkipTrailing = true;
        m_szTrailingDelim = m_szLeadingDelim;
    }
 
    CProcess &m_Process;
    const char **m_pszSource;
    CString *m_pszTarget;
    bool m_bSkipLeading;
    CString m_szLeadingDelim;
    bool m_bSkipTrailing;
    CString m_szTrailingDelim;
};

 

Member variables

 

     ●

CProcess &m_Process

[in] Your CStage *this pointer.

 

     ●

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 token.

 

     ●

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 new-line character.

 

Member functions

 

 

CToken::CToken(

    _in         CProcess &a_Process );

 

 

     ●

Purpose

Use CToken() to create a token parser object.

 

The CToken class object is used by the ParseForToken() function to extract a token or delimited phrase from your stage command argument. Simply initialize the members as you require and the call the ParseForToken() function to extract the token.

 

     ●

Parameters

 

 

●

CProcess &a_Process

[in] Your CStage (*this ) pointer.

 

     ●

Returns

n/a

 

     ●

Messages

None

 

     ●

Usage

To extract keywords 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 the keyword ‘LINK’, followed by an unsigned integer
    // with a minimum value of two and maximum value of ten.
 
    CString szKeyword = “LINK”;
 
    // Extract the keyword token.
 
    CString szToken;
    CToken *pToken = new CToken( *this );

    pToken->m_pszSource = &pszArgument;

    pToken->m_pszTarget = &szToken;

 

    if( !pManager->ParseForToken( pToken ) )

    {

        // Tell the user what was expected.

        pManager->StageMessage( *this, 21, _ERROR_, ( LPCTSTR )szKeyword );

        return( false );
    }
    else
    {
        // Validate the keyword.
        if( szKeyword.CompareNocase( szToken ) )
        {
            // Tell the user that it is a bad argument.
            pManager->StageMessage( *this, 7, _ERROR_, ( LPCTSTR )szToken,

                ( LPCTSTR )szKeyword );

            return( false );

        }

    }
 
    // Extract the unsigned integer string.

 

    CString szString;

    CIntegerString *pIntString = new CIntegerString( *this );

 

    pIntString->m_bRequired = true;

    pIntString->m_pszSource = &pszArgument;

    pIntString->m_pszTarget = &szString;

    pIntString->m_lMinUnsignedValue = 2;

    pIntString->m_lMaxUnsignedValue = 10;

 

    // Extract the string.

    if( !pManager->ParseForIntegerString( pIntString ) )

        return( false );

    // Convert the string to an integer ( long ) value.

    if( !pManager->ConvertToInteger( pIntString ) )

        return( false );

 
    ...
 
    return( true );

}

 

 

void CToken::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 CToken parser object when extracting tokens, one after another.

 

     ●

Parameters

 

●

void

 

     ●

Returns

 

●

void

 

     ●

Messages

None

 

     ●

Usage

To re-use a CToken object when extracting tokens, one after another:

 
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 three arguments; the first and third may be
    // keywords of some description, however the second argument is a token
    // which may or may not be surrounded by quotation marks.
 
    // Extract the first.
    CString szToken;
    CToken *pToken = new CToken( *this );

    pToken->m_pszSource = &pszArgument;

    pToken->m_pszTarget = &szToken;

 

    if( !pManager->ParseForToken( pToken ) )

    {

        ...

 

        return( false );

    }
 
    ...
 
    // Extract the second argument.

    pToken->m_szLeadingDelim += ‘”’;

    pToken->m_szTrailingDelim += ‘”’;

 

    if( !pManager->ParseForToken( pToken ) )

    {

        ...

 

        return( false );

    }

 

    // Remove the quotation marks from the list of delimiters.

    pToken->Reset();
 
    // Extract the third argument.

    if( !pManager->ParseForToken( pToken ) )

    {

        ...

 

        return( false );

    }
 
    ...
 
    return( true );

}