MkKernel_Parser_Local_C_API

local : define the __parser__ attribute related to a __parser__(...) … More...

Collaboration diagram for MkKernel_Parser_Local_C_API:

Macros
#define	__parser__alias   alias=ALIAS
	Use alias as public-api-name …
#define	__parser__arg_name   arg-name=NAME
	Rename an already defined argument to arg-name at POSITION (0,1,2,…) …
#define	__parser__arg_type   arg-type=TYPE
	Redefine an already defined argument-type to arg-type at POSITION (0,1,2,…) …
#define	__parser__arg_type_vcv   arg-type-vcv=ARRAY-LEN@ARRY-PTR
	Define a ME_VCV meta-type as array-of-strings …
#define	__parser__argument   argument
	Mark argument as ordinary argument and NOT as instance-argument …
#define	__parser__cast   cast=TYPE
	Force to cast into a TYPE of the method-argument …
#define	__parser__class   class=CLASS
	Force to use class as CLASS of the instance-method …
#define	__parser__class_overload   class-overload
	The class-overload does not generate a method-code in the object-Target-Programming-Language (TPL) …
#define	__parser__const   const
	Add the const prefix in front of the Target-Programming-Language (TPL) public API method …
#define	__parser__constructor   constructor
	Mark the function as instance-constructor …
#define	__parser__default   default=VALUE
	Add a default to a function-argument …
#define	__parser__destructor   destructor
	Mark function as instance destructor …
#define	__parser__enum_accept_integer   enum-accept-integer=int32|int64|long
	define datatype for enum integer value …
#define	__parser__enum_is_flag   enum-is-flag
	Add enum-is-flag feature to a enum …
#define	__parser__error_check   error-check
	Verify the enum-return-value of a function using the enum-error-check-code …
#define	__parser__flags   flags=FLAGS
	Add flags in front of the target-programming-language public API method …
#define	__parser__has_reference   has-reference
	Force a reference-type overload to be defined by the PLMK (Programming-Language-Micro-Kernel)-Compiler …
#define	__parser__hide   hide=BOOL|NAME
	hide a function from the public-api …
#define	__parser__global__hide_rx   hide-rx@LIST=REGEXP
	Hide all functions found by REGEXP …
#define	__parser__ignore   ignore
	Mark OBJECT to be ignore - not used in public-api …
#define	__parser__ignore_error   ignore-error=BOOL|NUMBER|2
	Ignore the MkErrorE error-indicator …
#define	__parser__in   in
	The attribute (in|out|inout) marks an argument as input, output, or both …
#define	__parser__out   out
	The attribute (in|out|inout) marks an argument as input, output, or both …
#define	__parser__inout   inout
	The attribute (in|out|inout) marks an argument as input, output, or both …
#define	__parser__inline   inline=INLINE
	add inline function as alternativ function …
#define	__parser__internal   internal
	make function, function-argument, type, variable invisible to the public API …
#define	__parser__keep   keep
	keep the function if the default-behaviour is to hide the function …
#define	__parser__keep_destr   keep-destr
	Do not replace the keep-destr destructor with the lng-destr default-destructor …
#define	__parser__keep_original_type   keep-original-type
	Do not try to map the type of an argument into a Programming-Language-Micro-Kernel (PLMK) type …
#define	__parser__library   library=NAME@TYPE@NAMESPACE
	Define the new library name, namespace and usage …
#define	__parser__lng_constr   lng-constr
	Define a constructor as the default-constructor …
#define	__parser__lng_destr   lng-destr
	Replace all destructors with the lng-destr default-destructor …
#define	__parser__lng_dispose   lng-dispose
	Mark a function to be the default-dispose function …
#define	__parser__macro   macro
	Define that a declaration belongs to a macro …
#define	__parser__no_alias   no-alias
	Delete the alias attribute for function …
#define	__parser__no_inline   no-inline
	Do not make this function inline …
#define	__parser__no_rpc   no-rpc
	Do not create a rpc-call for this function …
#define	__parser__no_static   no-static
	Do not add the static attibute to the TPL-wrapper. …
#define	__parser__no_type_extension   no-type-extension
	Disable the type-extension feature from function …
#define	__parser__no_size   no-size
	Hide the size information from the binary-object …
#define	__parser__null_allow   null-allow
	Allow a function-argument of type class to be a MK_NULL (None) value …
#define	__parser__null_return_allow   null-return-allow
	Allow the function to return a MK_NULL (None) value …
#define	__parser__null_return_check   null-return-check
	Mark the function as pseudo-instance-constructor …
#define	__parser__overload   overload=OVERLOAD
	Add an additional overload function to the original-function in the Target-Programming-Language (TPL) …
#define	__parser__overload_c_no   overload-c-no
	do not create the overload for function in C …
#define	__parser__prefix   prefix=PREFIX
	Force prefix to be prefix …
#define	__parser__reference   reference
	Mark an object as reference …
#define	__parser__return_type   return-type=TYPE
	Replace an already defined return-type …
#define	__parser__return_type_default_no   return-type-default-no
	Undo the return-type-default for a specific function…
#define	__parser__runtime   runtime=FUNC-NAME
	Add a public API function FUNC-NAME for a runtime-aware function…
#define	__parser__static   static
	Force a function to be a class-methode even if PLMK (Programming-Language-Micro-Kernel)-Compiler would chose an instance-method …
#define	__parser__template_overload   template-overload
	Assume a predefined template to implement the function …
#define	__parser__template_in_c   template-in-c
	The template is written in the C language and not in the Target-Programming-Language (TPL) language …
#define	__parser__template_required   template-required
	Require a predefined template to implement the function …
#define	__parser__type   type=META@DESCRIPTION
	Define the meta-type for the public-type …
#define	__parser__wrapper   wrapper
	Add a wrapper to the default value of a function-argument …

Detailed Description

local : define the __parser__ attribute related to a __parser__(...) …

See also

__parser__(...)

Macro Definition Documentation

__parser__alias

#define __parser__alias   alias=ALIAS

Use alias as public-api-name …

In the meta-code-library-definition-file (META-FILE) alias attribute will flip the definition, the new alias will be the "official" function-name and the original-function-name will be the alias attribute.

In the TPL-Wrapper the "official" function-name is defined but "internal" the original-function-name is used.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:alias=ALIAS);
usage	__parser__(alias=ALIAS) FUNCTION …
see also	__parser__(no-alias)

Example

define alias for a function - visualize the alias-flip

// header file
__parser__(alias=MkObjDup)
MK_EXTERN MK_OBJ MK_DECL MkObjDup_TEST (
  MK_OBJ const srcobj
) MK_HDL_NONNULL_ATTR_1;
 
// meta file
attributeDEF    MkObjDup,alias      MkObjDup_TEST
...
funcDEF         MkObjDup            ME_OBC               {{ME_OBC srcobj}}

Definition at line 65 of file parser_mk.h.

__parser__arg_name

#define __parser__arg_name   arg-name=NAME

Rename an already defined argument to arg-name at POSITION (0,1,2,…) …

The goal is to reuse an already availalable declaration from an external header-file and add some special features like:

1. add _out or _inout to the argument name to signal further processing

Also usefull if a native-code is parsed and global is used to modify parse output.

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:POSITION:arg-name=NEW-NAME)
usage	FUNCTION(type NAME __parser__(arg-name=NEW-NAME) ...
example	__parser__global__(LcConfigLookupFloat:2:arg-name=value_out);
note	A NAME or an INDEX is allowed as POSITION, the INDEX starts at 0
note	The POSITION is used internal in the [lset funcDEF($func) 1 $POSITION end NEW-NAME] TCL code
see also	__parser__(arg-type)

Example

The sqlite3 native-library header

SQLITE_API int sqlite3_exec(
  sqlite3*,                                  /* An open database */
  const char *sql,                           /* SQL to be evaluated */
  int (*callback)(void*,int,char**,char**),  /* Callback function */
  void *,                                    /* 1st argument to callback */
  char **errmsg                              /* Error msg written here */
);

The sqlite3_sq3.h meta-code header

// define the callback
__parser__global__(sqlite3_exec:callback-name=LiteExec);
__parser__global__(sqlite3_exec:callback-null=yes);
__parser__global__(sqlite3_exec:callback-once=yes);
__parser__global__(sqlite3_exec:callback_call:callback-call=yes);
__parser__global__(sqlite3_exec:callback_data:callback-data=yes);
 
// callback-call argument name is "callback_call"
__parser__global__(sqlite3_exec:2:arg-name=callback_call);
 
// callback-data argument name is "callback_data"
__parser__global__(sqlite3_exec:3:arg-name=callback_data);
 
// SPECIAL: the double index (2:0...) is applied to the inner "callback" function type of "sqlite3_exec"
__parser__global__(sqlite3_exec:2:0:arg-name=callV1); // attention name of the INDEX=0 argument in TYPE
__parser__global__(sqlite3_exec:2:0:arg-type=MK_CBP);
__parser__global__(sqlite3_exec:2:1:arg-name=num);
__parser__global__(sqlite3_exec:2:2:arg-name=vals);
__parser__global__(sqlite3_exec:2:3:arg-name=cols);
 
__parser__global__(sqlite3_exec:errmsg:internal=yes);
__parser__global__(sqlite3_exec:errmsg:default=NULL);

Definition at line 94 of file parser_mk.h.

__parser__arg_type

#define __parser__arg_type   arg-type=TYPE

Redefine an already defined argument-type to arg-type at POSITION (0,1,2,…) …

The goal is to reuse an already availalable declaration from an external header-file and add some special features like:

1. replace an "int" argument with an "enum" or "bool" type

Also usefull if a native-code is parsed and global is used to modify parse output.

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:POSITION:arg-type=NEW-TYPE)
usage	FUNCTION(TYPE argument __parser__(arg-type=NEW-TYPE) ...)
example	__parser__global__(LcConfigGetOption:1:arg-type=LcConfigOptionsEF);
see also	__parser__(return-type); __parser__(arg-type-vcv); __parser__(arg-name)

