src/c2html.h

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2016 Mike Becker. All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 */

#ifndef C2HTML_H
#define C2HTML_H

#include <stdio.h>
#include "highlighter.h"

#ifdef __cplusplus
extern "C" {
#endif
    
#define VERSION_MAJOR   2
#define VERSION_MINOR   0
#define VERSION_DEVELOP 0 /* set this to zero for release version */

/**
 * Reads a source file from the input buffer and writes at most
 * <code>maxlen</code> bytes of the formatted output to the output buffer.
 * 
 * The output buffer must either be large enough to hold <code>maxlen</code>
 * bytes or the write function must trigger an automatic extension of the
 * buffer.
 * 
 * The input is copied via an intermediate buffer to an internal buffer.
 * 
 * @param inputbuffer the input buffer
 * @param rfnc a read function operating for the input buffer
 * @param ibuf intermediate processing buffer
 * @param ibuflen length of intermediate processing buffer
 * @param outputbuffer the output buffer
 * @param wfnc a write function for the output buffer
 * @param maxlen the maximum amount bytes which will be written to the
 * output buffer
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @return total amount of bytes written to the output buffer
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
size_t c2html_formatn(void* inputbuffer, read_func rfnc,
        char* ibuf, size_t ibuflen, void* outputbuffer, write_func wfnc,
        size_t maxlen, c2html_highlighter_func hltr, int showln);
    
/**
 * Reads a source file from the input buffer and writes the formatted output
 * to an output buffer.
 * 
 * The output buffer must either be large enough to hold the formatted data
 * or the write function must trigger an automatic extension of the buffer.
 * 
 * The input is copied via an intermediate buffer to an internal buffer.
 * 
 * @param inputbuffer the input buffer
 * @param rfnc a read function operating for the input buffer
 * @param ibuf intermediate processing buffer
 * @param ibuflen length of intermediate processing buffer
 * @param outputbuffer the output buffer
 * @param wfnc a write function for the output buffer
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @return total amount of bytes written to the output buffer
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
size_t c2html_format(void* inputbuffer, read_func rfnc,
        char* ibuf, size_t ibuflen, void* outputbuffer, write_func wfnc,
        c2html_highlighter_func hltr, int showln);

/**
 * Reads a source file from the specified input file stream and writes the
 * formatted output to an output buffer.
 * 
 * The output buffer must either be large enough to hold the formatted data
 * or the write function must trigger an automatic extension of the buffer.
 * 
 * The input is copied via an intermediate buffer to an internal buffer.
 * For files, the recommended intermediate buffer length is the file system
 * block size.
 * 
 * @param inputfile the input file stream
 * @param ibuf intermediate processing buffer
 * @param ibuflen length of intermediate processing buffer
 * @param outputbuffer the output buffer
 * @param wfnc a write function for the output buffer
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @return total amount of bytes written to the output buffer
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
size_t c2html_fformat(FILE* inputfile, char *ibuf, size_t ibuflen,
        void* outputbuffer, write_func wfnc,
        c2html_highlighter_func hltr, int showln);

/**
 * Reads a source file from the specified input file stream and directly writes
 * the formatted output to the output file stream.
 * 
 * For files, the recommended intermediate buffer length is the file system
 * block size.
 * 
 * @param inputfile the input file stream
 * @param ibuf intermediate processing buffer
 * @param ibuflen length of intermediate processing buffer (recommended: 4 KB)
 * @param outputfile the output file stream
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
void c2html_fformatf(FILE *inputfile, char *ibuf, size_t ibuflen,
        FILE* outputfile, c2html_highlighter_func hltr, int showln);


/**
 * Writes at most <code>maxlen</code> bytes of formatted source data to the
 * output buffer.
 * 
 * @param inputbuffer the source file data as string
 * @param inputbuflen the length of the source file
 * @param outputbuffer the output buffer
 * @param wfnc a write function for the output buffer
 * @param maxlen the maximum amount bytes which will be written to the
 * output buffer
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @return total amount of bytes written to the output buffer
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
size_t c2html_bformatn(const char* inputbuffer, size_t inputbuflen,
        void* outputbuffer, write_func wfnc,
        size_t maxlen, c2html_highlighter_func hltr, int showln);
    

/**
 * Writes the formatted source data to the output buffer.
 * 
 * @param inputbuffer the source file data as string
 * @param inputbuflen the length of the source file
 * @param outputbuffer the output buffer
 * @param wfnc a write function for the output buffer
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @return total amount of bytes written to the output buffer
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
size_t c2html_bformat(const char* inputbuffer, size_t inputbuflen,
        void* outputbuffer, write_func wfnc,
        c2html_highlighter_func hltr, int showln);


/**
 * Writes the formatted source data directly to the specified file stream.
 * 
 * @param inputbuffer the source file data as string
 * @param inputbuflen the length of the source file
 * @param outputfile the output file stream
 * @param hltr the highlighter function
 * @param showln zero, if line numbers shall be omitted, nonzero otherwise
 * 
 * @see c2html_plain_highlighter()
 * @see c2html_c_highlighter()
 * @see c2html_java_highlighter()
 */
void c2html_bformatf(const char* inputbuffer, size_t inputbuflen,
        FILE* outputfile, c2html_highlighter_func hltr, int showln);

#ifdef __cplusplus
}
#endif

#endif /* C2HTML_H */