MkKernel_Parser_Native_C_API

native : define the __parser__ attribute related to native-library integration … More...

Collaboration diagram for MkKernel_Parser_Native_C_API:

Macros
#define	__parser__global__native2class   native2class:EXTERNAL-STRUCT=INTERNAL-CLASS@HANDEL-NAME
	Use native2class to link an external-struct with an internal-class …
#define	__parser__global__native_alias_from_prefix   native-alias-from-prefix:NATIVE-PREFIX=WRAPPER-PREFIX
	Use the native-alias-from-prefix feature to map a native-function to a wrapper-function with PLMK (Programming-Language-Micro-Kernel)-Support …
#define	__parser__global__native_alias_from_hdl   native-alias-from-hdl:OLD-PREFIX=OLD-TYPE@NEW-PREFIX@NEW-HDL
	Use the native-alias-from-hdl feature to map a native-function to a wrapper-function with PLMK (Programming-Language-Micro-Kernel)-Support …
#define	__parser__native_alias   native-alias
	Overwrite the default meta-function-name for a native-function …
#define	__parser__global__native_hide   native-hide=NEW-NAME
	create a hidden wrapper with name NEW-NAME with a public api …
#define	__parser__global__native_ignore_regexp   native-ignore-regexp@LIST=REGEXP
	Ignore all functions found by REGEXP …
#define	__parser__global__native_ignore_name   native-ignore-name@LIST=NAME
	Ignore all functions found by NAME …
#define	__parser__global__native_ignore_type   native-ignore-type@LIST=TYPE
	Ignore all functions found by TYPE …
#define	__parser__global__native_prefer_postfix   native-prefer-postfix@LIST=POSTFIX
	Select a specific native-function identified by POSTFIX …

Detailed Description

native : define the __parser__ attribute related to native-library integration …

Macro Definition Documentation

__parser__global__native2class

#define __parser__global__native2class   native2class:EXTERNAL-STRUCT=INTERNAL-CLASS@HANDEL-NAME

Use native2class to link an external-struct with an internal-class …

This attribute is only used if a native library without PLMK (Programming-Language-Micro-Kernel)-Support is used as input and an external-struct have to be mapped to an internal-class.

Definition

usage	__parser__global__(native2class:EXTERNAL-STRUCT=INTERNAL-CLASS@HANDEL-NAME);
see also	__parser__(class); __parser__global__(native-alias-from-prefix)

Example

Map external-struct config_setting_t to internal-class LbSettingS using handle nat

// native-hide header file
__parser__global__(native2class:config_setting_t=LbSettingS@nat);
 
// native-hide source file
struct LbSettingS {
  // superclass
  union {
    // object header
    struct MkObjectS  obj;        
  } super;
  // object body
  config_setting_t    *nat;
};

Definition at line 2250 of file parser_mk.h.

__parser__global__native_alias_from_hdl

#define __parser__global__native_alias_from_hdl   native-alias-from-hdl:OLD-PREFIX=OLD-TYPE@NEW-PREFIX@NEW-HDL

Use the native-alias-from-hdl feature to map a native-function to a wrapper-function with PLMK (Programming-Language-Micro-Kernel)-Support …

This attribute is only used if a native library without PLMK (Programming-Language-Micro-Kernel)-Support is used as input and a native-function have to be mapped to a wrapper-function.

In the meta-code the WRAPPER-PREFIX together with the NATIVE-POSTFIX is the new wrapper-function and the native-function is added to the native-alias attribute of the new wrapper-function.

In difference to __parser__global__(native-alias-from-prefix) this attribute is used if ther is NO unique prefix to identify a function class and the type of FIRST argument is required also.

Definition

usage	__parser__global__(native-alias-from-hdl:OLD-PREFIX:OLD-TYPE=NEW-PREFIX@NEW-HDL);
see also	__parser__(alias); __parser__global__(native2class); __parser__global__(native-alias-from-prefix)

Note

The processing-order is from longest-prefix to shortest-prefix.

Example

