LuaCocoa.h

Go to the documentation of this file.

/*
 LuaCocoa
 Copyright (C) 2009-2011 PlayControl Software. 
 Eric Wing <ewing . public @ playcontrol.net>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
 furnished to do so, subject to the following conditions:
 
 The above copyright notice and this permission notice shall be included in
 all copies or substantial portions of the Software.
 
 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 
 */

#ifndef LUA_COCOA_H
#define LUA_COCOA_H


#ifndef DOXYGEN_SHOULD_IGNORE_THIS

/* Note: For Doxygen to produce clean output, you should set the 
 * PREDEFINED option to remove ALMIXER_DECLSPEC, ALMIXER_CALL, and
 * the DOXYGEN_SHOULD_IGNORE_THIS blocks.
 * PREDEFINED = DOXYGEN_SHOULD_IGNORE_THIS=1 ALMIXER_DECLSPEC= ALMIXER_CALL=
 */

#if defined(__cplusplus)
    #define LUACOCOA_EXTERN extern "C"
#else
    #define LUACOCOA_EXTERN extern
#endif

#if TARGET_OS_WIN32

    #if defined(NSBUILDINGLUACOCOA)
        #define LUACOCOA_EXPORT __declspec(dllexport)
    #else
        #define LUACOCOA_EXPORT __declspec(dllimport)
    #endif

    #define LUACOCOA_IMPORT __declspec(dllimport)

#else
    #if defined(__GNUC__) && __GNUC__ >= 4 && defined(NSBUILDINGLUACOCOA)
        #define LUACOCOA_EXPORT __attribute__ ((visibility("default")))
    #else
        #define LUACOCOA_EXPORT
    #endif
    
    #define LUACOCOA_IMPORT
#endif

#endif /* DOXYGEN_SHOULD_IGNORE_THIS */



#include <stdarg.h> /* va_list */
#include <stdbool.h>

#ifdef LUACOCOA_DONT_USE_BUNDLED_LUA_HEADERS
    #include "lua.h"
    #include "lualib.h"
    #include "lauxlib.h"
#else
    /* Since I compiled Lua with C-linkage for LuaCocoa, C++ users need the header guards since Lua doesn't
     * specify them in their main headers.
     */
    #ifdef __cplusplus
    extern "C" {
    #endif
        #include <LuaCocoa/lua.h>
        #include <LuaCocoa/lualib.h>
        #include <LuaCocoa/lauxlib.h>
    #ifdef __cplusplus
    }
    #endif
#endif /* end LUACOCOA_DONT_USE_BUNDLED_LUA_HEADERS */
/* Hide Obj-C stuff for people writing pure C (or C++) programs that just want access to the LuaCocoa C APIs */
#ifdef __OBJC__ 
#import <Foundation/Foundation.h>

// Forward declaration so I don't need to #include "lua.h" here. (I don't have to worry about the search path of Lua for the public header.)
// But I have to use the formal "struct" version of the name instead of the typedef, i.e. "struct lua_State" instead of just "lua_State"
struct lua_State;

// Not sure if I want to make part of the API
/*
@protocol LuaCocoaErrorDelegate <NSObject>
@optional
- (void) error:(NSString*)error_string luaState:(lua_State*)lua_state functionName:(NSString*)function_name fileName:(NSString*)file_name lineNumber:(NSInteger)line_number;
@end
*/

LUACOCOA_EXPORT @interface LuaCocoa : NSObject
{
@private
    struct lua_State* luaState;
    bool ownsLuaState;
    NSMutableDictionary* frameworksLoaded;
    bool skipDLopen; // in case you are using with other language bridges
    bool disableImportFromLua; // consider for sandboxing

    // Not sure if I want to make part of the API
//  lua_CFunction luaErrorFunction;
//  id<LuaCocoaErrorDelegate> errorDelegate;

}
@property(assign, readonly) struct lua_State* luaState;
@property(assign) bool skipDLopen;
@property(assign) bool disableImportFromLua;

// Not sure if I want to make part of the API
//@property(assign) lua_CFunction luaErrorFunction;
//@property(assign) id<LuaCocoaErrorDelegate> errorDelegate;

- (id) init;

- (id) initWithLuaState:(struct lua_State*)lua_state assumeOwnership:(bool)should_assume_ownership;

// Might be moved to private API
- (bool) loadFrameworkWithBaseName:(NSString*)base_name hintPath:(NSString*)hint_path searchHintPathFirst:(bool)search_hint_path_first skipDLopen:(bool)skip_dl_open;

// Might be moved to private API
- (bool) isFrameworkLoaded:(NSString*)base_name;