Example

• look to example form __parser__(arg-name)

Definition at line 115 of file parser_mk.h.

__parser__arg_type_vcv

#define __parser__arg_type_vcv   arg-type-vcv=ARRAY-LEN@ARRY-PTR

Define a ME_VCV meta-type as array-of-strings …

An array-of-strings is defined in C as a pointer-to-a-array-of-strings and the number-of-strings-in-the-array.

• These two arguments are combined into one meta-type called ME_VCV.

Definition

scope	global and function
usage	__parser__global__(FUNCTION:arg-type-vcv=ARRAY-LEN@ARRY-PTR)
usage	__parser__(arg-type-vcv=ARRAY-LEN@ARRY-PTR) FUNCTION ...
see also	__parser__(arg-type)

Example

#1 the sqlite3_sq3.h meta-code header

__parser__global__(sqlite3_create_filename:arg-type-vcv=nParam@azParam);

#2 the sqlite3.h native-library header

SQLITE_API sqlite3_filename sqlite3_create_filename(
  const char *zDatabase,
  const char *zJournal,
  const char *zWal,
  int nParam,
  const char **azParam
);

Definition at line 137 of file parser_mk.h.

__parser__argument

#define __parser__argument   argument

Mark argument as ordinary argument and NOT as instance-argument …

By default the type of the first argument is checked for a class-instance-type and if found the function is used as class-instance-methode. If this is not desired use the argument attribute.

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:argument=yes);
usage	FUNCTION ( type ARGUMENT __parser__(argument) ... )

Example

__parser__(no-type-extension,overload=MqFactoryGetCalled)
MQ_EXTERN MQ_FCT MK_DECL MqFactoryGetCalledL_RT (
  MK_RT_PARSER
  MK_BFLN largs   __parser__(argument)
) MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL;

Definition at line 152 of file parser_mk.h.

__parser__cast

#define __parser__cast   cast=TYPE

Force to cast into a TYPE of the method-argument …

By default the original-type is choosen from the method-argument but if the original-type is not sufficient (example: int to bool) the type can be casted. A cast is only required if there is not an default-cast or if the new-type is used as pointer-value-output.

Usage

A cast is used together with arg-type.

__parser__global__(FUNCTION:ARGUMENT:arg-type=NEW-TYPE);
__parser__global__(FUNCTION:ARGUMENT:cast=OLD-TYPE);

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:cast=OLD-TYPE);
usage	FUNCTION ( NEW-TYPE argument __parser__(cast=OLD-TYPE) ...)
see also	__parser__(arg-name); __parser__(arg-type)

Example

ORIGINAL native function:

int config_lookup_bool(const config_t *config, const char *path, int *value);

The NATIVE function is transformed into META-CLASS-METHOD:

funcDEF LcConfigLookupBool ME_NI4 {{ME_LCC§N config} {ME_PSN path} {ME_NI4§P value}}

BUT the "int-return", the "arg-2-type" and the "arg-2-name" is not suficient, change:

__parser__global__(LcConfigLookupBool:return-type=LcErrorE);
__parser__global__(LcConfigLookupBool:2:arg-name=value_out);
__parser__global__(LcConfigLookupBool:2:arg-type=MK_BOOL);
__parser__global__(LcConfigLookupBool:value_out:cast=MK_I32);

The final ATTRIBUTE databse of LcConfigLookupBool is:

