zproject_class.gsl

#   Generate project API
#
#   This is a code generator built using the iMatix GSL code generation
#   language. See https://github.com/imatix/gsl for details.
#
#   Copyright (c) the Contributors as noted in the AUTHORS file.
#   This file is part of zproject.
#
#   This Source Code Form is subject to the terms of the Mozilla Public
#   License, v. 2.0. If a copy of the MPL was not distributed with this
#   file, You can obtain one at http://mozilla.org/MPL/2.0/.

.macro generate_project_api
.#
.#  Build the project header file
.#
.directory.create ("include")
.if !file.exists ("include/$(project.header:)") & count (class, class.name = project.name) = 0
.   echo "Generating skeleton for include/$(project.header)"
.   output "include/$(project.header)"
/*  =========================================================================
    $(project.name) - $(project.description?'':)

.   for project.license
    $(string.trim (license.):block                                         )
.   endfor
    =========================================================================
*/

#ifndef $(PROJECT.HEADER:c)_H_INCLUDED
#define $(PROJECT.HEADER:c)_H_INCLUDED

//  Include the project library file
#include "$(project.prefix)_library.$(project.header_ext)"

//  Add your own public definitions here, if you need them

#endif
.else
.   echo "NOT regenerating an existing include/$(project.header) skeleton file; but you probably should not care"
.endif
.output "include/$(project.prefix)_library.$(project.header_ext)"
/*  =========================================================================
    $(project.name) - generated layer of public API

.   for project.license
    $(string.trim (license.):block                                         )
.   endfor

$(project.GENERATED_WARNING_HEADER:)
    =========================================================================
*/

#ifndef $(PROJECT.PREFIX)_LIBRARY_H_INCLUDED
#define $(PROJECT.PREFIX)_LIBRARY_H_INCLUDED

//  Set up environment for the application
.if file.exists ("include/$(project.prelude)")
#include "$(project.prelude)"
.endif

//  External dependencies
.for use where !defined (implied)
.    if (use.optional = 1)
.# TODO: Fix up GSL to only reference same macro once (e.g. if variants are
.# defined for OS packages named vastly different in various distros, like lua)
#if defined (HAVE_$(USE.AM_LIB_MACRO))
#include <$(use.header)>
#endif
.    else
#include <$(use.header)>
.    endif
.endfor

//  $(PROJECT.PREFIX) version macros for compile-time API detection
#define $(PROJECT.PREFIX)_VERSION_MAJOR $(project->version.major)
#define $(PROJECT.PREFIX)_VERSION_MINOR $(project->version.minor)
#define $(PROJECT.PREFIX)_VERSION_PATCH $(project->version.patch)

#define $(PROJECT.PREFIX)_MAKE_VERSION(major, minor, patch) \\
    ((major) * 10000 + (minor) * 100 + (patch))
#define $(PROJECT.PREFIX)_VERSION \\
    $(PROJECT.PREFIX)_MAKE_VERSION($(PROJECT.PREFIX)_VERSION_MAJOR, $(PROJECT.PREFIX)_VERSION_MINOR, $(PROJECT.PREFIX)_VERSION_PATCH)

#if defined (__WINDOWS__)
#   if defined $(PROJECT.PREFIX)_STATIC
#       define $(PROJECT.PREFIX)_EXPORT
#   elif defined $(PROJECT.PREFIX)_INTERNAL_BUILD
#       if defined DLL_EXPORT
#           define $(PROJECT.PREFIX)_EXPORT __declspec(dllexport)
#       else
#           define $(PROJECT.PREFIX)_EXPORT
#       endif
#   elif defined $(PROJECT.PREFIX)_EXPORTS
#       define $(PROJECT.PREFIX)_EXPORT __declspec(dllexport)
#   else
#       define $(PROJECT.PREFIX)_EXPORT __declspec(dllimport)
#   endif
#   define $(PROJECT.PREFIX)_PRIVATE
#elif defined (__CYGWIN__)
#   define $(PROJECT.PREFIX)_EXPORT
#   define $(PROJECT.PREFIX)_PRIVATE
#else
#   define $(PROJECT.PREFIX)_EXPORT
#   if (defined __GNUC__ && __GNUC__ >= 4) || defined __INTEL_COMPILER
#       define $(PROJECT.PREFIX)_PRIVATE __attribute__ ((visibility ("hidden")))
#   else
#       define $(PROJECT.PREFIX)_PRIVATE
#   endif
#endif