mapping the native sqlite3_aggregate_context function to the wrapper Sq3ContextAggregateContext function.

// native header file (sqlite3.h)
SQLITE_API sqlite3_int64 sqlite3_value_int64(sqlite3_value*);
 
// wrapper header file (sqlite3_sq.h)
__parser__global__(native-alias-from-hdl:sqlite3_value_:sqlite3_value=Sq3Value@sq3val);
__parser__global__(native-alias-from-hdl:sqlite3_:sqlite3_value=Sq3Value@sq3val);
__parser__global__(native2class:sqlite3_value=Sq3ValueS@nat);
 
// meta code file (.liblcconfig.meta)
attributeDEF    Sq3ValueInt64,cast              ME_NI8_MK_I64
attributeDEF    Sq3ValueInt64,class             Sq3ValueC
attributeDEF    Sq3ValueInt64,doc-group         Types
attributeDEF    Sq3ValueInt64,inline            yes
attributeDEF    Sq3ValueInt64,native-alias      sqlite3_value_int64
attributeDEF    Sq3ValueInt64,prefix            Sq3Value
attributeDEF    Sq3ValueInt64,sq3val,native     {nat sqlite3_value §S§P}
...
funcDEF         Sq3ValueInt64  ME_NI8_MK_I64    {{ME_CCC_Sq3ValueC sq3val}}

Definition at line 2331 of file parser_mk.h.

__parser__global__native_alias_from_prefix

#define __parser__global__native_alias_from_prefix   native-alias-from-prefix:NATIVE-PREFIX=WRAPPER-PREFIX

Use the native-alias-from-prefix feature to map a native-function to a wrapper-function with PLMK (Programming-Language-Micro-Kernel)-Support …

This attribute is only used if a native library without PLMK (Programming-Language-Micro-Kernel)-Support is used as input and a native-function have to be mapped to a wrapper-function.

In the meta-code the WRAPPER-PREFIX together with the NATIVE-POSTFIX is the new wrapper-function and the native-function is added to the native-alias-from-prefix attribute of the new wrapper-function.

Note

The processing-order is from longest-prefix to shortest-prefix.

Definition

usage	__parser__global__(native-alias-from-prefix=NATIVE-PREFIX@WRAPPER-PREFIX);
see also	__parser__(alias); __parser__global__(native2class); __parser__global__(native-alias-from-hdl)

Example

mapping the native config_lookup function to the wrapper LcConfigLookup function.

// native header file (libconfig.h)
extern LIBCONFIG_API config_setting_t *config_lookup(const config_t *config, const char *path);
 
// wrapper header file (config_lc.h)
__parser__global__(native-alias-from-prefix:config_=LcConfig);
__parser__global__(native2class:config_t=LcConfigS@nat);
__parser__global__(prefix2doc:LcConfigLookup=Lookup);
__parser__global__(LcConfigLookup:null-return-check=yes);
 
// meta code file (.liblcconfig.meta)
attributeDEF    LcConfigLookup,null-return-check                    yes
attributeDEF    LcConfigLookup,config,native                        {nat config_t}
attributeDEF    LcConfigLookup,native                               {nat config_setting_t}
attributeDEF    LcConfigLookup,native-alias-from-prefix             config_lookup
...
attributeDEF    prefix2doc,LcConfigLookup                           Lookup
...
funcDEF         LcConfigLookup                 ME_LSC               {{ME_LCC§N config} {ME_PSN path}}

Definition at line 2289 of file parser_mk.h.

__parser__global__native_hide

#define __parser__global__native_hide   native-hide=NEW-NAME

create a hidden wrapper with name NEW-NAME with a public api …

Sometimes a native-function is too complicated to be fully defined by the All-Language-Compiler (ALC).

‍A two-step approach is required where the native-function is renamed to NEW-NAME and become the private-function and the programmer write the public-function as wrapper for the private-function.

The NEW-NAME is in native-syntax like sqlite3_prepare_v2_hide for the libsqlite3 function sqlite3_prepare_v2. The metacode-sytax of the both functions are Sq3StmtPrepareV2Hide and Sq3StmtPrepareV2 because the both functions belonging to the class Sq3StmtC.

