This document is optional background reading; it was used mainly as reference during development for naming macros and functions.
En's reliance on a combination of the C preprocessor and its roots in LSL means that the available syntax for any sort of standardized libraries or extensions is extremely limited. Therefore, En - and other projects based on it - attempt to conform to a specific style and naming conventions.
All code in the default state is generated by En and generally should not be modified or extended. Therefore, "En style" is a system of self-enforced function, macro, and variable naming, capitalization, and code organization that enhances code readability and flexibility when using En libraries, especially with other libraries.
Each "En style" LSL script is laid out as follows:
Options - macros that are optionally #define-d at the top of the script - are named and capitalized as follows:
- EVENT_EN_EVENT_NAME is a user-defined raw event handler option. When defined, En will pass raw event_name LSL events through to the matching lowercase function, such as EVENT_EN_LISTEN to en_listen(...) and EVENT_EN_TIMER to en_timer(...).
- EVENT_ENLIBRARYNAME_EVENT_NAME is a user-defined En event handler option, like EVENT_EN_EVENT_NAME but used by an En library instead of En itself, such as EVENT_ENRPC_MESSAGE to enrpc_message(...).
- FEATURE_ENLIBRARYNAME_OPTION_NAME is a library feature option. When defined, En will enable or disable certain library features, such as FEATURE_ENRPC_PROTOCOL_CLEP_SHOUT and FEATURE_ENTIMER_DISABLE_MULTIPLE. These features can significantly modify script size and performance.
- OVERRIDE_TYPE_ENLIBRARYNAME_OPTION_NAME is a library override option. When defined as a specific value, En's default configurable constants can be overridden on compile, such as OVERRIDE_INTEGER_ENRPC_RESERVE_LISTENS and OVERRIDE_FLOAT_ENTIMER_MINIMUM_INTERVAL.
- TRACE_EN enables additional enLog trace logging at compile time for all libraries. (This feature is not currently used, but should eventually enable logging for all possible functions.)
- TRACE_ENLIBRARYNAME enables additional enLog trace logging at compile time for a specific library. (This feature is only used for some libraries and some functions, but should eventually be used for all traceable functions.)
- TRACE_ENLIBRARYNAME_FUNCTIONNAME enables additional enLog trace logging at compile time for a specific function. (This feature is only used with certain functions.)
Options must be #define-d before #include-ing libraries.lsl, which automatically includes each library's macros.lsl, then each library's functions.lsl.
Global variables and internal functions, as well as internal macro functions, are named and capitalized as follows:
- _ENLIBRARYNAME_GLOBAL_NAME is an internal library global variable that the script should not access directly, such as _ENRPC_CLEP and _ENTIMER_QUEUE.
- _enLibraryName_FunctionName is an internal library function or macro that the script should not call directly, such as _enRPC_ListenAll and _enLNX_BuildHead.
¶ Functions and Inline Macros
Functions and inline macros (which are effectively called as functions) are named and capitalized as follows:
- en_event_name is a user-defined raw event handler function. When the matching uppercase EVENT_EN_EVENT_NAME option is defined, En will pass raw event_name LSL events through to en_event_name, such as en_listen and en_timer.
- enlibraryname_event_name is a user-defined En event handler function, like en_event_name but called by an En library instead of En itself, such as enrpc_message and entimer_timer.
- enLibraryName_event_name is a library's public event handler function. No libraries currently use this, because all libraries inject their own internal event handlers as needed (see below); it is, however, useful as a naming scheme for third-party event handler libraries.
- _enlibraryname_event_name is a library's internal event handler that the script should not call directly, such as _enrpc_listen and _entimer_timer.
- enLibraryName_FunctionName is a library function or macro callable by the script, such as enRPC_LEPRequest and enTimer_Start.
Additionally, some macros should not be #define-d but may be referenced in scripts:
- CONST_TYPE_NAME is a constant that cannot be redefined, such as CONST_FLOAT_PI_BY_FOUR or CONST_VECTOR_GREEN.
- FLAG_ENLIBRARYNAME_FLAG_NAME is a flag (integer or bitfield) that is used by an En library, such as FLAG_ENRPC_LISTEN_OWNERONLY and FLAG_ENTIMER_ONESHOT.
- The seven default loglevels: PRINT, FATAL, ERROR, WARN, INFO, DEBUG, and TRACE.
"En style" can be used by other libraries by replacing "en" and "EN" with a prefix of one's choice, such as "myLibraryName_FunctionName" or "myLibraryName_event_name". This allows other libraries to use the same function-based event routing style.
If other libraries are used, they should be #include-d immediately below En's libraries.lsl.