attributeDEF    LcConfigLookupBool,DEFAULT-ARGS                                    value_out
attributeDEF    LcConfigLookupBool,TYPE-ATTR                                       {value_out P#1}
attributeDEF    LcConfigLookupBool,inline                                          yes
attributeDEF    LcConfigLookupBool,value_out,out                                   yes

The final META-CLASS-METHOD is.

funcDEF         LcConfigLookupBool                                 ME_ENE_MkErrorE                {{ME_CCN_LcConfigC config} {ME_PSN_MK_STRN path} {ME_NB0_MK_BOOL value_out}}

The "C" code META-API generated is:

  mk_inline enum MkErrorE LcConfigLookupBool (LC_CFGN config, MK_STRN path, MK_BOOL *value_out) {
    MK_I32 value_out_val = 0;
    enum LcErrorE errVal = (enum LcErrorE)config_lookup_bool(config->nat, path, &value_out_val);
    *value_out = (MK_BOOL)(value_out_val);
    LcErrorE_Check(config, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Definition at line 204 of file parser_mk.h.

__parser__class

#define __parser__class   class=CLASS

Force to use class as CLASS of the instance-method …

By default the CLASS is choosen from the type of the FIRST argument :

• func(MK_BUF arg,...) -> MkBufferC.

if this does not fit the requirement use class attribute is used to force an other class.

Definition

scope	global or function or enum
usage	__parser__global__(OBJECT:class=CLASS);
usage	__parser__(class=CLASS) OBJECT
see also	__parser__(class-overload)

Example

  __parser__(class=MqContextC,static,hide)
  mk_inline bool MqCtxCheck (MK_MNGN mng) {
    return MkSanitizeCheck(MqContextC,mng);
  }

Definition at line 226 of file parser_mk.h.

__parser__class_overload

#define __parser__class_overload   class-overload

The class-overload does not generate a method-code in the object-Target-Programming-Language (TPL) …

By default a base-class-attribute (instance-method or class-method) is visible by the child-class through class-inheriance but this is a problem for a non-object-Target-Programming-Language (TPL) if ther is already an definition for the method in the child-class.

• Example: The C language always require an explicit method to call even if there is already an base-class-methond because ther is an requirement foan an wrapper to cast the instance-argument into the base-class-instance-argument.

Example

The class MkBufferC has the base-class MkObjectC.

• In a object-Target-Programming-Language (TPL) such as Java, the MkObjectHandleGet and MkBufferHandleGet are the same method.
• In a non-object-Target-Programming-Language (TPL) such as C, the MkBufferHandleGet method is explicitily required.

The class MkBufferC method :

__parser__(class-overload=MkObjectHandleGet)
mk_inline MK_HDL MK_DECL MkBufferHandleGet_RT ( 
  MK_RT_PARSER
  MK_BUF const buf 
) {
  MK_RT_ATTR_HDL_CHECK(buf);
  return MkObjectHandleGet(MkOBJ(buf));  // <- MkOBJ(buf) is the "compile-time-cast" form "MkBufferC" into "MkObjectC"
} MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL

is calling the base-class MkObjectC method :

__parser__(template-required)
MK_EXTERN MK_HDL MK_DECL MkObjectHandleGet_RT ( 
  MK_RT_PARSER
  MK_OBJ const obj 
) MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL;

Problem

The problem is that the method MkBufferHandleGet is not required in the object-Target-Programming-Language (TPL) and the All-Language-Compiler (ALC) should not create code.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:class-overload=yes);
usage	__parser__(class-overload) FUNCTION

Definition at line 272 of file parser_mk.h.

__parser__const

#define __parser__const   const

Add the const prefix in front of the Target-Programming-Language (TPL) public API method …

Definition

scope	global or function
usage	__parser__global__(FUNCTION:const);
usage	__parser__(const) FUNCTION

Example

__parser__(const,flags=new)
MK_EXTERN void MK_DECL MkBufferStreamLog_RT (
  MK_RT_PARSER
  MK_BUS  const bus,
  MK_OBJN       fmtobj    __parser__(default=NULL),
  MK_DBG  const debug     __parser__(default=0),
  MK_STRN const callfunc  __parser__(default=F#FUNC),
  MK_I32  const lvl       __parser__(default=0)
) MK_RT_ATTR_RUNTIME;
 
#define MkBufferStreamLog_5F(bus,fmt,...)   MkBufferStreamLog(bus,MkObj(fmt),__VA_ARGS__)
#define MkBufferStreamLog_2F(bus,fmt)       MkBufferStreamLog_5F(bus,fmt,0,__func__,0)
#define MkBufferStreamLog_3F(bus,fmt,pfx)   MkBufferStreamLog_5F(bus,fmt,0,pfx,0)

C++ code:

      void Log (const MkObjectC* fmtobj = NULL, MK_DBG debug = 0, MK_STRN callfunc = __builtin_FUNCTION(), MK_I32 lvl = 0) const;

Definition at line 287 of file parser_mk.h.

__parser__constructor

#define __parser__constructor   constructor

Mark the function as instance-constructor …

A constructor is defined as a function returning a new instance or MK_NULL if the constructor fails. Special code is added to act on return-NULL to raise an exception.

The constructor is always a method (static or instance) of the return-class-type and is added to the TOR doxygen-documentation-group.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:constructor=yes);
usage	__parser__(constructor) FUNCTION ...
see also	__parser__(null-return-check); __parser__(lng-constr)

Example

__parser__(constructor,lng-constr)
MK_EXTERN MK_BFL MK_DECL MkBufferListCreate_RT (
  MK_RT_PARSER
  MK_NUM const size      __parser__(default=0)
) MK_RT_ATTR_RUNTIME;

Definition at line 306 of file parser_mk.h.

__parser__default

#define __parser__default   default=VALUE

Add a default to a function-argument …

C does not support a default value for a argument but other languages do, like C#. This is a hint to add a default value if the target language support this.

The default can be of different types __parser__(default=TOKEN) :

TOKEN	usage
value	any "value" like 0 or MK_NULL
F#value	function: lookup "value" in the library-definition-table (LONG) and add post-processing code
F#STRING_NULL	function: add null string like ""
F#FUNC	function: the "name" of the current function
F#LINE	function: the "line" of the current function
F#FILE	function: the "file" of the current function
F#CTOR#value	function: use "value" as "constructor" for lookup
F#MK_ERROR	function: the current error-code
S#"value"	string: use "value" with STRING decoration
B#value	boolean: use "value" as true or false
N#value	native: lookup "value" in the library-definition-table (SHORT) without post-processing code

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:default=VALUE);
usage	FUNCTION ( type argument __parser__(default=VALUE) ...)

Example

__parser__(internal)
MK_EXTERN enum MkErrorE MK_DECL MkErrorSetR (
  MK_ERR const          err,
  MK_STRN const         message,
  enum MkErrorE const   errcode     __parser__(default=F#MK_ERROR),
  MK_I32 const          errnum      __parser__(default=-1),
  MK_MNG const          errctx      __parser__(default=NULL)
) MK_HDL_NONNULL_ATTR_1;

Definition at line 348 of file parser_mk.h.

__parser__destructor

#define __parser__destructor   destructor

Mark function as instance destructor …

Definition

scope	global or function
usage	__parser__global__(FUNCTION:destructor=yes);
usage	__parser__(destructor) FUNCTION ...
see also	__parser__(constructor); __parser__(lng-destr); __parser__(keep-destr)

Example

__parser__(destructor)
MK_EXTERN void MK_DECL MkBufferDelete (
  MK_BUF* const bufP
);

Definition at line 366 of file parser_mk.h.

__parser__enum_accept_integer

#define __parser__enum_accept_integer   enum-accept-integer=int32|int64|long

define datatype for enum integer value …

(GO special) The GO programming language allow to define the enum datatype

Definition

scope	global or enum
usage	__parser__global__(ENUM:enum-accept-integer=int32|int64|long);
usage	__parser__(enum-is-flag=int32|int64|long) ENUM ...

Example

• define the enum-type of the enum MkTimeoutE

  __parser__(enum-accept-integer=long)
  enum MkTimeoutE {
    MK_TIMEOUT_INIT       = META_TIMEOUT_REF,
    MK_TIMEOUT_LONG       = (META_TIMEOUT_REF/5),
    MK_TIMEOUT_NORMAL     = (META_TIMEOUT_REF/10  < 1 ? 1 : META_TIMEOUT_REF/10),
    MK_TIMEOUT_SHORT      = (META_TIMEOUT_REF/45  < 1 ? 1 : META_TIMEOUT_REF/45),
    MK_TIMEOUT_SOCKET     = (META_TIMEOUT_REF/90  < 1 ? 1 : META_TIMEOUT_REF/90),
    MK_TIMEOUT_VERYSHORT  = (META_TIMEOUT_REF/180 < 1 ? 1 : META_TIMEOUT_REF/180),
    MK_TIMEOUT_DEFAULT    = -1,
    MK_TIMEOUT_USER       = -2,
    MK_TIMEOUT_MAX        = -3,
  };

Definition at line 381 of file parser_mk.h.

__parser__enum_is_flag

#define __parser__enum_is_flag   enum-is-flag

Add enum-is-flag feature to a enum …

By default, an enum is a list of named-integer-values, BUT if the integer values follow the scheme 2^x (x=0,1,2,…), the enum is a flag-enum. A flag-enum is able to store multiple enum-values in an integer-value using an OR ("|") operator.

A enum-is-flag enum is usually marked with a EF postfix like MyEnumEF.

Definition

scope	global or enum
usage	__parser__global__(ENUM:enum-is-flag=yes);
usage	__parser__(enum-is-flag) ENUM ...

Example

usage of a flag enum

enum FLAG { first = 2^0, second=2^1, third=2^2, … };
enum FLAG myVal = (first|third);

Example

define a flag enum

__parser__(enum-is-flag)
enum LcConfigOptionsEF {
  CONFIG_OPTION_NONE=0x0,
  CONFIG_OPTION_AUTOCONVERT=0x01,
  CONFIG_OPTION_SEMICOLON_SEPARATORS=0x02,
  CONFIG_OPTION_COLON_ASSIGNMENT_FOR_GROUPS=0x04,
  CONFIG_OPTION_COLON_ASSIGNMENT_FOR_NON_GROUPS=0x08,
  CONFIG_OPTION_OPEN_BRACE_ON_SEPARATE_LINE=0x10,
  CONFIG_OPTION_ALLOW_SCIENTIFIC_NOTATION=0x20,
  CONFIG_OPTION_FSYNC=0x40,
  CONFIG_OPTION_ALLOW_OVERRIDES=0x80,
};

Definition at line 420 of file parser_mk.h.

__parser__error_check

#define __parser__error_check   error-check

Verify the enum-return-value of a function using the enum-error-check-code …

The goal is to reuse an already availalable declaration from an external header-file and add the error-check feature from the Programming-Language-Micro-Kernel (PLMK).

The return-value for error-check is an enum and the macro ENUM_Check like LcErrorE_Check is added to verify the enum and jump to the error: label on error.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:error-check=yes);
usage	__parser__(error-check) FUNCTION ...

Example

native function after error-check was added

mk_inline enum MkErrorE LcConfigReadFile (LC_CFG config, MK_STRN filename) {                                            
  LcErrorE_Check(config, config_read_file (config->nat, filename));                                                           
  return MK_OK;                                                                                                               
error:                                                                                                                        
  MkErrorStack_1X(config);                                                                                                     
  return MK_ERROR;                                                                                                            
}   

Definition at line 447 of file parser_mk.h.

__parser__flags

#define __parser__flags   flags=FLAGS

Add flags in front of the target-programming-language public API method …

Some target-programming-languages like C# supprt an additional flag. With the flags feature an additional flag can be added. Supported flags are virtual and new.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:flags=FLAG?@FLAG?…);
usage	__parser__(flags=FLAG) FUNCTION ...

Example

__parser__(class=MqFactoryC,flags=virtual)
MQ_EXTERN enum MkErrorE MK_DECL MqFactoryNew (
  MQ_FCT  const fct,
  MQ_CTX  const tmpl    __parser__(internal,default=NULL),
  MQ_CTX* const val_out
);

Definition at line 469 of file parser_mk.h.

__parser__global__hide_rx

#define __parser__global__hide_rx   hide-rx@LIST=REGEXP

Hide all functions found by REGEXP …

Definition

usage	__parser__global__(hide=REGEXP);
example	__parser__global__(hide-rx=^MkSys);
see also	__parser__(hide); __parser__(keep)

Definition at line 528 of file parser_mk.h.

__parser__has_reference

#define __parser__has_reference   has-reference

Force a reference-type overload to be defined by the PLMK (Programming-Language-Micro-Kernel)-Compiler …

In C++ by DEFAULT only an class-instance-argument get an extra reference-type overload but with the has-reference feature every other-type could get an reference-type overload also.

Definition

scope	argument
usage	__parser__global__(FUNCTION:ARGEMEBT:has-reference=yes);
usage	FUNCTION ( type argument __parser__(has-reference) ... )

Example

MK_EXTERN MK_ERR MK_DECL MkErrorCatch (
  MK_ERR const  err,
  MK_EXP const  exception  __parser__(default=NULL,has-reference),
  MK_STRN const  callfunc   __parser__(default=F#FUNC)
) MK_HDL_NONNULL_ATTR_1;

Definition at line 490 of file parser_mk.h.

__parser__hide

#define __parser__hide   hide=BOOL|NAME

hide a function from the public-api …

There are functions that are only useful for a specific language like TCL or for a specific purpose like "debugging" or "testing". These functions should NOT be public by default and only on request.

• In the All-Language-Compiler (ALC) the function p_KeepAdd is used to unhide a hidden function.

If hide is combinded with a name argument instead of yes than the hidden-function is renamed to name.

• The goal is to later add a hand-written-function function with the original-name.

Definition

scope	global or function or toplevel
usage	__parser__global__(FUNCTION:hide?=yes|name?);
usage	__parser__global__(hide=PATTERN);
usage	__parser__(hide?=yes|name?) FUNCTION ...
see also	__parser__(keep); __parser__(ignore)

Example

__parser__(hide,template-required)
MK_EXTERN void MK_DECL MqMain (
  void * code
);

Definition at line 519 of file parser_mk.h.

__parser__ignore

#define __parser__ignore   ignore

Mark OBJECT to be ignore - not used in public-api …

There are two levels of hiding :

• hide - The OBJECT will be available in the meta-code-library-definition-file (META-FILE) and still be useable in the public-api using the keep feature
• ignore - The OBJECT will not be available in the meta-code-library-definition-file (META-FILE) and not be useable in the public-api

Definition

scope	object
usage	__parser__(ignore) OBJECT ...
see also	__parser__(keep); __parser__(hide)

Example

__parser__(ignore)
typedef struct {
  MK_NUM  size;
  MK_STRN  *data;
} MK_STRN_A;

Definition at line 552 of file parser_mk.h.

__parser__ignore_error

#define __parser__ignore_error   ignore-error=BOOL|NUMBER|2

Ignore the MkErrorE error-indicator …

By default, if a return-value is an error-enum like MkErrorE than an exception will be raised if the MkErrorE signal an error like MK_ERROR.
Sometimes this is not desired because the MkErrorE should be reported for debugging etc.

• The ignore-error=2 has special meaning.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:ignore-error=yes);
usage	__parser__(ignore-error) FUNCTION ...
see also	__parser__(error-check)

Example

__parser__(ignore-error,inline=MkErrorGetCodeI)
MK_EXTERN enum MkErrorE MK_DECL MkErrorGetCode (
  MK_ERR const err
) MK_HDL_NONNULL_ATTR_1;

Definition at line 576 of file parser_mk.h.

__parser__in

#define __parser__in   in

The attribute (in|out|inout) marks an argument as input, output, or both …

in is the default value for every argument, but for special purposes in can be set explicitly.

• This is used e.g. in __parser__push__ / __parser__pop__ etc.

As a special extension, the attributes in, out and inout can also be used as argument name expansion.

• same: FUNCTION( type ARGUMENT __parser__(out), ...)
• same: FUNCTION( type ARGUMENT_out, ...)

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:in|out|inout?=yes?);
usage	FUNCTION(type ARGUMENT __parser__(in|out|inout), ...)
usage	FUNCTION(type ARGUMENT_in|out|inout, ...)
see also	__parser__(in) __parser__(out) __parser__(inout)

