ZFLuaExecute.h File Reference

execute lua script More...

#include "ZFLuaDef.h"

Go to the source code of this file.

Functions
zfauto	ZFLuaExecute (const ZFInput &input)
	main entry for lua module, execute lua code
zfauto	ZFLuaExecute (const zfchar *buf)
	see ZFLuaExecute
zfauto	ZFLuaExecute (const ZFInput &input, ZFObject *param0, ZFObject *param1=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param2=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param3=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param4=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param5=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param6=(((ZFObject *const &) _ZFP_ZFMP_DEF)))
	see ZFLuaExecute
zfauto	ZFLuaExecute (const zfchar *buf, ZFObject *param0, ZFObject *param1=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param2=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param3=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param4=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param5=(((ZFObject *const &) _ZFP_ZFMP_DEF)), ZFObject *param6=(((ZFObject *const &) _ZFP_ZFMP_DEF)))
	see ZFLuaExecute
zfauto	ZFLuaExecuteDetail (const ZFInput &input, const ZFCoreArray< zfauto > &luaParams, zfbool *success=(zft_zfnull), zfstring *errorHint=(zft_zfnull), void *L=(zft_zfnull))
	see ZFLuaExecute
zfauto	ZFLuaExecuteDetail (const zfchar *buf, const ZFCoreArray< zfauto > &luaParams, zfbool *success=(zft_zfnull), zfstring *errorHint=(zft_zfnull), void *L=(zft_zfnull))
	see ZFLuaExecute

Detailed Description

execute lua script

Function Documentation

ZFLuaExecute()

zfauto ZFLuaExecute ( const ZFInput & input )

extern

main entry for lua module, execute lua code

thanks to powerful reflection mechanism in ZFFramework, most of components are registered to lua by reflection automatically

all types of ZFFramework are wrapped as zfauto in lua world, including: ZFObject types (wrapped directly) and non-ZFObject normal C++ types (wrapped by ZFTypeIdWrapper)
then, all reflectable ZFMethod supply ZFMethodGenericInvoker to invoke the method without knowing all actual types

here is a list of functions available in lua to communicate with ZFFramework:

• "zfAlloc("ClassName" [params...])" or "ClassName([params...])"
  alloc a ZFObject type
  "ClassName" can be v_ZFClass, v_zfstring, or native lua string
  if extra init param passed, your class must supplys reflectable ZFObject::objectOnInit
• invoker
  • "ret = zfl_call(obj, "functionName", param0, param1, ...)" or "obj:functionName(param0, param1, ...)"
    call object's instance method, params are optional
    for "functionName", see ZFTypeId_ZFMethod
    "functionName" can be v_ZFMethod, v_zfstring, or native lua string, while other types must exactly match the original types
  • "ret = zfl_call(zfnull, "ClassOrNamespace.methodName", param0, param1, ...)" or "ret = ClassOrNamespace.methodName(param0, param1, ...)"
    call global function or static class member method, params are optional
    for "functionName", see ZFTypeId_ZFMethod
    "functionName" can be v_ZFMethod, v_zfstring, v_ZFClass, or native lua string, while other types must exactly match the original types
    these namespace are considered as the same:
    • ZF_NAMESPACE_GLOBAL_NAME
    • ZF_NAMESPACE_GLOBAL_ABBR_NAME
    • empty string
  • while calling functions with lua raw string, such as "func('abc')", we will try to convert to proper param type by string converter, if overload functions exists, conversion may take more than once, until it matches first function
• ZFEnum
  • "YourEnum.e_YourEnumValue()"
    access the enum value
  • "YourEnumFlags('YourEnumValue1|YourEnumValue2')" or "YourEnumFlags(YourEnum.e_YourEnumValue1(), YourEnum.e_YourEnumValue2, ...)"
    create enum flags
