Artistic Style Developer Information

Compile Options

To use Artistic Style with a Graphical User Interface (GUI) it is no longer necessary to remove the source module astyle_main.cpp and write embedded code to call the formatter.  AStyle can now be compiled as a static library or a shared library (DLL).  The entire source code can also be included in the project with the GUI source.

To compile AStyle for use in a GUI the compile option  ASTYLE_LIB  must be defined (e.g.-DASTYLE_LIB).  Then AStyle will accept the files and options as parameters from a function call.  It is the responsibility of the GUI to read the source files and accept the options from the user via the GUI.  These are then passed to AStyle via the function call described below.  After the source files are formatted they will be returned to the GUI.  The GUI must then save the source file and take other appropriate action.

AStyleMain Function

This function is called to format the source code.

Syntax

extern "C" char* STDCALL  AStyleMain (
    const char* pSourceIn,
    const char* pOptions,
    void  (STDCALL *fpError)(int, char*),
    char* (STDCALL *fpAlloc)(unsigned long)
);

Parameters

pSourceIn
A pointer to the source file to be formatted. 

pOptions
A pointer to the formatting options.  They should be in the same format as in the default options file.  The options may be set apart by new-lines, tabs or spaces. The long options do not need the '--' prefix.

If the file to be formatted is a java or C# file, the file mode option must be included (e.g. mode=java or mode=cs).

fpError
A pointer to the error handling function. If there are errors in the parameters pSourceIn or pOptions, this function is called.  It should display an error message and then either abort or continue the program depending on the error.  The first parameter is a number identifying the error.   The second parameter is a pointer to a standard error message.

Error messages numbered 100-199 are errors that prevent the file from being formatted.  A NULL pointer is returned to the calling program.  Error messages numbered 200-299 are errors that do NOT prevent the file from being formatted.  A valid pointer and a formatted file are returned.  This will occur if an invalid option is sent to AStyleMain.  The calling program has the option of accepting or rejecting the formatted file.

fpAlloc
A pointer to the memory allocation function. The calling program must allocate memory for the output source file.  This function will be called when the memory is needed.  The parameter is the amount of memory that should be allocated. 

Memory should be allocated using the operator "new (nothrow)". With this method, if there is a allocation exception, Artistic Style will generate an error message and return a NULL pointer from the AStyleMain function. The calling program can handle the exception at this point rather than in the memory allocation function. See the following example program for the procedure.

The calling program is responsible for freeing the allocated memory when it is no longer required.

Return Value

If the function succeeds, the return value is a pointer to the formatted source code.

If the function fails, the return value is NULL.

This function typically fails for one of the following reasons:

• an invalid parameter value, usually a NULL pointer.
• the memory allocation function (fpAlloc) returns a NULL.

Remarks

The STDCALL macro is defined for Windows as __stdcall.  It is needed if AStyle is compiled as a Windows static library or DLL.  For Linux it is defined but does not have a value.

The calling program is responsible for freeing the memory allocated by  fpAlloc when it is no longer needed.

Example

The following example formats source files by calling the Artistic Style formatter.  It is a console application but the procedure for a GUI is the same.  The example can be copied and pasted into a source file.  The Artistic Style source code must be added to the project and compiled with the option ASTYLE_LIB.  The AStyle source code can also be compiled as a static or shared library (DLL), with the option ASTYLE_LIB, and linked to the project.

 
// Example.cpp
/* This program calls the Artistic Style GUI formatter (AStyleMain)
 * to format the astyle source files in a 'test' directory.
 */
#include <fstream>
#include <iostream>
using namespace std;
// allow for different calling conventions in Linux and Windows
#ifdef _WIN32
#define STDCALL __stdcall
#else
#define STDCALL
#endif
#define FPS 30          // file path size
// functions to call AStyleMain
extern "C"
    char* STDCALL  AStyleMain(const char* pSourceIn,
                              const char* pOptions,
                              void(STDCALL *fpError)(int, char*),
                              char*(STDCALL *fpAlloc)(unsigned long));