example

MK_EXTERN enum MkErrorE MK_DECL MkBufferGetSTR_RT (
  MK_RT_PARSER
  MK_BUFN const buf,
  MK_STRN * const val_out
) MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL MK_RT_ATTR_NONNULL_2;

Definition at line 599 of file parser_mk.h.

__parser__inline

#define __parser__inline   inline=INLINE

add inline function as alternativ function …

By default the function declared is used by the target-programming-language but it is more efficiant to use a inline function if also available.

There is a good reason to provide a inline and a not-inline version of a function because :

1. A inline function is more efficiant than a real function.
2. The Target-Programming-Language (TPL) (like "C#") does not support the use of an inline function and requires a real function.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:inline=INLINE);
usage	__parser__(inline=INLINE) FUNCTION ...

Example

// "H" file
 
// get the MkRuntimeS::isSilent value
__parser__(static,inline=MkRuntimeGetIsSilent)
MK_EXTERN bool MK_DECL MkRuntimeGetIsSilentP ( void ) ;
 
mk_inline bool MkRuntimeGetIsSilent ( void ) {
  return MkRuntimeRLS.isSilent;
}
 
// "C" file
 
bool MkRuntimeGetIsSilentP ( void ) {
  return MkRuntimeGetIsSilent();
}

Definition at line 642 of file parser_mk.h.

__parser__inout

#define __parser__inout   inout

The attribute (in|out|inout) marks an argument as input, output, or both …

in is the default value for every argument, but for special purposes in can be set explicitly.

• This is used e.g. in __parser__push__ / __parser__pop__ etc.

As a special extension, the attributes in, out and inout can also be used as argument name expansion.

• same: FUNCTION( type ARGUMENT __parser__(out), ...)
• same: FUNCTION( type ARGUMENT_out, ...)

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:in|out|inout?=yes?);
usage	FUNCTION(type ARGUMENT __parser__(in|out|inout), ...)
usage	FUNCTION(type ARGUMENT_in|out|inout, ...)
see also	__parser__(in) __parser__(out) __parser__(inout)

example

MK_EXTERN enum MkErrorE MK_DECL MkBufferGetSTR_RT (
  MK_RT_PARSER
  MK_BUFN const buf,
  MK_STRN * const val_out
) MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL MK_RT_ATTR_NONNULL_2;

Definition at line 605 of file parser_mk.h.

__parser__internal

#define __parser__internal   internal

make function, function-argument, type, variable invisible to the public API …

The internal attribute is required to signal the internal-only usage.

There are 3 levels on "hiding" :

attribute	public API	meta-code	tool-usage
ignore	no	no	no
internal	no	yes	yes
hide	no(yes)	yes	yes

The internal attribute is added to the meta-code-library-definition-file (META-FILE) to give a tool the ability to act on this attribute.

Note

The internal-function-argument require the __parser__default attribute because the internal-function-argument can not be set by the library-user.

Definition

scope	global or function or argument
usage	__parser__global__(FUNCTION:internal=yes);
usage	__parser__(internal) FUNCTION ...
usage	FUNCTION ( type argument __parser__(internal) ...)
see also	hide; ignore; keep; __parser__default

Example

Set the internal attribute to a TYPE, a FUNTION and a FUNCTION-ARGUMENT:

__parser__(internal)
typedef struct MkRtExtS * MK_RTEXT;
...
__parser__(internal)
MK_EXTERN void MK_DECL MkSetup (void) __attribute__ ((constructor(200)));
...
__parser__(constructor,lng-constr)
MK_EXTERN MK_BUF MK_DECL MkBufferCreate (
  MK_TYP        type    __parser__(internal,default=NULL),
  MK_NUM  const size    __parser__(default=0)
);

Definition at line 688 of file parser_mk.h.

__parser__keep

#define __parser__keep   keep

keep the function if the default-behaviour is to hide the function …

To hide a block of functions the feature __parser__global__(hide=REGEXP) is used. If you want a single-function to be visible again, use the keep feature.

The keep feature is often used to reveal a hidden function used for testing purposes.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:keep=yes);
usage	__parser__(keep) FUNCTION ...
see also	__parser__(hide); __parser__(ignore); __parser__(internal)

Example

unhide a hidden function

// hide all functions start with "MkSys"
__parser__global__(hide-rx=^MkSys);
....
// make "MkSysKill" visible but without documentation entry
__parser__(keep,doc-no)
MK_EXTERN enum MkErrorE MK_DECL MkSysKill (
  MK_OBJ const fmtobj,
  MK_I32 pid,
  MK_I32 signal
);

Definition at line 721 of file parser_mk.h.

__parser__keep_destr

#define __parser__keep_destr   keep-destr

Do not replace the keep-destr destructor with the lng-destr default-destructor …

If the lng-destr feature is used …

‍enabled with ATTRIBUTE(LNG_DESTR) in the PLMK (Programming-Language-Micro-Kernel)-Compiler language definition

all destructors will be replaced by the default-destructor marked with with lng-destr. The default-destructor is used for the default target-language-destructor like "destroy" in TCL. BUT if your OWN special-destructor should be supported as well, you can mark your OWN destructor with keep-destr, this destructor will always be available.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:keep-destr=yes);
usage	__parser__(keep-destr) FUNCTION ...
see also	__parser__(lng-destr)

Example

__parser__(destructor,keep-destr)
MK_EXTERN void MK_DECL MkObjectDelete_RT (
  MK_RT_PARSER
  MK_obj obj
);

Definition at line 749 of file parser_mk.h.

__parser__keep_original_type

#define __parser__keep_original_type   keep-original-type

Do not try to map the type of an argument into a Programming-Language-Micro-Kernel (PLMK) type …

By default the parser will try to map any native-type of an argument into a type supported by the Programming-Language-Micro-Kernel (PLMK). Sometimes this is not usefull for internal arguments used for special C purpose.

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:keep-original-type=yes);
usage	FUNCTION ( desired-type argument __parser__(keep-original-type) … )

Example

__parser__(constructor,lng-constr)
mk_inline LC_CFG LcConfigCreate (
  MK_TYP        type    __parser__(internal,default=NULL),
  config_t      *nat    __parser__(internal,keep-original-type,default=NULL)
) {
  LcRtSetup_NULL;
  if (type == NULL) type = LcConfigC_TT;
  type = MkTypeResolve(MK_RT_CALL type);
  return (LC_CFG)MkObjCreate(type,nat,NULL);
}

Definition at line 775 of file parser_mk.h.

__parser__library

#define __parser__library   library=NAME@TYPE@NAMESPACE