- (void) collectExhaustivelyWaitUntilDone:(bool)should_wait_until_done;

+ (void) collectExhaustivelyWaitUntilDone:(bool)should_wait_until_done;

- (NSString*) pcallLuaFunction:(const char*)lua_function_name withSignature:(const char*)parameter_signature, ...;
- (NSString*) pcallLuaFunction:(const char*)lua_function_name errorFunction:(lua_CFunction)error_function withSignature:(const char*)parameter_signature, ...;
// Not sure if I want to make an API or not
//- (void) error:(const char *)fmt, ...;

@end


//LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* const kLuaCocoaErrorDomain /* = @"kLuaCocoaErrorDomain" */;

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsInstance(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT id LuaCocoa_CheckInstance(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT id LuaCocoa_ToInstance(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushInstance(struct lua_State* lua_state, id the_object);

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsClass(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT Class LuaCocoa_CheckClass(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT Class LuaCocoa_ToClass(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushClass(struct lua_State* lua_state, Class the_class);

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsNSNumber(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSNumber* LuaCocoa_CheckNSNumber(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSNumber* LuaCocoa_ToNSNumber(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushUnboxedNSNumber(struct lua_State* lua_state, NSNumber* the_number);

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsNSNull(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSNull* LuaCocoa_CheckNSNull(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSNull* LuaCocoa_ToNSNull(struct lua_State* lua_state, int stack_index);

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsNSString(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* LuaCocoa_CheckNSString(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* LuaCocoa_ToNSString(struct lua_State* lua_state, int stack_index);

LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushUnboxedNSString(struct lua_State* lua_state, NSString* the_string);
LUACOCOA_EXTERN LUACOCOA_EXPORT __strong const char* LuaCocoa_ToString(struct lua_State* lua_state, int stack_index);

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsNSArray(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushUnboxedNSArray(struct lua_State* lua_state, NSArray* the_array);


LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsNSDictionary(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushUnboxedNSDictionary(struct lua_State* lua_state, NSDictionary* the_dictionary);

LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsPropertyList(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT id LuaCocoa_ToPropertyList(struct lua_State* lua_state, int stack_index);

LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushUnboxedPropertyList(struct lua_State* lua_state, id the_object);


// Warning: will convert strings and nsstrings and NSValue's with correct encoding to selectors
// Becareful to check for strings/nsstrings separately if you need to distinguish
LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsSelector(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT SEL LuaCocoa_CheckSelector(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT SEL LuaCocoa_ToSelector(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PushSelector(struct lua_State* lua_state, SEL the_selector);

LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* LuaCocoa_GetInfoOnFunction(lua_State* lua_state, const char* function_name, int* line_defined, int* last_line_defined);

LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* LuaCocoa_ParseForErrorFilenameAndLineNumber(NSString* the_string, int* line_number);

// Warning: Parameter signatures are subject to change in future releases to be more consistent with Obj-C. Sorry.
LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* LuaCocoa_PcallLuaFunction(lua_State* lua_state, lua_CFunction lua_error_function, const char* lua_function_name, const char* parameter_signature, ...);
LUACOCOA_EXTERN LUACOCOA_EXPORT NSString* LuaCocoa_PcallLuaFunctionv(lua_State* lua_state, lua_CFunction lua_error_function, const char* lua_function_name, const char* parameter_signature, va_list vl);


#endif /* __OBJC__ */

LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PrependToLuaSearchPath(struct lua_State* lua_state, const char* search_path);

LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_AppendToLuaSearchPath(struct lua_State* lua_state, const char* search_path);

LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_PrependToCSearchPath(struct lua_State* lua_state, const char* search_path);

LUACOCOA_EXTERN LUACOCOA_EXPORT void LuaCocoa_AppendToCSearchPath(struct lua_State* lua_state, const char* search_path);


// These struct APIs may be subject to change. I'm unhappy with the keyname vs. structname issues.
// These functions are mostly untested. Please report bugs/problems/API defects.
LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsStruct(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_IsStructWithName(struct lua_State* lua_state, int stack_index, const char* key_name);
LUACOCOA_EXTERN LUACOCOA_EXPORT const char* LuaCocoa_GetStructName(struct lua_State* lua_state, int stack_index);
LUACOCOA_EXTERN LUACOCOA_EXPORT void* LuaCocoa_CheckStruct(struct lua_State* lua_state, int stack_index, const char* key_name);
LUACOCOA_EXTERN LUACOCOA_EXPORT bool LuaCocoa_PushStruct(struct lua_State* lua_state, void* the_struct, const char* key_name);

#endif /* LUA_COCOA_H */