The ALC create:

1. The public-function-declaration with all arguments not having the ??__parser__native_internal attribute.
2. The private-function-definition with the __parser__(hide) attribute set.

The programmer uses the private-function to create the public-function following the public-function-declaration.
The public-function can now be used to add an additional feature like extra code to work with ??__parser__native_internal arguments.

Example: create the metacode-function from the native-function sqlite3_prepare_v2_hide

The native-function is a constructor for the ppStmt handle defined with:

SQLITE_API int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);

The problem is that the meta-code-contructor is only allowed to return one argument but the function sqlite3_prepare_v2 return two arguments ppStmt and pzTail.
The solution is to use the two-step approach and add the pzTail value to a stor for later usage.

With the global attributes defined in sqlite3_sq3.h :

__parser__global__(sqlite3_prepare_v2:native-hide=sqlite3_prepare_v2_hide)
__parser__global__(sqlite3_prepare_v2:class:Sq3StmtC)
__parser__global__(sqlite3_prepare_v2:lng-constr=yes)
__parser__global__(sqlite3_prepare_v2:constructor=yes)
__parser__global__(sqlite3_prepare_v2:nByte:default:-1)
__parser__global__(sqlite3_prepare_v2:ppStmt:out=yes)
__parser__global__(sqlite3_prepare_v2:ppStmt:hdl=yes)
__parser__global__(sqlite3_prepare_v2:pzTail:out=yes)

the c_native.tcl tool of the All-Language-Compiler (ALC) create the hidden defintion Sq3StmtPrepareV2Hide :

// hidden api (original-metacode-function)
__parser__(hide,constructor,class=Sq3StmtC)
mk_inline enum MkErrorE Sq3StmtPrepareV2Hide (
  SQ3_LITE  db, 
  MK_STRN   zSql, 
  MK_I32    nByte   __parser__(default=-1), 
  SQ3_STMT  *ppStmt __parser__(out), 
  MK_STRN   *pzTail __parser__(out)
) {
  *ppStmt = NULL;
  struct sqlite3 * db_hdl = db->nat;
  sqlite3_stmt* ppStmt_val = NULL;
  enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_prepare_v2(db_hdl, zSql, nByte, &ppStmt_val, pzTail);
  SQ3_STMT ppStmt_hdl = *ppStmt = Sq3StmtC_ObjCreate(ppStmt_val);
  Sq3ErrorE_Check_Ctor(Sq3StmtC_TT,ppStmt_hdl,errVal);
  return MK_OK;
error:
  return MK_ERROR;
}

and the public declaration Sq3StmtPrepareV2 :

// wrapper api header definition (final-metacode-function)
__parser__(lng-constr,constructor,class=Sq3StmtC)
mk_inline enum MkErrorE Sq3StmtPrepareV2 (
  SQ3_LITE  db, 
  MK_STRN   zSql, 
  MK_I32    nByte   __parser__(default=-1), 
  SQ3_STMT  *ppStmt __parser__(out) 
);

Finally the programmer create the public definition Sq3StmtPrepareV2 using the hidden definition Sq3StmtPrepareV2Hide :

mk_inline enum MkErrorE Sq3StmtPrepareV2 (SQ3_LITE db, MK_STRN zSql, MK_I32 nByte, SQ3_STMT *ppStmt) {
  MK_STRN pzTail = NULL;
  MkErrorE_Check(Sq3StmtPrepareV2Hide(db,zSql,nByte,ppStmt,&pzTail));
  ppStmt->pzTail = pzTail; // storage for the 'pzTail' in the new created 'ppStmt'
  return MK_OK;
error:
  return MkErrorStack_1x(db);
}

Definition

usage	__parser__global__(native-hide=NEW-NAME);
example	__parser__global__(native-hide=sqlite3_prepare_v2_hide);

Definition at line 2454 of file parser_mk.h.

__parser__global__native_ignore_name

#define __parser__global__native_ignore_name   native-ignore-name@LIST=NAME