Define the new library name, namespace and usage …

A library is a collection of CLASSES and METHODS. The library is used to define the name and the namespace of the library.

For a native-library the Programming-Language-Micro-Kernel (PLMK) is added with an extra pre-processing step (example: libconfig).

Definition

scope	toplevel - start of file
usage	__parser__(library=NAME@native|internal@NAME-SPACE);
internal	The library is already using the Programming-Language-Micro-Kernel (PLMK)
native	The library is not using the Programming-Language-Micro-Kernel (PLMK)

Definition at line 790 of file parser_mk.h.

__parser__lng_constr

#define __parser__lng_constr   lng-constr

Define a constructor as the default-constructor …

Every CLASS has ONE or MORE constructors - if MORE constructors are available define ONE of these MORE constructors to be the default-constructor.

The default-constructor will be used as the default in the Target-Programming-Language (TPL).

Definition

scope	global or function
usage	__parser__global__(FUNCTION:lng-constr=yes);
usage	__parser__(lng-constr) FUNCTION ...
see also	__parser__(constructor); __parser__(null-return-check)

Example

__parser__(constructor,lng-constr)
MK_EXTERN MK_BUF MK_DECL MkBufferCreate (
  MK_TYP        type    __parser__(internal,default=NULL),
  MK_NUM  const size    __parser__(default=0)
);

Definition at line 814 of file parser_mk.h.

__parser__lng_destr

#define __parser__lng_destr   lng-destr

Replace all destructors with the lng-destr default-destructor …

If the lng-destr feature is used …

‍enabled with ATTRIBUTE(LNG_DESTR) in the PLMK (Programming-Language-Micro-Kernel)-Compiler language definition

All destructors will be replaced by the default-destructor marked with with lng-destr. The default-destructor is used for the default target-language-destructor like "destroy" in TCL.

Every CLASS has ONE destructor - but in a class-hierarchie only ONE destructor (from MkObjectC) is required to delete all instances from all CLASSes.

The lng-destr also the destructor ised for MkTypeS::destructor .

Definition

scope	global or function
usage	__parser__global__(FUNCTION:lng-destr=yes);
usage	__parser__(lng-destr) FUNCTION ...
see also	__parser__(keep-destr)

Example

__parser__(destructor,lng-destr,lng-dispose,alias=MkObjectDispose)
MK_EXTERN void MK_DECL MkObjectDispose_M (
  MK_MNG *objPtr
);

Definition at line 844 of file parser_mk.h.

__parser__lng_dispose

#define __parser__lng_dispose   lng-dispose

Mark a function to be the default-dispose function …

The dispose untie the connection between the target-languange-instance (LNG) and the PLMK (Programming-Language-Micro-Kernel)-instance (PLMK). Untie means that the LNG-instance is still active, but the PLMK (Programming-Language-Micro-Kernel)-instance's refCount is decremented and the PLMK (Programming-Language-Micro-Kernel)-instance is likely to be destroyed.

Every subsequent access to the LNG-instance leads to a secure and catch-able PLMK (Programming-Language-Micro-Kernel)-NULL-pointer-exception.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:lng-dispose=yes);
usage	__parser__(lng-dispose) FUNCTION ...
see also	__parser__(lng-destr)
read more	ObjectDispose

Example

__parser__(destructor,lng-destr,lng-dispose,alias=MkObjectDispose)
MK_EXTERN void MK_DECL MkObjectDispose_M (
  MK_MNG *objPtr
);

Definition at line 869 of file parser_mk.h.

__parser__macro

#define __parser__macro   macro

Define that a declaration belongs to a macro …

A macro is only visible to the "C" language, for a "non-C" language this is the same as internal. A macro will be added to the meta-code-library-definition-file (META-FILE) but with the macro attribute set, later the macro will be part of the public-api like a normal inline or function.

A macro hase a declaration like a normal funtion but no definition.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:macro=yes);
usage	__parser__(macro) FUNCTION ...
see also	__parser__(internal)

Example

declare and define a macro for public-api usage

__parser__(constructor,macro)
void MkBufferCreateTLS_T(MK_MACRO_TYP cls, MK_MACRO_TYP name, MK_NUM const size);
 
#define MkBufferCreateTLS_T(cls,name,size)          
  static MkThreadLocal struct cls name##R = {0};   
  MK_BUF name = MkBUF(&name##R);                  
  if (unlikely(!__MkCheckX(cls,&name##R))) {     
    MkBufferInit(name,cls##TT,size);         
    MkRefIncr_1X(name);                          
  } else if (MkBUF_R(&name##R).var.cursize) { 
    MkBufferReset(name);                       
  }

Definition at line 902 of file parser_mk.h.

__parser__no_alias

#define __parser__no_alias   no-alias

Delete the alias attribute for function …

Sometimes an alias is created automatically by the PLMK (Programming-Language-Micro-Kernel)-Compiler, this happens when a native-library-header is sourced and the PLMK (Programming-Language-Micro-Kernel)-Compiler generate a PLMK (Programming-Language-Micro-Kernel)-Compiler-C-Wrapper for the native-library.

• example: my_special_name → new: MySpecialName with alias=my_special_name

If the default behaviour is not desired because the target-function already has a definition, the alias attribute will overwrite the alread available definition → the no-alias feature will delete the alias attribute.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:no-alias=yes);
usage	__parser__(no-alias) FUNCTION ...
see also	__parser__(alias)

Example

delete the alias attribute from function

// native C header
... tbd
 
// wrapper C header
... tbd
 
// wrapper C source
... tbd

Definition at line 935 of file parser_mk.h.

__parser__no_inline

#define __parser__no_inline   no-inline

Do not make this function inline …

Attention

experimental

Definition at line 940 of file parser_mk.h.

__parser__no_rpc

#define __parser__no_rpc   no-rpc

Do not create a rpc-call for this function …

By default the PLMK (Programming-Language-Micro-Kernel)-Rpc-Compiler create an rpc-call for every public function. If a function is publib but not useable by rpy use this attribute.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:no-rpc=yes);
usage	__parser__(no-rpc) FUNCTION ...

Definition at line 968 of file parser_mk.h.

__parser__no_size

#define __parser__no_size   no-size

Hide the size information from the binary-object …

By default a binary-object is defined by a binaray-data-pointer and a binary-data-size. If the size is already encoded into the binaray-data-pointer the binary-data-size information is not needed. The no-size attribute will disable the generation of code required to use the binary-data-size information.

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:no-size=yes);
usage	FUNCTION ( type argument __parser__(no-size) ... )

Example

Mark the argument data with the no-size attribute

__parser__(constructor)
MQ_EXTERN MQ_DMP MK_DECL MqDumpBinSet (
  MK_BINN  data    __parser__(no-size)
) MK_HDL_NONNULL_ATTR_1;

Definition at line 1068 of file parser_mk.h.

__parser__no_static

#define __parser__no_static   no-static

Do not add the static attibute to the TPL-wrapper. …

The PLMK (Programming-Language-Micro-Kernel)-Compiler create the entire library as TPL-wrapper. A function-definition is by default static in the wrappe-code-file. If the function-definition need access by hand-written code from other source-files the no-static attribute is used to delete the static attribute from source-code.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:no-static=yes);
usage	__parser__(no-static) FUNCTION ...

Example

Create wrapper without static prefix

// header file
__parser__(no-static)
MK_EXTERN enum MkErrorE MK_DECL MkBufferGetBFL (
  MK_BUF const buf,
  MK_BFL * val_inout
) MK_HDL_NONNULL_ATTR_1;
 
// TCL wrapper source file
// attention - missing "static" in front of "OT_ProcRet"
OT_ProcRet NS(MkBufferC_GetBFL) (MkBufferC_ARGS) {
  OT_SETUP_hdl
  OT_SETUP_VARARGS(0,1,GetL_doc)
  MkBufferListCreateTLS_T(val_inout,10);
  OT_CHECK_OPTIONAL(OT_CHECK_BFL (val_inout))
  OT_CHECK_NOARGS
  MkErrorC_Check(hdl,MkBufferGetBFL (hdl, &val_inout));
  OT_retObj_SET_BFL(val_inout)
  goto end;
  error:
  OT_retObj_SET_Error
  end:
  OT_retObj_RETURN
}

Definition at line 1010 of file parser_mk.h.

__parser__no_type_extension

#define __parser__no_type_extension   no-type-extension

Disable the type-extension feature from function …

The type-extension is a special PLMK (Programming-Language-Micro-Kernel)-feature to simulate a OVERLOAD in the "C"-API.

• the no-type-extension is an attribute to disable the type-extension feature

A group-of-functions which only differ in the type are put together as a type-extension-group. The type-extension-function is identified by the last caracter in the function-name.

Example: To read data from a data-package the "C" funtion MqReadTT is used with TT=type-extension.

The following type-extensions are supported:

‍C=string,O=bool,Y=byte,S=short,I=int,W=longint,F=float,D=double,B=bin,L=list,U=buffer

The type-extension is always used in the doxygen documentation and partly used to create overload functions in the Target-Programming-Language (TPL).

Definition

scope	global or function
usage	__parser__global__(FUNCTION:no-type-extension=yes);
usage	__parser__(no-type-extension) FUNCTION ...

Example

Create wrapper without static prefix

__parser__(no-type-extension)
MK_EXTERN MK_BUF MK_DECL MkBufferListIndexGetBUF (
  MK_BFL const bfl,
  MK_NUM       index
) MK_HDL_NONNULL_ATTR_1;

Definition at line 1045 of file parser_mk.h.

__parser__null_allow

#define __parser__null_allow   null-allow

Allow a function-argument of type class to be a MK_NULL (None) value …

Usually an error is raised if a function-argument of type class has a MK_NULL value instead of an instance. A MK_NULL will be a valid argument if null-allow is set

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:null-allow=yes);
usage	FUNCTION ( type argument __parser__(null-allow) ... )
see also	__parser__(null-return-check); __parser__(null-return-allow)

