|
| 1 | +/* |
| 2 | +Eris - Heavy-duty persistence for Lua 5.2.4 - Based on Pluto |
| 3 | +Copyright (c) 2013-2015 by Florian Nuecke. |
| 4 | +
|
| 5 | +Permission is hereby granted, free of charge, to any person obtaining a copy |
| 6 | +of this software and associated documentation files (the "Software"), to deal |
| 7 | +in the Software without restriction, including without limitation the rights |
| 8 | +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell |
| 9 | +copies of the Software, and to permit persons to whom the Software is |
| 10 | +furnished to do so, subject to the following conditions: |
| 11 | +
|
| 12 | +The above copyright notice and this permission notice shall be included in |
| 13 | +all copies or substantial portions of the Software. |
| 14 | +
|
| 15 | +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR |
| 16 | +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, |
| 17 | +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE |
| 18 | +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER |
| 19 | +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, |
| 20 | +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN |
| 21 | +THE SOFTWARE. |
| 22 | +*/ |
| 23 | + |
| 24 | +/* lua.h must be included before this file */ |
| 25 | + |
| 26 | +#ifndef ERIS_H |
| 27 | +#define ERIS_H |
| 28 | + |
| 29 | +#define ERIS_VERSION_MAJOR "1" |
| 30 | +#define ERIS_VERSION_MINOR "1" |
| 31 | +#define ERIS_VERSION_NUM 101 |
| 32 | +#define ERIS_VERSION_RELEASE "1" |
| 33 | + |
| 34 | +/* |
| 35 | +** ================================================================== |
| 36 | +** API |
| 37 | +** ================================================================== |
| 38 | +*/ |
| 39 | + |
| 40 | +/** |
| 41 | + * This provides an interface to Eris' persist functionality for writing in |
| 42 | + * an arbitrary way, using a writer. |
| 43 | + * |
| 44 | + * When called, the stack in 'L' must look like this: |
| 45 | + * 1: perms:table |
| 46 | + * 2: value:any |
| 47 | + * |
| 48 | + * 'writer' is the writer function used to store all data, 'ud' is passed to |
| 49 | + * the writer function whenever it is called. |
| 50 | + * |
| 51 | + * [-0, +0, e] |
| 52 | + */ |
| 53 | +LUA_API void eris_dump(lua_State* L, lua_Writer writer, void* ud); |
| 54 | + |
| 55 | +/** |
| 56 | + * This provides an interface to Eris' unpersist functionality for reading |
| 57 | + * in an arbitrary way, using a reader. |
| 58 | + * |
| 59 | + * When called, the stack in 'L' must look like this: |
| 60 | + * 1: perms:table |
| 61 | + * |
| 62 | + * 'reader' is the reader function used to read all data, 'ud' is passed to |
| 63 | + * the reader function whenever it is called. |
| 64 | + * |
| 65 | + * The result of the operation will be pushed onto the stack. |
| 66 | + * |
| 67 | + * [-0, +1, e] |
| 68 | + */ |
| 69 | +LUA_API void eris_undump(lua_State* L, lua_Reader reader, void* ud); |
| 70 | + |
| 71 | +/** |
| 72 | + * This is a stack-based alternative to eris_dump. |
| 73 | + * |
| 74 | + * It expects the perms table at the specified index 'perms' and the value to |
| 75 | + * persist at the specified index 'value'. It will push the resulting string |
| 76 | + * onto the stack on success. |
| 77 | + * |
| 78 | + * [-0, +1, e] |
| 79 | + */ |
| 80 | +LUA_API void eris_persist(lua_State* L, int perms, int value); |
| 81 | + |
| 82 | +/** |
| 83 | + * This is a stack-based alternative to eris_undump. |
| 84 | + * |
| 85 | + * It expects the perms table at the specified index 'perms' and the string |
| 86 | + * containing persisted data at the specified index 'value'. It will push the |
| 87 | + * resulting value onto the stack on success. |
| 88 | + * |
| 89 | + * [-0, +1, e] |
| 90 | + */ |
| 91 | +LUA_API void eris_unpersist(lua_State* L, int perms, int value); |
| 92 | + |
| 93 | +/** |
| 94 | + * Pushes the current value of a setting onto the stack. |
| 95 | + * |
| 96 | + * The name is the name of the setting to get the value for: |
| 97 | + * - 'debug' whether to write debug information when persisting function |
| 98 | + * prototypes (line numbers, local variable names, upvalue names). |
| 99 | + * - 'maxrec' the maximum complexity of objects we support (the nesting level |
| 100 | + * of tables, for example). This can be useful to avoid segmentation |
| 101 | + * faults due to too deep recursion when working with user-provided |
| 102 | + * data. |
| 103 | + * - 'path' whether to generate a "path" used to indicate where in an object |
| 104 | + * an error occurred. This adds considerable overhead and should |
| 105 | + * only be used to debug errors as they appear. |
| 106 | + * - 'spio' whether to pass IO objects along as light userdata to special |
| 107 | + * persistence functions. When persisting this will pass along the |
| 108 | + * lua_Writer and its void* in addition to the original object, when |
| 109 | + * unpersisting it will pass along a ZIO*. |
| 110 | + * - 'spkey' the name of the field in the metatable of tables and userdata |
| 111 | + * used to control persistence (on/off or special persistence). |
| 112 | + * |
| 113 | + * If an unknown name is specified this will throw an error. |
| 114 | + * |
| 115 | + * [-0, +1, e] |
| 116 | + */ |
| 117 | +LUA_API void eris_get_setting(lua_State *L, const char *name); |
| 118 | + |
| 119 | +/** |
| 120 | + * Changes the value of a setting to a value on the stack. |
| 121 | + * |
| 122 | + * For the available settings see eris_set_setting(). This will get the new |
| 123 | + * value from the specified stack index 'value'. If the type does not match |
| 124 | + * this will throw an error. Specify a nil value to reset the setting to its |
| 125 | + * default value. |
| 126 | + * |
| 127 | + * [-0, +0, e] |
| 128 | + */ |
| 129 | +LUA_API void eris_set_setting(lua_State *L, const char *name, int value); |
| 130 | + |
| 131 | +/* |
| 132 | +** ================================================================== |
| 133 | +** Library installer |
| 134 | +** ================================================================== |
| 135 | +*/ |
| 136 | + |
| 137 | +/** |
| 138 | + * This pushes a table with the two functions 'persist' and 'unpersist': |
| 139 | + * persist([perms,] value) |
| 140 | + * Where 'perms' is a table with "permanent" objects and 'value' is the |
| 141 | + * value that should be persisted. Returns the string with persisted data. |
| 142 | + * If only one value is given, the perms table is assumed to be empty. |
| 143 | + * |
| 144 | + * unpersist([perms,] value) |
| 145 | + * Where 'perms' is a table with the inverse mapping as used when |
| 146 | + * persisting the data via persist() and 'value' is the string with the |
| 147 | + * persisted data returned by persist(). Returns the unpersisted value. |
| 148 | + * If only one value is given, the perms table is assumed to be empty. |
| 149 | + */ |
| 150 | +LUA_API int luaopen_eris(lua_State* L); |
| 151 | + |
| 152 | +#endif |
| 153 | + |
0 commit comments