Base class for console applications. More...

#include <brconsolemanager.h>

Inheritance diagram for Burger::ConsoleApp:

Collaboration diagram for Burger::ConsoleApp:

Public Types
typedef int(BURGER_API *	CallbackProc )(ConsoleApp pThis, const char pInputFilename, const char *pOutputFilename)
	Callback for doing the application's work.
typedef void(BURGER_API *	UsageProc )(ConsoleApp *pThis)
	Callback for printing instructions.
Public Member Functions
	ConsoleApp (int iArgc, const char **ppArgv)
	Base constructor.
BURGER_INLINE void	SetArgv (const char **ppArgv)
	Set the current argv parameter.
BURGER_INLINE const char **	GetArgv (void) const
	Get the current argv parameter.
BURGER_INLINE void	SetArgc (int iArgc)
	Set the current argc parameter.
BURGER_INLINE int	GetArgc (void) const
	Get the current argc parameter.
BURGER_INLINE void	SetReturnCode (int iReturnCode)
	Set the value for main() to return.
BURGER_INLINE int	GetReturnCode (void) const
	Get the current return code.
void BURGER_API	PauseOnError (void) const
	Pause console output if the return code is not zero.
Word BURGER_API	ProcessFilenames (Burger::ConsoleApp::CallbackProc pCallback)
	Handle drag and drop for console apps.
int BURGER_API	InputAndOutput (Burger::ConsoleApp::CallbackProc pCallback, Burger::ConsoleApp::UsageProc pUsage)
	Function for 2 or 3 argument tools.
int BURGER_API	SimpleTool (Burger::ConsoleApp::CallbackProc pCallback, Burger::ConsoleApp::UsageProc pUsage)
	Handle simple console applications.
Private Attributes
const char **	m_ppArgv
	Arguments passed to the console.
int	m_iArgc
	Number of valid arguments.
int	m_iReturnCode
	Value to return to the OS.
Word8	m_bLaunchedFromFinder
	TRUE if the application was directly launched.

Detailed Description

Base class for console applications.

This class contains everything needed to create a cross-platform environment for writing console based applications. Functions are included to allow for the application to gain drag and drop functionality on platforms that support it.

Member Typedef Documentation

typedef int(BURGER_API * Burger::ConsoleApp::CallbackProc)(ConsoleApp *pThis, const char *pInputFilename, const char *pOutputFilename)

Callback for doing the application's work.

typedef void(BURGER_API * Burger::ConsoleApp::UsageProc)(ConsoleApp *pThis)

Callback for printing instructions.

Constructor & Destructor Documentation

Burger::ConsoleApp::ConsoleApp	(	int	iArgc,
		const char **	ppArgv
	)

Base constructor.

When a console app is spawned using ANSI C++ main(), it is given two parameters argc and argv. These parms are cached inside of this base class so the member functions can handle automatic parameter passing and decoding. The return code is initialized to zero.

Member Function Documentation

Burger::ConsoleApp::GetArgc ( void ) const [inline]

Get the current argc parameter.

Accessor to get the current argc input value passed to main().

Returns:: Integer with the number of valid argv commands. Can be zero.

See also:: Burger::Console::GetArgv() const

Burger::ConsoleApp::GetArgv ( void ) const [inline]

Get the current argv parameter.

Accessor to get the current argv input value passed to main().

Returns:: NULL or pointer to an array of char pointers of command line parameters.

See also:: Burger::Console::GetArgc() const

Burger::ConsoleApp::GetReturnCode ( void ) const [inline]

Get the current return code.

Accessor to get the current return code that main() would give back to the operating system if the application exited immediately.

Returns:: Integer with main() return code.

int BURGER_API Burger::ConsoleApp::InputAndOutput	(	Burger::ConsoleApp::CallbackProc	pCallback,
		Burger::ConsoleApp::UsageProc	pUsage
	)

Function for 2 or 3 argument tools.

If the console application was invoked with argc == 2 or argc == 3, then execute the callback with a Burgerlib input filename and a NULL for the output filename (argc==2) or a burgerlib input filename and a burgerlib output filename (argc==3). There is no checking performed on the filenames to see if they are actually pointing to valid files.

If argc!=2 and argc!=3 then set the error code to 10 and then the pUsage function is called so that instructions can be displayed. If pUsage is NULL, no instructions will be printed.

Parameters:

	pCallback	Pointer to a function to perform the actual work.
	pUsage	Pointer to a function to print the instructions.

Returns:: The current error code. Can be returned to the operating system.

See also:: int Burger::ConsoleApp::SimpleTool(Burger::ConsoleApp::CallbackProc,Burger::ConsoleApp::UsageProc)

void Burger::ConsoleApp::PauseOnError ( void ) const

Pause console output if the return code is not zero.

If the return code is not set to zero, force the text output to remain on the screen if the application was launched from double clicking. If the application was launched from a console, this function does nothing.

Word BURGER_API Burger::ConsoleApp::ProcessFilenames ( Burger::ConsoleApp::CallbackProc pCallback )

Handle drag and drop for console apps.

Detect if the application was launched from the Finder or from Explorer. If so, detect if it was because data files were "dropped" on the application for processing. If both cases are true, then call the user supplied function pointer for each file to be processed. The filenames are in Burgerlib format.

Note:: This function will set the console return code to 1 on entry, so if the processing doesn't take place, it will assume an error has occurred. The processing procedure can set the return code to zero or any other value at will and that's the return code that will be retained.

Parameters:

pCallback

Function pointer to a call that accepts a Burgerlib filename.

Returns:: TRUE if the function pointer was called. FALSE if normal processing should occur.

Burger::ConsoleApp::SetArgc ( int iArgc ) [inline]

Set the current argc parameter.

Override the argc input value passed to main().

Parameters:

iArgc

New number of parameters present (Can be zero)

See also:: Burger::ConsoleApp::SetArgv(const char **)

Burger::ConsoleApp::SetArgv ( const char ** ppArgv ) [inline]

Set the current argv parameter.

Override the argv input value passed to main().

Parameters:

ppArgv

NULL or pointer to an array of char pointers of command line parameters.

See also:: Burger::ConsoleApp::Setargc(int)

Burger::ConsoleApp::SetReturnCode ( int iReturnCode ) [inline]

Set the value for main() to return.

When a console application exits, it's expected to return an integer value as an error code to the operating system. The default is zero, but with this call, an application can change the return value to any code for any reason, usually to denote an error condition.

Parameters:

iReturnCode

Return code for main() to send back to the operating system

int BURGER_API Burger::ConsoleApp::SimpleTool	(	Burger::ConsoleApp::CallbackProc	pCallback,
		Burger::ConsoleApp::UsageProc	pUsage
	)

Handle simple console applications.

For console applications that only accept 2 or 3 parameters, namely a file to input data and a file to output data, this helper function performs the drag and drop and mundane operations for setup and teardown of the command line.

All is needed are two callbacks, one for the actual console application's conversion function and the other for printing the instructions to the console.

Parameters: