|
| 1 | + |
| 2 | +# Scripting API |
| 3 | + |
| 4 | +This document describes the interface to be used to inject messages into the InfoLogger logging system from languages other than C or C++. |
| 5 | + |
| 6 | +Languages currently supported are: Tcl, Python, Go, Javascript (node.js/v8). |
| 7 | + |
| 8 | +A subset of the InfoLogger C++ API (covering most use-cases) is exported using SWIG-generated modules. This avoids the tedious work of manually writing native bindings calling the C++ library for each language (although this is still possible for the brave). InfoLogger provides them ready to use! |
| 9 | + |
| 10 | +This documentation includes a reference of the exported functions, and language-specific example code calling the infoLogger module. |
| 11 | + |
| 12 | +As the C++ interface uses some complex types which can not be transparently converted to all languages, we defined this simplified API with string-only parameters. Although some overhead is added by the generalized used of strings to access the logging message structure fields (compared to the native C++ API), the performance loss is not significant for most situations. A typical machine can still log over 100000 messages per second from a script. |
| 13 | + |
| 14 | + |
| 15 | + |
| 16 | +## Classes reference |
| 17 | + |
| 18 | +Default constructor and destructor are not shown here. |
| 19 | + |
| 20 | +* `class InfoLogger` |
| 21 | + |
| 22 | + The main class, to create a handle to the logging system. It provides the methods to inject log messages: |
| 23 | + * `logInfo(string message)` |
| 24 | + Sends a message with severity Info. |
| 25 | + * `logError(string message)` |
| 26 | + Sends a message with severity Error. |
| 27 | + * `logWarning(string message)` |
| 28 | + Sends a message with severity Warning. |
| 29 | + * `logFatal(string message)` |
| 30 | + Sends a message with severity Fatal. |
| 31 | + * `logDebug(string message)` |
| 32 | + Sends a message with severity Debug. |
| 33 | + * `log(message)` |
| 34 | + Sends a message with default severity and metadata. |
| 35 | + * `log(InfoLoggerMetadata metadata, string message)` |
| 36 | + Send a message with specific metadata (instead of the default, if one defined). |
| 37 | + * `setDefaultMetadata(InfoLoggerMetadata metadata)` |
| 38 | + Define some metadata to be used by default for all messages. |
| 39 | + * `unsetDefaultMetadata()` |
| 40 | + Reset the default metadata. |
| 41 | + |
| 42 | + |
| 43 | +* `class InfoLoggerMetadata` |
| 44 | + |
| 45 | + It is used to specify extra fields associated to a log message. An object of this type can be optionnaly provided to the logging function to set some specific message fields. |
| 46 | + * `setField(string key, string value)` |
| 47 | + Set one of the field to a specific value. An empty value reset this field to the default. List of valid fields include: *Severity, Level, ErrorCode, SourceFile, SourceLine, Facility, Role, System, Detector, Partition, Run* |
| 48 | + * `InfoLoggerMetadata(InfoLoggerMetadata)` |
| 49 | + Copy-constructor, to copy an existing InfoLoggerMetadata object to a new one. |
| 50 | + |
| 51 | + |
| 52 | +## Example usage |
| 53 | + |
| 54 | +Example usage is shown below. Library files listed there are available from the infoLogger library installation directory. |
| 55 | + |
| 56 | +* **Tcl** |
| 57 | + * Library files: `infoLoggerForTcl.so` |
| 58 | + * Code example: (interactive interpreter from the command line) |
| 59 | + ``` |
| 60 | + tclsh |
| 61 | + load infoLoggerForTcl.so |
| 62 | + set logHandle [InfoLogger] |
| 63 | + $logHandle logInfo "This is a test" |
| 64 | + $logHandle logError "Something went wrong" |
| 65 | + ``` |
| 66 | +* **Python** |
| 67 | + * Library files: `_infoLoggerForPython.so` and `infoLoggerForPython.py` |
| 68 | + * Code example: (interactive interpreter from the command line) |
| 69 | + ``` |
| 70 | + python |
| 71 | + import infoLoggerForPython |
| 72 | + logHandle=infoLoggerForPython.InfoLogger() |
| 73 | + logHandle.logInfo("This is a test") |
| 74 | + logHandle.logError("Something went wrong") |
| 75 | + ``` |
| 76 | +* **Go** |
| 77 | + * Library files: `infoLoggerForGo.a` and `infoLoggerForGo.go`, to be copied to your `${GOPATH}/src/infoLoggerForGo` |
| 78 | + * Build: `CGO_LDFLAGS="${GOPATH}/src/infoLoggerForGo/infoLoggerForGo.a -lstdc++" go build` |
| 79 | + * Code example: |
| 80 | + ``` |
| 81 | + package main |
| 82 | + import "infoLoggerForGo" |
| 83 | + func main() { |
| 84 | + var logHandle=infoLoggerForGo.NewInfoLogger() |
| 85 | + logHandle.LogInfo("This is a test") |
| 86 | + logHandle.LogError("Something went wrong") |
| 87 | + } |
| 88 | + ``` |
| 89 | +
|
| 90 | +* **Node.js** |
| 91 | + * Library files: `infoLogger.node` |
| 92 | + * Code example: (interactive interpreter from the command line) |
| 93 | + ``` |
| 94 | + node |
| 95 | + var infoLoggerModule=require("infoLogger"); |
| 96 | + var logHandle=new infoLoggerModule.InfoLogger(); |
| 97 | + logHandle.logInfo("This is a test"); |
| 98 | + logHandle.logError("Something went wrong"); |
| 99 | + ``` |
| 100 | + |
| 101 | +
|
| 102 | +
|
| 103 | +## Tips |
| 104 | +Don't forget to delete the objects if necessary! |
0 commit comments