Ignore all functions found by NAME …

The native-function name is compared with \\m\arg{ignore-name}\\M and if true the function is ignored.

For detail description refer to __parser__global__(native-ignore-regexp)

Definition

usage	__parser__global__(native-ignore-name=NAME);
example	__parser__global__(native-ignore-name=sqlite3_preupdate_old);
see also	__parser__(ignore)

Definition at line 2483 of file parser_mk.h.

__parser__global__native_ignore_regexp

#define __parser__global__native_ignore_regexp   native-ignore-regexp@LIST=REGEXP

Ignore all functions found by REGEXP …

The ignore-XXX style of attributes are used to __parser__(ignore) a native-function.

• The __parser__global__(native-ignore-regexp) ignore by regular-expression
• The __parser__global__(native-ignore-name) ignore by name
• The __parser__global__(native-ignore-type) ignore by argument-type oe return-type

Definition

usage	__parser__global__(native-ignore-regexp=REGEXP);
example	__parser__global__(native-ignore-regexp=^MyPrefix);
see also	__parser__(ignore)

Definition at line 2469 of file parser_mk.h.

__parser__global__native_ignore_type

#define __parser__global__native_ignore_type   native-ignore-type@LIST=TYPE

Ignore all functions found by TYPE …

If the native-function argument-type or return-type is the ignore-type than the function is ignored. The ignore-type have to be a type defined by struct TYPE { ... } or by typedef struct { ... } TYPE

For detail description refer to __parser__global__(native-ignore-regexp)

Definition

usage	__parser__global__(ignore-type=TYPE);
example	__parser__global__(ignore-type=sqlite3_module);
see also	__parser__(ignore)

Definition at line 2498 of file parser_mk.h.

__parser__global__native_prefer_postfix

#define __parser__global__native_prefer_postfix   native-prefer-postfix@LIST=POSTFIX

Select a specific native-function identified by POSTFIX …

If the native-api provide multiple function to provide an feature select the function with POSTFIX to be the leading function.

Note

The POSTFIX refer to the meta-function-name with Title notation.

Example: sqlite3

SQLITE_API int sqlite3_prepare_v2(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
SQLITE_API int sqlite3_prepare_v3(
  sqlite3 *db,            /* Database handle */
  const char *zSql,       /* SQL statement, UTF-8 encoded */
  int nByte,              /* Maximum length of zSql in bytes. */
  unsigned int prepFlags, /* Zero or more SQLITE_PREPARE_ flags */
  sqlite3_stmt **ppStmt,  /* OUT: Statement handle */
  const char **pzTail     /* OUT: Pointer to unused portion of zSql */
);
 
__parser__global__(native-prefer-postfix=V2);

Definition

usage	__parser__global__(native-prefer-postfix=POSTFIX);
example	__parser__global__(native-prefer-postfix=V2);

Definition at line 2532 of file parser_mk.h.

__parser__native_alias

#define __parser__native_alias   native-alias

Overwrite the default meta-function-name for a native-function …

By default a meta-function-name is created from native-function using the following rules:

1. The basic syntax is: NsClassAttribute
2. The Ns is the current library Ns like Sq3 for LibSq3Lite.
3. The Class is the rootname of the current class or package like Stmt for Sq3StmtC.
4. The Attribute is the root of the native-function-name. The root is the name without library-prefix like errmsg for sqlite3_errmsg.
5. If #4 contains "_" than the Attribute is split into a list-of-attributes
6. The list-of-attributes is joined together with title-substitution like sqlite3_errmsg to Sq3LiteErrmsg
7. If the name from #6 does not fit the needs than native-alias will provide the name without any further modification done like native-alias=Sq3LiteErrMsg

Definition

scope	global or function
usage	__parser__global__(FUNCTION:native-alias=NEW-NAME);
usage	__parser__(native-alias=NEW-NAME) FUNCTION …
see also	__parser__(alias); __parser__global__(native2class); __parser__global__(native-alias-from-prefix)

Definition at line 2354 of file parser_mk.h.