.if !project.stable
//  Project has no stable classes, so we build the draft API
#undef  $(PROJECT.PREFIX)_BUILD_DRAFT_API
#define $(PROJECT.PREFIX)_BUILD_DRAFT_API

.endif
//  Opaque class structures to allow forward references
//  These classes are stable or legacy and built in all releases
.for project.class where scope = "public" & !draft
typedef struct _$(class.c_name:)_t $(class.c_name:)_t;
#define $(CLASS.C_NAME:c)_T_DEFINED
.endfor
.for project.class where scope = "public" & draft
.   if first ()
//  Draft classes are by default not built in stable releases
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
typedef struct _$(class.c_name:)_t $(class.c_name:)_t;
#define $(CLASS.C_NAME:c)_T_DEFINED
.   if last ()
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.endfor

.for constant
.   resolve_c_constant (constant, "draft")
.endfor
.if count (constant, scope = "public")
//  Public constants
.endif
.for constant where scope = "public" & !draft
#define $(CONSTANT.NAME)\
                            $(constant.value)  //  $(constant.?'')
.endfor
.for constant where scope = "public" & draft
.   if first ()
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
#define $(CONSTANT.NAME)\
                            $(constant.value)  //  $(constant.?'')
.   if last ()
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.endfor

//  Public classes, each with its own header file
.for header where scope = "public"
#include "$(header.name:$(project.filename_prettyprint)).$(project.header_ext)"
.endfor
.for class where scope = "public" & class.c_name <> "$(project.name)" & !draft
#include "$(class.name:$(project.filename_prettyprint)).$(project.header_ext)"
.endfor
.for class where scope = "public" & class.c_name <> "$(project.name)" & draft
.   if first ()
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
#include "$(class.name:$(project.filename_prettyprint)).$(project.header_ext)"
.   if last ()
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.endfor

#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
//  Self test for private classes
$(PROJECT.PREFIX)_EXPORT void
    $(project.prefix)_private_selftest (bool verbose, const char *subtest);
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API

#endif
/*
$(project.GENERATED_WARNING_HEADER:)
*/
.#
.#  Build the project selftest program
.#
.if project.use_cxx
.output "src/$(project.prefix)_selftest.$(project.source_ext)"
.else
.output "src/$(project.prefix)_selftest.$(project.source_ext)"
.endif
/*  =========================================================================
    $(project.prefix)_selftest.c - run selftests

    Runs all selftests.

    -------------------------------------------------------------------------
.   for project.license
    $(string.trim (license.):block                                         )
.   endfor

$(project.GENERATED_WARNING_HEADER:)
    =========================================================================
*/

#include "$(project.prefix)_classes.$(project.header_ext)"

#include <stdio.h>
#include <string.h>

typedef struct {
    const char *testname;           // test name, can be called from command line this way
    void (*test) (bool);            // function to run the test (or NULL for private tests)
    bool stable;                    // true if class is declared as stable
    bool pub;                       // true if class is declared as public
    const char *subtest;            // name of private subtest to run
} test_item_t;

static test_item_t
all_tests [] = {
.for class where !draft & selftest & private ?<> 1
.   if first ()
// Tests for stable public classes:
.   endif
    { "$(class.c_name)", $(class.c_name)_test, true, true, NULL },
.endfor
.for class where draft & selftest & private ?<> 1
.   if first ()
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
// Tests for draft public classes:
.   endif
    { "$(class.c_name)", $(class.c_name)_test, false, true, NULL },
.   if last ()
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.endfor
.for class where selftest & private ?= 1
.   if first ()
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
// Tests for stable/draft private classes:
// Now built only with --enable-drafts, so even stable builds are hidden behind the flag
.   endif
.   if class.draft = 1
    { "$(class.c_name)", NULL, false, false, "$(class.c_name)_test" },
.   else
    { "$(class.c_name)", NULL, true, false, "$(class.c_name)_test" },
.   endif
.   if last ()
    { "private_classes", NULL, false, false, "$ALL" }, // compat option for older projects
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.endfor
    {0, 0, 0}          //  Sentinel
};

//  -------------------------------------------------------------------------
//  Test whether a test is available.
//  Return a pointer to a test_item_t if available, NULL otherwise.
//

test_item_t *
test_available (const char *testname)
{
    test_item_t *item;
    for (item = all_tests; item->testname; item++) {
        if (strcmp (testname, item->testname) == 0)
            return item;
    }
    return NULL;
}