Definition at line 1081 of file parser_mk.h.

__parser__null_return_allow

#define __parser__null_return_allow   null-return-allow

Allow the function to return a MK_NULL (None) value …

Usually an error is raised if an function returning a MK_NULL instead of an instance. A MK_NULL will be a valid return-possibility if null-return-allow is set

• The null-return-allow add extra code to check on C-NULL and set the target-language NULL value.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:null-return-allow=yes);
usage	__parser__(null-return-allow) FUNCTION ...
see also	__parser__(null-return-check); __parser__(null-allow)

Definition at line 1097 of file parser_mk.h.

__parser__null_return_check

#define __parser__null_return_check   null-return-check

Mark the function as pseudo-instance-constructor …

An constructor is defined as a function returning a new instance or MK_NULL if the constructor fails. Special code is added to act on return-NULL to raise an exception. A pseudo-constructor is a function which act like a class-method but return a NEW instance of an other-class or MK_NULL.

• The null-return-check add extra code to check on MK_NULL and raise an exception.

In difference to the constructor the pseudo-constructor belongs to an other class as the return-type indicates.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:null-return-check=yes);
usage	__parser__(null-return-check) FUNCTION ...
see also	__parser__(constructor); __parser__(lng-constr); __parser__(null-return-allow); __parser__(null-allow)

Definition at line 1126 of file parser_mk.h.

__parser__out

#define __parser__out   out

The attribute (in|out|inout) marks an argument as input, output, or both …

in is the default value for every argument, but for special purposes in can be set explicitly.

• This is used e.g. in __parser__push__ / __parser__pop__ etc.

As a special extension, the attributes in, out and inout can also be used as argument name expansion.

• same: FUNCTION( type ARGUMENT __parser__(out), ...)
• same: FUNCTION( type ARGUMENT_out, ...)

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:in|out|inout?=yes?);
usage	FUNCTION(type ARGUMENT __parser__(in|out|inout), ...)
usage	FUNCTION(type ARGUMENT_in|out|inout, ...)
see also	__parser__(in) __parser__(out) __parser__(inout)

example

MK_EXTERN enum MkErrorE MK_DECL MkBufferGetSTR_RT (
  MK_RT_PARSER
  MK_BUFN const buf,
  MK_STRN * const val_out
) MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL MK_RT_ATTR_NONNULL_2;

Definition at line 602 of file parser_mk.h.

__parser__overload

#define __parser__overload   overload=OVERLOAD

Add an additional overload function to the original-function in the Target-Programming-Language (TPL) …

A overload function has the identical body but an other name, the overload attribute.

The overload feature is not available in all Target-Programming-Language (TPL).

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:overload=OVERLOAD);
usage	__parser__(overload:OVERLOAD) FUNCTION ...

Example

Add the overload function

__parser__(no-type-extension,overload=MqConfigSetIoTcp)
MQ_EXTERN enum MkErrorE
MK_DECL MqConfigSetIoTcpL (
  MQ_CTX const  ctx,
  MK_BFL const  vals
) MK_HDL_NONNULL_ATTR_1;

Definition at line 1150 of file parser_mk.h.

__parser__overload_c_no

#define __parser__overload_c_no   overload-c-no

do not create the overload for function in C …

The overload is a wrapper and id used to support the default-argument and other things.
TODO → link to overload docu

The overload-c-no feature is only usefull in C.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:overload-c-no=yes);
usage	__parser__(overload-c-no) FUNCTION ...

define myFuc_2 as overload for myFunc to support def3 default argument.

#define myFuc_2(arg1,arg2) myFunc(arg1,arg2,def3)

Definition at line 1170 of file parser_mk.h.

__parser__prefix

#define __parser__prefix   prefix=PREFIX

Force prefix to be prefix …

Deprecated

The prefix was step by step replaced by doc-group doc-index and a better PLMK (Programming-Language-Micro-Kernel)-Compiler

By default the prefix is derived from the method-name like MkBufferName -> MkBuffer or from an existing class name. If this is NOT practical or just wrong use prefix attribute to define the prefix. The prefix was importand to select the doxygen-documentation-group but was replaced by the doc-group and doc-index feature. In addition the prefix is still importand to select the class if the function is not an instance-method and not a CTOR/DTOR. The combination of "class" and "prefix" define the documentation-target.

Example

select prefix for method MqLogFactoryE

• Without prefix definition the prefix will be set to MkLog and the method will be finally located into the package-namespace using the Log documentation-target because no MqLogC class is available. The package-namespace is the default-namespace for all methods that cannot be associated with a class.
• With prefix=MqFactory the method becomes a static-method of class MqFactoryC documented in documentation-target Misc by default.

Attention

The prefix is used to overwrite the pattern2prefix global attribute or to correct a wrong prefix-detection.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:prefix=PREFIX);
usage	__parser__(prefix=PREFIX) FUNCTION ...
see also	__parser__(doc-group); __parser__(doc-index)

Definition at line 1211 of file parser_mk.h.

__parser__reference

#define __parser__reference   reference

Mark an object as reference …

A reference is typically applied to a struct to define that this struct is used by default as a reference and not as a pointer.

Definition

scope	global or function
usage	__parser__global__(OBJECT:reference?=yes?);
usage	__parser__(reference?=yes?) OBJECT ...

Example

string data default format:

__parser__(reference)
typedef struct {
  MK_NUM  len;   
  MK_STRN ptr;   
} MkStringR;

Definition at line 1227 of file parser_mk.h.

__parser__return_type

#define __parser__return_type   return-type=TYPE

Replace an already defined return-type …

The goal is to reuse an already availalable declaration from an external-header-file and
change the return-type of a function to support an additional feature.

Attention

The return-type does not do any further analyse - only a HARD cast is done. Both types, the source-type and the target-type HAVE to be "C" compatible.

The following midications are possible;

1. Replace an int (flag) return-type with an enum or bool return-type.
2. Switch the return-type to an error-indicator.

If the return-type is an error-return-enum and the error-check or error-return-enum is set than the c_Native.tcl will check and map the error-return-enum into an MkEnumE.

Also usefull if native code is parsed and global is used to modify the parse output.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:return-type=TYPE);
usage	__parser__(return-type=TYPE) FUNCTION ...
see also	__parser__global__(return-type-default); __parser__(return-type-default-no)

Example

switch return-type

// change "int" return to "LcErrorE" error-indicator (default: int)
__parser__global__(LcConfigLookupInt64:return-type=LcErrorE);
 
// change "int" return to "boolean" (default: int)
__parser__global__(LcConfigGetOption:return-type=bool);

Definition at line 1262 of file parser_mk.h.

__parser__return_type_default_no

#define __parser__return_type_default_no   return-type-default-no

Undo the return-type-default for a specific function…

Definition

scope	global or function
usage	__parser__global__(FUNCTION:return-type-default-no=yes);
usage	__parser__(return-type-default-no) FUNCTION ...
see also	__parser__(return-type); __parser__global__(return-type-default)

Definition at line 1305 of file parser_mk.h.

__parser__runtime

#define __parser__runtime   runtime=FUNC-NAME

Add a public API function FUNC-NAME for a runtime-aware function…

The runtime is the global Programming-Language-Micro-Kernel (PLMK) storage defined as thread-local or static struct and is important for type and storage mangement.

‍if TREAD is enabled and for speed reason the first argument in a runtime-aware function provide the pointer to the runtime called mkrt ...

A function who start with MK_RT_PARSER or MK_RT_ARGS as first argument is called runtime-aware.

The runtime is only used internal and the public-api is using a macro-function starting with MK_RT_CALL to provide the runtime to the internal-api.

The argument FUNC-NAME is the public-api name of the function.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:runtime=FUNC-NAME);
usage	__parser__(runtime=FUNC-NAME) FUNCTION ...

Note

The namespece is choosen according to the namespace of the original function, possible values are MK_, MQ_, LC_, ...

Example

__parser__(constructor)
MK_EXTERN MK_BUS MK_DECL MkBufferStreamCreate64_RT (
  MK_RT_PARSER
  MK_NUM  const size    __parser__(default=0)
) MK_RT_ATTR_RUNTIME;

will create an entry in the additional header file kernel_runtime_rt.h :