• value holder
  • "value = YourTypeName("yourTypeData")" or "value = zfAlloc("YourTypeName")" or "value = YourTypeName()"
    create a non-ZFObject type registered by ZFTYPEID_DECLARE, return the associated "YourTypeName" that holds the value
    "YourTypeName" represents the type name in ZFTYPEID_DECLARE
    "yourTypeData" store string datas that would be decoded by YourTypeNameFromString
    "yourTypeData" can be v_zfstring, or native lua string
    if your value holder supplys reflectable ZFObject::objectOnInit (ZFOBJECT_ON_INIT_DECLARE_1 series), the value holder can also be constructed by function like call: "YourTypeName(param0, param1)"
  • "value:yourFunc()" or "YourTypeName.YourFunc()"
    for non-ZFObject types that wrapped by ZFTYPEID_DECLARE, you may use ZFMETHOD_USER_REGISTER_0 series to register methods to its wrapper type "YourTypeName", then the methods can be invoked directly to your value type
• value converter
  • "zfl_value(v)"
    convert a value to lua's raw value, the result lua value can be:
    • lua string
    • lua integer
    • lua number
    • lua boolean
  • these types are automatically converted when return from cpp to lua:
    • v_zfbool => lua boolean : use v_zfboolHolder explicitly if necessary
• value comparer
  • "zfl_cmp(v0, v1)"
    compare two values, including ZFObject types and lua types, return:
    • -2 : error or uncomparable
    • -1 : v0 < v1
    • 0 : v0 == v1
    • 1 : v0 > v1
  • "zfl_eq(v0, v1)"
    similar to zfl_cmp, compare two values
    note: due to limitation of lua, v0 == v1 won't work as expected when not all of them are both primitive type or both ZFObject type, it's recommended to use zfl_eq for most case
• callback

  • "ZFCallbackForLua(luaFunc)"
    create a ZFListener from lua function
    the lua function's proto type must be:

    function myLuaCallback(zfargs)
    end

    
    about thread safe:

    • when the callback called in the same ZFThread where the callback created, the callback should work as expected, all variable capture should work
    • when the callback called in different ZFThread:
      • the callback and all captured upvalues would be copied to a new lua state managed by the ZFThread
      • only these value types can be captured:
        • lua primitive types: boolean, integer, number, string
        • ZFObject types

    
    further more, lua function can be converted to ZFListener implicitly

    button:observerAdd(ZFUIButton.E_ButtonOnClick(), function(zfargs)
        end)

    useful in dynamic method register:

    ZFDynamic()
        :staticMethod('MyRetType', 'myMethod', ZFMP()
            :mp('MyParamType', 'p0')
        , function(zfargs)
            ---@type MyRetType
            local p0 = zfargs:param0()
     
            -- return by either of ways:
            zfargs:result(MyRetType())
            -- or simply return
            -- return MyRetType()
        end)

  • "output:output(text[, size, result])"
    write to output callback
  • "input:input(buf [, size, result])"
    read from input callback
• array
  • "ZFCoreArrayCreate([a, b, c, ...])"
    create a array, params support these types:
    • zfauto
    • native lua number (stored as v_zfdouble)
    • native lua string (stored as v_zfstring)
• param and return value
  • simply use lua standard logic to process params and return values, here's some example:

    -- get all params
    local args = {...};
    local argsCount = #args;
    -- return value
    return args[1];

    note that, all params passed from ZFLuaExecute are all zfauto type
• util
  • "zfl_iter(a)"
    util to loop ZFCoreArray, ZFContainer, ZFKeyValueContainer:

    -- for array type
    for i,e in zfl_iter(a) do
    end
    -- for map type
    for i,k,v in zfl_iter(m) do
    end

  • "zfl_range(n, ...)"
    util to perform range loop:

    for i in zfl_range(xxx) do
    end

    • "zfl_range(n)" : loop in range [0, n)
    • "zfl_range(n0, n1)" : loop in range [n0, n1)
    • "zfl_range(n0, n1, offset)" : loop in range [n0, n1), each step with specified offset
• local path info spec
  • "zfl_L()"
    lua_State of current chunk, stored as v_zfptr
  • "ZFLocalPathInfo([localPath])"
    return path info of current context, null if not available
  • "zfimport(localFilePath)"
    util method for ZFLuaExecute + ZFInputForLocal, useful to load local resource or class definition
• debug helper
  • "zfl_tableInfo(v)" or "zfl_tableInfoPrint(v)"
    return string that represents the table
  • "zfl_trace()"
    return lua stack trace as string

note:

• all types would be registered automatically,
• for dynamically loaded library, all types would also be registered normally, however, won't be automatically unregistered when unloaded