//  -------------------------------------------------------------------------
//  Run all tests.
//

static void
test_runall (bool verbose)
{
    test_item_t *item;
    printf ("Running $(project.name) selftests...\\n");
    for (item = all_tests; item->testname; item++) {
        if (strcmp (item->testname, "private_classes") == 0)
            continue;
        if (!item->subtest)
            item->test (verbose);
        else
            $(project.prefix)_private_selftest (verbose, item->subtest);
    }

    printf ("Tests passed OK\\n");
}

static void
test_list (void)
{
    test_item_t *item;
    puts ("Available tests:");
    for (item = all_tests; item->testname; item++)
        printf ("    %-40s - %s\t%s\\n",
            item->testname,
            item->stable ? "stable" : "draft",
            item->pub ? "public" : "private"
        );
}

static void
test_number (void)
{
    int n = 0;
    test_item_t *item;
    for (item = all_tests; item->testname; item++) {
        if (! strcmp (item->testname, "private_classes") == 0)
            n++;
    }
    printf ("%d\\n", n);
}

int
main (int argc, char **argv)
{
    bool verbose = false;
    test_item_t *test = 0;
    int argn;
    for (argn = 1; argn < argc; argn++) {
        if (strcmp (argv [argn], "--help") == 0
        ||  strcmp (argv [argn], "-h") == 0) {
            puts ("$(project.prefix)_selftest.c [options] ...");
            puts ("  --verbose / -v         verbose test output");
            puts ("  --number / -n          report number of tests");
            puts ("  --list / -l            list all tests");
            puts ("  --test / -t [name]     run only test 'name'");
            puts ("  --continue / -c        continue on exception (on Windows)");
            return 0;
        }
        if (strcmp (argv [argn], "--verbose") == 0
        ||  strcmp (argv [argn], "-v") == 0)
            verbose = true;
        else
        if (strcmp (argv [argn], "--number") == 0
        ||  strcmp (argv [argn], "-n") == 0) {
            test_number ();
            return 0;
        }
        else
        if (strcmp (argv [argn], "--list") == 0
        ||  strcmp (argv [argn], "-l") == 0) {
            test_list ();
            return 0;
        }
        else
        if (strcmp (argv [argn], "--test") == 0
        ||  strcmp (argv [argn], "-t") == 0) {
            argn++;
            if (argn >= argc) {
                fprintf (stderr, "--test needs an argument\\n");
                return 1;
            }
            test = test_available (argv [argn]);
            if (!test) {
                fprintf (stderr, "%s not valid, use --list to show tests\\n", argv [argn]);
                return 1;
            }
        }
        else
        if (strcmp (argv [argn], "--continue") == 0
        ||  strcmp (argv [argn], "-c") == 0) {
#ifdef _MSC_VER
            //  When receiving an abort signal, only print to stderr (no dialog)
            _set_abort_behavior (0, _WRITE_ABORT_MSG);
#endif
        }
        else {
            printf ("Unknown option: %s\\n", argv [argn]);
            return 1;
        }
    }

    #ifdef NDEBUG
        printf(" !!! 'assert' macro is disabled, remove NDEBUG from your compilation definitions.\\n");
        printf(" tests will be meaningless.\\n");
    #endif //

    if (test) {
        printf ("Running $(project.name) test '%s'...\\n", test->testname);
        if (!test->subtest)
            test->test (verbose);
        else
            $(project.prefix)_private_selftest (verbose, test->subtest);
    }
    else
        test_runall (verbose);

    return 0;
}
/*
$(project.GENERATED_WARNING_HEADER:)
*/
.#
.#  Build the project private classes selftest module
.#
.if project.use_cxx
.output "src/$(project.prefix)_private_selftest.$(project.source_ext)"
.else
.output "src/$(project.prefix)_private_selftest.$(project.source_ext)"
.endif
/*  =========================================================================
    $(project.prefix)_private_selftest.c - run private classes selftests

    Runs all private classes selftests.

    -------------------------------------------------------------------------
.   for project.license
    $(string.trim (license.):block                                         )
.   endfor

$(project.GENERATED_WARNING_HEADER:)
    =========================================================================
*/

#include "$(project.prefix)_classes.$(project.header_ext)"


//  -------------------------------------------------------------------------
//  Run all private classes tests.
//