#define MkBufferStreamCreate64(...) MkBufferStreamCreate64_RT(MK_RT_CALL __VA_ARGS__)

Definition at line 1344 of file parser_mk.h.

__parser__static

#define __parser__static   static

Force a function to be a class-methode even if PLMK (Programming-Language-Micro-Kernel)-Compiler would chose an instance-method …

By default the FIRST argument of a function is checked to be a class-type or not. If a class-type is found the function will be a instance-function of the class. If this is not desired, use the static attribute to force an class-method,

Definition

scope	global or function
usage	__parser__global__(FUNCTION:static=yes);
usage	__parser__(static) FUNCTION ...
see also	__parser__(argument); __parser__(class);

Example

first argument is class-type but this is a constructor with an other class args as initializer, add static attribute

__parser__(constructor,static)
MK_EXTERN MK_BFL MK_DECL MkBufferListCreateLA (
  MK_BAC const args
) ;

Definition at line 1367 of file parser_mk.h.

__parser__template_in_c

#define __parser__template_in_c   template-in-c

The template is written in the C language and not in the Target-Programming-Language (TPL) language …

A template is written “by hand” and in a programming language with an API that is defined as a combination of lang-code and c-code (like Java), the question arises as to which language the template language should be.

By default, this attribute only makes sense in combination with __parser__template_overload.

This option overrides the default value, which is template-written-in-TPL-language.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:template-in-c=yes);
usage	__parser__(template-in-c) FUNCTION ...
see also	__parser__(template-required)

Example

__parser__(template-overload,template-in-c)
MK_EXTERN MK_STRN MK_DECL MkObjectToNameOfClass_RT (
  MK_RT_PARSER
  MK_OBJ const obj
) MK_RT_ATTR_RUNTIME MK_RT_ATTR_HDL;

Definition at line 1441 of file parser_mk.h.

__parser__template_overload

#define __parser__template_overload   template-overload

Assume a predefined template to implement the function …

By default the PLMK (Programming-Language-Micro-Kernel)-Compiler generate the declaration and the definition of a function. Sometimes a function is beyond the capability of the compiler itself.

This special function require additional support by the programmer. Usually the PLMK (Programming-Language-Micro-Kernel)-Compiler add the definition of the function to the source-code and the programmer add a #define macro to update the definition.

The difference between template-required and template-overload is the template-required will not implement the definition and template-overload does.

Example from MkObjectC_tcl.c The class is implemented in the target language and therefore the exact name of the class cannot be determined in the Programming-Language-Micro-Kernel (PLMK) but is passed to the implementation in the target language using template-overload.

// overwrite "libmkkernel→MkObjectToNameOfClass_O" with "own" implementation
#define MkObjectToNameOfClass_O(hdl)  OT_LNG_OBJ_CLASSNAME(OBJ2VAL_O(hdl))
...
static OT_ProcRet NS(MkObjectC_ToNameOfClass) (MkObjectC_ARGS) {
  OT_SETUP_hdl
  OT_SETUP_NOARG(ToNameOfClass_doc)
  OT_CHECK_NOARGS
  OT_retObj_SET_STR(MkObjectToNameOfClass (hdl))
  goto end;
  error:
  OT_retObj_SET_Error
  end:
  OT_retObj_RETURN
}

Definition

scope	global or function
usage	__parser__global__(FUNCTION:template-overload=yes);
usage	__parser__(template-overload) FUNCTION ...
see also	__parser__(template-required)

Example

__parser__(alias=MkObjectToNameOfClass,template-overload)
MK_EXTERN MK_STRN MK_DECL MkObjectToNameOfClass_O (
  MK_OBJ const obj
) MK_HDL_NONNULL_ATTR_1;

Definition at line 1415 of file parser_mk.h.

__parser__template_required

#define __parser__template_required   template-required

Require a predefined template to implement the function …

By default the PLMK (Programming-Language-Micro-Kernel)-Compiler generate the declaration and the definition of a function. Sometimes a function is beyond the capability of the compiler itself. This special function have to be implemented as code-template by hand.

• With template-required the PLMK (Programming-Language-Micro-Kernel)-Compiler will not try to generate the definition of the function.

A template is loaded from the [INCLUDE_PATH/tmpl] directory OR, if present, from the source code itself.

The difference between template-required and template-overload is the template-required will not implement the definition and template-overload does.

Definition

scope	global or function
usage	__parser__global__(FUNCTION:template-required=yes);
usage	__parser__(template-required) FUNCTION ...
see also	__parser__(template-overload)

Example

__parser__(template-required)
MK_EXTERN enum MkErrorE MK_DECL MkBufferToObject (
  MK_BUF        const buf,
  MK_NAT_OBJECT *     obj_out
) MK_HDL_NONNULL_ATTR_1;

Definition at line 1472 of file parser_mk.h.

__parser__type

#define __parser__type   type=META@DESCRIPTION

Define the meta-type for the public-type …

A meta-type is an internal-type of the PLMK (Programming-Language-Micro-Kernel)-Compiler and is used in the meta-code-library-definition-file (META-FILE) to hide the native-type from PLMK (Programming-Language-Micro-Kernel)-Compiler internals. The meta-type always start with a ME_ prefix and uses min 3 extra characters to unique identify the native-type.

Example

define the meta-type for a 4 byte int data-type

// 4 byte \b integer data-type
__parser__(type=ME_NI4:"4 byte 'integer' data-type")
typedef signed int MK_I32;

At the beginning of meta-code-library-definition-file (META-FILE) is a short listing of the meta-types used.