void  STDCALL ASErrorHandler(int errorNumber, char* errorMessage);
char* STDCALL ASMemoryAlloc(unsigned long memoryNeeded);
// other functions
extern "C"
    char* STDCALL  AStyleGetVersion();
void error(const char *why, const char* what = "");
char* getText(char* testFileName);
void  setText(char* textOut, char* testFileName);
// global variables
char originalFileName[FPS];       // name of file to be formatted
char inFileName[FPS+5];           // name of file to be formatted + .orig
int main(int, char **)
{
    // options to pass to AStyle
    char testFileName[][FPS] = { "../test/ASBeautifier.cpp",
                                "../test/ASEnhancer.cpp" ,
                                "../test/ASFormatter.cpp" ,
                                "../test/ASResource.cpp" ,
                                "../test/astyle_main.cpp" ,
                                "../test/astyle.h"
                              };
    char* options = "-atOP";
    size_t arraySize = sizeof(testFileName) / sizeof(testFileName[0]);

    // get Artistic Style version
    char* version = AStyleGetVersion();

    cout << "\nArtistic Style " << version << endl;
    // process the input files
    for (size_t i = 0; i < arraySize; i++)
    {
        // get the text to format
        cout << "formatting " << testFileName[i] << endl;
        char* textIn = getText(testFileName[i]);

        // call the Artistic Style formatting function
        char* textOut = AStyleMain(textIn,
                                   options,
                                   ASErrorHandler,
                                   ASMemoryAlloc);

        // NULL pointer is an error
        // an error message has been displayed by the error handler
        if (textOut == NULL)
        {
            rename(inFileName, originalFileName);
            cout << "The file cannot be formatted!" << endl;
            return 0;
        }
        // return the formatted text
        setText(textOut, testFileName[i]);
        // must delete the temporary buffers
        delete [] textIn;
        delete [] textOut;
    }
}
// Error handler for the Artistic Style formatter
void  STDCALL ASErrorHandler(int errorNumber, char* errorMessage)
{
    cout << errorMessage << " (error " << errorNumber << ")" << endl;
}
// Allocate memory for the Artistic Style formatter
char* STDCALL ASMemoryAlloc(unsigned long memoryNeeded)
{
    // error condition is checked after return from AStyleMain
    char* buffer = new(nothrow) char [memoryNeeded];
    return buffer;
}
// Error message function for this example
void error(const char *why, const char* what)
{
    cout << why << ' ' << what << endl;
    cout << "The program has terminated!" << endl;
    exit(1);
}
// get the text to be formatted
// usually the text would be obtained from a GUI
char* getText(char* testFileName)
{
    // rename the input file
    strcpy(originalFileName, testFileName);
    strcpy(inFileName, originalFileName);
    strcat(inFileName, ".orig");
    remove(inFileName);
    if (rename(originalFileName, inFileName) < 0)
        error("Could not open input file", originalFileName);
    // open the input file
    ifstream in(inFileName);
    if (!in)
        error("Could not open input file", inFileName);
    // get length of buffer
    in.seekg(0, ifstream::end);
    int bufferSizeIn = in.tellg();
    in.seekg(0, ifstream::beg);
    // allocate memory
    char* bufferIn = new(nothrow) char [bufferSizeIn];
    if (bufferIn == NULL)
    {
        in.close();
        rename(inFileName, originalFileName);
        error("Memory allocation failure on input");
    }
    // read data as a block
    in.read(bufferIn, bufferSizeIn);
    in.close();
    // get actual size - will be smaller than buffer size
    int textSizeIn = in.gcount();
    bufferIn[textSizeIn-1] = '\0';
    return bufferIn;
}
// return the formatted text
// usually the text would be returned to a GUI
void setText(char* bufferOut, char* testFileName)
{
    // open the output file
    ofstream out(testFileName);
    if (!out)
        error("Could not open output file", testFileName);
    // write the text
    int textSizeOut = strlen(bufferOut);
    out.write(bufferOut, textSizeOut);
    out.close();
}