void
$(project.prefix)_private_selftest (bool verbose, const char *subtest)
{
.for class where !draft & selftest & private ?= 1
.   if first ()
// Tests for stable private classes:
.   endif
    if (streq (subtest, "$ALL") || streq (subtest, "$(class.c_name)_test"))
        $(class.c_name)_test (verbose);
.endfor
.for class where draft & selftest & private ?= 1
.   if first ()
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
// Tests for draft private classes:
.   endif
    if (streq (subtest, "$ALL") || streq (subtest, "$(class.c_name)_test")
        $(class.c_name)_test (verbose);
.   if last ()
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.endfor
}
/*
$(project.GENERATED_WARNING_HEADER:)
*/
.-
.-  Build the classes header for private header files and constants
.-
.output "src/$(project.prefix)_classes.$(project.header_ext)"
/*  =========================================================================
    $(project.prefix)_classes - private header file

.   for project.license
    $(string.trim (license.):block                                         )
.   endfor
$(project.GENERATED_WARNING_HEADER:)
    =========================================================================
*/

#ifndef $(PROJECT.PREFIX)_CLASSES_H_INCLUDED
#define $(PROJECT.PREFIX)_CLASSES_H_INCLUDED

//  Platform definitions, must come first
#include "platform.h"

//  External API
#include "../include/$(project.header:)"

//  Extra headers
.for header where scope = "private"
#include "$(header.name:$(project.filename_prettyprint)).$(project.header_ext)"
.endfor

//  Opaque class structures to allow forward references
.for class where scope = "private"
#ifndef $(CLASS.C_NAME:c)_T_DEFINED
typedef struct _$(class.c_name:)_t $(class.c_name:)_t;
#define $(CLASS.C_NAME:c)_T_DEFINED
#endif
.endfor

//  Internal API
.for class where scope = "public"
.   visibility = "$(PROJECT.PREFIX)_PRIVATE"
.   for class.method where private
//  $(method.description:no,block)
.       if method->return.fresh
//  Caller owns return value and must destroy it when done.
.       endif
$(VISIBILITY) $(c_method_signature (method):)\
.       if defined(method.format_index)
 CHECK_PRINTF ($(method.format_index));
.       else
;
.       endif

.   endfor
.endfor

.for class where scope = "private"
#include "$(class.name:$(project.filename_prettyprint)).$(project.header_ext)"
.endfor

//  *** To avoid double-definitions, only define if building without draft ***
#ifndef $(PROJECT.PREFIX)_BUILD_DRAFT_API
.for class where draft = 0
.   for constant where draft = 1
.      if first ()

//  *** Draft constants, defined for internal use only ***
.      endif
#define $(CLASS.NAME:c)_$(NAME:c) $(value)  // $(constant.description:no,block)
.   endfor
.   for class.callback_type where draft = 1
.      if first ()

//  *** Draft callbacks, defined for internal use only ***
.      endif
// $(callback_type.description:no,block)
$(c_callback_typedef (callback_type))
.   endfor
.   for . as method where draft = 1
.       if name () = "constructor" | name () = "method" | name () = "destructor"

//  *** Draft method, defined for internal use only ***
//  $(.description:no,block)
.           if ->return.fresh
//  Caller owns return value and must destroy it when done.
.           endif
$(PROJECT.PREFIX)_PRIVATE $(c_method_signature (method):)\
.           if defined(method.format_index)
 CHECK_PRINTF ($(method.format_index));
.           else
;
.           endif
.       endif
.   endfor
.endfor

//  Self test for private classes
$(PROJECT.PREFIX)_PRIVATE void
    $(project.prefix)_private_selftest (bool verbose, const char *subtest);

#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API

.for constant where scope = "private"
.   if first ()
//  Private constants
.   endif
#define $(CONSTANT.NAME)\t$(constant.value) //  $(constant.?'')
.endfor
#endif
.close
.#  Generate API interface
.macro method_state_comment (state)
.       if my.state = "draft"
//  *** Draft method, for development use, may change without warning ***
.       elsif my.state = "legacy"
//  *** Deprecated method, slated for removal: avoid using it ***
.       endif
.endmacro
.macro generate_interface (draft)
.   if class.scope = "private"
.      visibility = "$(PROJECT.PREFIX)_PRIVATE"
.   else
.      visibility = "$(PROJECT.PREFIX)_EXPORT"
.   endif
.   for class.constant where draft = my.draft
#define $(CLASS.NAME:c)_$(NAME:c) $(value)  // $(constant.description:no,block)
.   if last ()

.   endif
.   endfor
.   for class.callback_type where draft = my.draft
// $(callback_type.description:no,block)
$(c_callback_typedef (callback_type))

.   endfor
.   for class.constructor where draft = my.draft
.       method_state_comment (state)
//  $(constructor.description:no,block)
$(VISIBILITY) $(c_method_signature (constructor):)\
.       if defined(constructor.format_index)
 CHECK_PRINTF ($(constructor.format_index));
.       else
;
.       endif

.   endfor
.   for class.destructor where draft = my.draft
.       method_state_comment (state)
//  $(destructor.description:no,block)
$(VISIBILITY) $(c_method_signature (destructor):)\
.       if defined(destructor.format_index)
 CHECK_PRINTF ($(destructor.format_index));
.       else
;
.       endif

.   endfor
.   for class.actor where draft = my.draft
//  $(actor.description:no,block)
$(VISIBILITY) void
    $(actor.name:c) (zsock_t *pipe, void *args);

.   endfor
.   for class.method where draft = my.draft & !private
.       method_state_comment (state)
//  $(method.description:no,block)
.       if method->return.fresh
//  Caller owns return value and must destroy it when done.
.       endif
$(VISIBILITY) $(c_method_signature (method):)\
.       if defined(method.format_index)
 CHECK_PRINTF ($(method.format_index));
.       else
;
.       endif

.   endfor
.endmacro
.template 0
#
#  Regenerate the @interface for the class if it has an API model
#

for class
    skeleton_class_header ()
    skeleton_class_source ()

    if !defined (class.api)
        resolve_c_class (class)
    endif
    if defined (class.api)
        handle = file.open (class.header, "ra")
        current_loc = "prefix"
        error = # undefined
        HEADER_FILE_PREFIX = "" # All lines preceding the @interface line
        HEADER_FILE_SUFFIX = "" # All lines following the @end line

        # Read each line from the file and pull out the prefix and suffix blocks
        while defined (handle)
            this_line = handle.read (error)? ""

            if defined (error)
                handle.close ()
                handle = # undefined
            elsif current_loc = "prefix"
                if regexp.match ("//\\s*@interface", this_line)
                    current_loc = "interface"
                elsif regexp.match ("//\\s*@warning", this_line)
                    # ignore the warning line - do not copy it
                else
                    HEADER_FILE_PREFIX += this_line
                endif
            elsif current_loc = "interface"
                if regexp.match ("//\\s*@end", this_line)
                    current_loc = "suffix"
                endif
            elsif current_loc = "suffix"
                HEADER_FILE_SUFFIX += this_line
            endif
        endwhile

        #   Now output the file with stored prefix, generated interface,
        #   and stored suffix
        output class.header
        template 1
$(HEADER_FILE_PREFIX:)\
//  @warning THE FOLLOWING @INTERFACE BLOCK IS AUTO-GENERATED BY ZPROJECT
//  @warning Please edit the model at "$(class.api)" to make changes.
//  @interface
.   if !project.stable
//  This API is a draft, and may change without notice.
.   elsif class.state = "draft"
//  This is a draft class, and may change without notice. It is disabled in
//  stable builds by default. If you use this in applications, please ask
//  for it to be pushed to stable state. Use --enable-drafts to enable.
.   elsif class.state = "stable"
//  This is a stable class, and may not change except for emergencies. It
//  is provided in stable builds.
.       if count (class.method, method.state = "draft")
//  This class has draft methods, which may change over time. They are not
//  in stable releases, by default. Use --enable-drafts to enable.
.       endif
.   if count (class.method, method.state = "legacy")
//  This class has legacy methods, which will be removed over time. You
//  should not use them, and migrate any code that is still using them.
.   endif
.   elsif class.state = "legacy"
//  This is a deprecated class, and will be removed over time. It is
//  provided in stable builds to support old applications. You should
//  stop using this class, and migrate any code that is still using it.
.   endif
.   generate_interface (0)
.   if count (class., count.draft ?= 1)
#ifdef $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
.   generate_interface (1)
.   if count (class., count.draft ?= 1)
#endif // $(PROJECT.PREFIX)_BUILD_DRAFT_API
.   endif
//  @end
$(HEADER_FILE_SUFFIX:)\
.       endtemplate
        close
    endif
endfor
.endtemplate
.endmacro

if count (class)
    for project.class
        if !defined (class.api)
            resolve_c_class (class)
        endif
    endfor
    generate_project_api ()
endif