## type definition :
##
namespace eval meta_writer {
##
##  ME_(PCANRVE)      FIRST: P=pointer, C=class, A=array, N=Native, R=reference, V=vararg, E(NE)=enum
##
##  ME_P*             The "pointer" data type
##  ME_P(VSBLFECA)    V=void, S=string, B=binary, L=list, F=format, E=exception, C=constructor, A=callback
##  ME_P.(BNX)        B=basicType, N=const, X=unrecognized
##
  array set typeDoc {
    ME_PAX_MK_CBP             {MK_CBP          {MK_PTRB *}                               {generic pointer to call-back data}                                     {}               }
    ME_PBB_MK_BINB            {MK_BINB         {unsigned char}                           {byte-array type data-type}                                             {}               }
    ME_PBN_MK_BINN            {MK_BINN         {MK_BINB§M *}                             {const byte-array pointer data-type}                                    {}               }
    ME_PBX_MK_BIN             {MK_BIN          {MK_BINB *}                               {byte-array pointer data-type}                                          {}               }
    ME_PCX_MK_CCP             {MK_CCP          {MK_PTRB *}                               {class constructor/destructor data type}                                {}               }
    ME_PEX_MK_EXP             {MK_EXP          {MK_PTRB§M *}                             {target language exception-class-object}                                {}               }
    ME_PFX_MK_FST             {MK_FST          {MK_STRB§M *}                             {constant 'printf' format string}                                       {}               }
    ME_PLB_MK_LSTB            {MK_LSTB         {unsigned char}                           {list type data-type}                                                   {}               }
    ME_PLX_MK_LST             {MK_LST          {MK_LSTB *}                               {list pointer data-type}                                                {}               }
    ME_PSB_MK_STRB            {MK_STRB         char                                      {string type data-type}                                                 {}               }
    ME_PSN_MK_STRN            {MK_STRN         {MK_STRB§M *}                             {constant string pointer data-type}                                     {}               }
    ME_PSX_MK_STR             {MK_STR          {MK_STRB *}                               {string pointer data-type}                                              {}               }
    ME_PVB_MK_PTRB            {MK_PTRB         void                                      {pointer type data-type}                                                {}               }
    ME_PVN_MK_PTRN            {MK_PTRN         {MK_PTRB§M *}                             {const generic pointer data-type}                                       {}               }
    ME_PVX_MK_NAT_LIST        {MK_NAT_LIST     {void *}                                  {target language list pointer}                                          {}               }
    ME_PVX_MK_NAT_OBJECT      {MK_NAT_OBJECT   {void *}                                  {target language object pointer}                                        {}               }
    ME_PVX_MK_PTR             {MK_PTR          {MK_PTRB *}                               {generic pointer data-type}                                             {}               }
  }
##
##
##  ME_C*             The "class" data type
##  ME_C(CX)          C=class, X=special
##  ME_C.(CN)         C=class, N=const
##
  array set typeDoc {
    ME_CCC_MkBufferC          {MK_BUF          {struct MkBufferS *}                      {MkBufferC class handle}                                                MkBufferS        }
    ME_CCC_MkBufferListC      {MK_BFL          {struct MkBufferListS *}                  {MkBufferListC class handle}                                            MkBufferListS    }
    ME_CCC_MkBufferStreamC    {MK_BUS          {struct MkBufferStreamS *}                {MkBufferStreamC class handle}                                          MkBufferStreamS  }
    ME_CCC_MkErrExtC          {MK_ERREXT       {struct MkErrExtS *}                      {final class for the MkErrorS extention technology}                     MkErrExtS        }
    ME_CCC_MkErrorC           {MK_ERR          {struct MkErrorS *}                       {MqErrorC class handle}                                                 MkErrorS         }
    ME_CCC_MkExtensionC       {MK_EXT          {struct MkExtensionS *}                   {abstract class for the extension technology}                           MkExtensionS     }
    ME_CCC_MkLogFileC         {MK_LFL          {struct MkLogFileS *}                     {MkLogFileC class handle}                                               MkLogFileS       }
    ME_CCC_MkObjectC          {MK_OBJ          {struct MkObjectS *}                      {MkObjectC class handle}                                                MkObjectS        }
    ME_CCC_MkRtExtC           {MK_RTEXT        {struct MkRtExtS *}                       {final class for the MkRuntimeS extention technology}                   MkRtExtS         }
    ME_CCC_MkRuntimeC         {MK_RT           {struct MkRuntimeS *}                     {runtime singleton class object}                                        MkRuntimeS       }
    ME_CCC_MkTypeC            {MK_TYP          {struct MkTypeS *}                        {a managed object class type !base! pointer}                            MkTypeS          }
    ME_CCN_MkBufferC          {MK_BUFN         {struct MkBufferS§M *}                    {const - MkBufferC class handle}                                        MkBufferS        }
    ME_CCN_MkBufferListC      {MK_BFLN         {struct MkBufferListS§M *}                {const - MkBufferListC class handle}                                    MkBufferListS    }
    ME_CCN_MkBufferStreamC    {MK_BUSN         {struct MkBufferStreamS§M *}              {const - MkBufferStreamC class handle}                                  MkBufferStreamS  }
    ME_CCN_MkErrExtC          {MK_ERREXTN      {struct MkErrExtS§M *}                    {const - final class for the MkErrorS extention technology}             MkErrExtS        }
    ME_CCN_MkErrorC           {MK_ERRN         {struct MkErrorS§M *}                     {const - MqErrorC class handle}                                         MkErrorS         }
    ME_CCN_MkExtensionC       {MK_EXTN         {struct MkExtensionS§M *}                 {const - abstract class for the extension technology}                   MkExtensionS     }
    ME_CCN_MkLogFileC         {MK_LFLN         {struct MkLogFileS§M *}                   {const - MkLogFileC class handle}                                       MkLogFileS       }
    ME_CCN_MkObjectC          {MK_OBJN         {struct MkObjectS§M *}                    {const - MkObjectC class handle}                                        MkObjectS        }
    ME_CCN_MkRtExtC           {MK_RTEXTN       {struct MkRtExtS§M *}                     {const - final class for the MkRuntimeS extention technology}           MkRtExtS         }
    ME_CCN_MkRuntimeC         {MK_RTN          {struct MkRuntimeS§M *}                   {const - runtime singleton class object}                                MkRuntimeS       }
    ME_CCN_MkTypeC            {MK_TYPN         {struct MkTypeS§M *}                      {const - a managed object class type !base! pointer}                    MkTypeS          }
    ME_CXC_MK_BAC             {MK_BAC          {struct MkBufferListS *}                  {a list of 'buffer' as last argument in function}                       MkBufferListS    }
    ME_CXC_MK_MNG             {MK_MNG          {MK_PTRB *}                               {managed object pointer; datatype will be checked at runtime}           {}               }
    ME_CXC_MkExceptionC       {MK_MXP          {MK_PTRB *}                               {target language library-exception-class-object}                        {}               }
    ME_CXN_MK_BAC             {MK_BACN         {struct MkBufferListS§M *}                {const - a list of 'buffer' as last argument in function}               MkBufferListS    }
    ME_CXN_MK_MNGN            {MK_MNGN         {MK_PTRB§M *}                             {const - a managed object pointer; datatype will be checked at runtime} {}               }
  }
##
##
##  ME_A*             The "array" data type
##  ME_A(SCX)         S=string, C=class, X=unrecognized
##  ME_A.(NX)         N=const, X=unrecognized
##
  array set typeDoc {
    ME_ASN_MK_STRN_A          {MK_STRN_A       {struct { MK_NUM size ;MK_STRN * data ;}} {ARRAY of MK_STRN}                                                      §code§       }
  }
##
##
##  ME_N*             The "native" data type
##  ME_N(BIF)         B=bool, I=integer, U=Unsigned, F=float
##  ME_N.(#XL)        #=#bytes, X=longlong, L=long
##
  array set typeDoc {
    ME_NB0_MK_BOOL            {MK_BOOL         bool                                      {'boolean' data-type}                                                   {}               }
    ME_NB1_MK_BOL             {MK_BOL          {unsigned char}                           {1 byte 'boolean' data-type}                                            {}               }
    ME_NF4_MK_FLT             {MK_FLT          float                                     {4 byte 'float' data-type}                                              {}               }
    ME_NF8_MK_DBL             {MK_DBL          double                                    {8 byte 'double' data-type}                                             {}               }
    ME_NI1_MK_I8              {MK_I8           char                                      {1 byte 'byte' data-type}                                               {}               }
    ME_NI2_MK_I16             {MK_I16          {short int}                               {2 byte 'short integer' data-type}                                      {}               }
    ME_NI4_MK_DBG             {MK_DBG          int                                       {debug-level data-type}                                                 {}               }
    ME_NI4_MK_I32             {MK_I32          int                                       {4 byte 'integer' data-type}                                            {}               }
    ME_NI4_MK_NUM             {MK_NUM          int32_t                                   {}                                                                      {}               }
    ME_NI8_MK_I64             {MK_I64          {long long}                               {8 byte 'wide integer' data-type}                                       {}               }
    ME_NIH_MK_HDL             {MK_HDL          int32_t                                   {handle data-type}                                                      {}               }
    ME_NIL_MK_LONG            {MK_LONG         long                                      {4/8 byte 'long' data-type}                                             {}               }
    ME_NIL_MK_SIZE            {MK_SIZE         long                                      {long byte 'size' datay-type}                                           {}               }
    ME_NIL_MK_TIME_T          {MK_TIME_T       time_t                                    {time [sec] data-type}                                                  {}               }
    ME_NU1_MK_U8              {MK_U8           {unsigned char}                           {1 byte 'unsigned byte' data-type}                                      {}               }
    ME_NU2_MK_U16             {MK_U16          {unsigned short}                          {2 byte 'unsigned short' data-type}                                     {}               }
    ME_NU4_MK_SIG             {MK_SIG          {unsigned int}                            {}                                                                      {}               }
    ME_NU4_MK_U32             {MK_U32          {unsigned int}                            {4 byte 'unsigned integer' data-type}                                   {}               }
    ME_NU8_MK_U64             {MK_U64          {long unsigned long}                      {8 byte 'unsigned wide' data-type}                                      {}               }
    ME_NUL_MK_ULN             {MK_ULN          {unsigned long}                           {8 byte 'unsigned long' data-type}                                      {}               }
  }
##
##
##  ME_R*             The "reference" data type
##  ME_R(SCU)         S=string, C=class, U=union
##  ME_R.(NA~)        S=string, A=unrecognized, ~=unrecognized
##
  array set typeDoc {
    ME_RCN                    {classR          classR                                    {const - class reference}                                               {}               }
    ME_RSN                    {stringR         stringR                                   {const - string reference}                                              {}               }
    ME_RUA_MkBufferAtomU      {MK_ATO          {union MkBufferAtomU}                     {atomic native data buffer type}                                        MkBufferAtomU    }
  }
##
##
##  ME_V*             The "variable argument list" data type
##  ME_V(ACL)         A=..., C=string, L=va_list
##  ME_V.(NV)         N=const, V=unrecognized
##
  array set typeDoc {
    ME_VAV                    {...             ...                                       {variable argument list 'printf' style}                                 {}               }
    ME_VCV                    {{MK_STRN[]}     {MK_STRN[]}                               {variable argument list 'string-array' style}                           {}               }
    ME_VLV                    {va_list         va_list                                   {variable argument list 'va_list' style}                                {}               }
  }
##
##
## additional modifer definition :
##
##   %S = struct, %U = union, %E = enum, %G = unsigned, %N/M = const, %P = ptr
##
}
  
headerDEF       library                                             {{MkKernel internal Mk}}
headerDEF       header                                              /home/dev1usr/Project/NHI1/theKernel/c/kernel_mk.h
headerDEF       §END§                                               -
 
attributeDEF    KEEP_DTOR                                                          §NO§

Definition

scope	type
usage	__parser__(type=META:DESCRIPTION) TYPE

Definition at line 1498 of file parser_mk.h.

__parser__wrapper

#define __parser__wrapper   wrapper

Add a wrapper to the default value of a function-argument …

By default a __parser__(default=…) value is used as provided but sometimes this is not sufficiant and a wrapper is required in "C" code to add a TPL-Namespace.

The wrapper is defined as "C" macro in the TPL-Header-File and is required if the default value is a function-call in the TPL-Code.

Definition

scope	global or argument
usage	__parser__global__(FUNCTION:ARGUMENT:wrapper=WRAPPER);
usage	FUNCTION ( type argument __parser__(wrapper=WRAPPER) ... )
see also	__parser__(default)

Example

… tbd

Definition at line 1520 of file parser_mk.h.