npLogs plugin

About this plugin

This plugin allow you to deal with one or more log files from your publications. Specify the log file path or use the default log file in order to add entries: info, error, warning, etc. Use the various inline templates in order to enhance the log file.

You can instantiate various log files objects, so can work with various logs files at the same time. The plugin have certain events in order to control the entries which can be added to the log file. Easy to use but useful for debug purpose, for example.

Thirparty

This plugin are imposible without the aid of this people:

Thanks a lot!

Plugin actions index

npLogsCreate

Create a new Logs object instance. Provide an optional log file path or let this argument empty to use the default log file path, which is saved on your publication directory, and have the same name, but with the ".log" extension. For example, if your publication is named "My Book Address.exe", then the default log file path (if you didn't specify other) is "My Book Address.log".

The result variable store the numeric ID of the create Logs file instance: you use this ID later with other plugin actions. You can create various instances of Logs objects, but, note that if you specify the same publication file (or use the default one) the result variable store the instance ID for the first created Logs object.

↑↑

npLogsDestroy

Destroy a previosly created Logs object instance. The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsDestroyAll

Destroy all previosly created Logs object instances.

↑↑

npLogsAdd

Add a new entry to the specified Logs object instance. Remember that the Message argument can contain Log files inline templates. The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsInfo

Add a new info entry to the specified Logs object instance. This action act in the same way that npLogsAdd, but prepend to the specified message the "Info" word. The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsError

Add a new error entry to the specified Logs object instance. This action act in the same way that npLogsAdd, but prepend to the specified message the "Error" word. The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsWarning

Add a new warning entry to the specified Logs object instance. This action act in the same way that npLogsAdd, but prepend to the specified message the "Warning" word. The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsDupe

Provide an string to be duplicated N times before add to the specified Logs object instance. You can use this action to decorate or separate log file sections, which can help you when reading the log file. For example, take a look at the below code, which write a "header" on the log file:

npLogsDupe "[LogID]" "=" "60" "[Result]"
npLogsInfo "[LogID]" "{n} :: {pc} :: {u}" "[Result]"
npLogsDupe "[LogID]" "=" "60" "[Result]"

This produce a result similar to this:

============================================================
Info: 30/05/2012 23:52:51 :: DECONE :: dec
============================================================

The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsSize

Get the log file size (in bytes) for the specified Logs object instance. The result variable store the size of the log in bytes. Note that the result variable can also store "-1", if the log file don't exists (because any entry is added yet) or "False" if an error ocurr. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsDelete

Delete the log file of the specified Logs object instance. The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npLogsFilePath

Get the log file path of the specified Logs object instance. The result variable store the log file path if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npOnLogsBeforeParse

Set a publication subroutine to be executed when the on the specified Logs object before parse event is fired. The Instance ID variable store the ID of Logs object instance which fired the event: using this variable you can easily shared the same subroutine with various instances. The message variable store the message to add into the log file.

This event is fired just before the plugin parse and expand the Log files inline templates. Note that you can change the content of the Message variable and this changes take effect, so if you change the message the changed message is finally added to the log file, if you allow it in the npOnLogsAfterParse action/subroutine (if used).

The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

npOnLogsAfterParse

Set a publication subroutine to be executed when the on the specified Logs object after parse event is fired. The Instance ID variable store the ID of Logs object instance which fired the event: using this variable you can easily shared the same subroutine with various instances. The message variable store the message to add into the log file. The Allow variable argument can be an (optional) variable name to be used on the subroutine. If you set the Allow variable to "False", the plugin finally reject the log entry and this are not added to the log file.

This event is fired just after the plugin parse and expand the Log files inline templates. Note that you can change the content of the Message variable and this changes take effect, so if you change the message the changed message is finally added to the log file, if you allow it, which is the default behaviour (if you didn't set the Allow variable to "False").

The result variable store "True" if everyhing is OK, or "False" if not, for example, because no instance is found with the provided ID. The [LastError] variable contain information about the error in this last case.

↑↑

Log files inline templates

Then you add entries to a log file can use certain inline templates which are expanded by the plugin before add to the log file. This inline templates can contain useful related information around the system and your publication, for example.

Note that every inline template have both short and large names. You can use whatever you want, since the result is exactly the same.

Remember you can use one or more of this inline templates when add log file entries, for example:

npLogsInfo "[LogID]" "{n} :: {pc} :: {u} :: Hello world!" "[Result]"

The above action produce a log entry like this:

Info: 30/05/2012 23:41:19 :: DECONE :: dec :: Hello world!

↑↑

Action errors subroutine

All the NeoPlugins deal with errors in the same way that NeoBook does: when the plugin found an action error the [LastError] variable store information about the error, so you can take care about this variable when execute an action.

But all the NeoPlugins also incorporate an advanced way to deal with possible action errors. You can define a subroutine named OnNeoPluginActionError in order to be executed when some action error are found and you can use this variables inside:

Note that this error handling subroutine are shared for all the NeoPlugins, so you no need to specify a subroutine for every plugin you use in your publication because the same subroutine are recognized and automagically used by every NeoPlugin. Below you can view a sample of this subroutine code:

:OnNeoPluginActionError
  AlertBox "NeoPlugin Error" "Error [LastError] in plugin: [PluginName]"
Return

Also note that the use of this NeoPlugins error handling subroutine is completelly optional. You can continue using the [LastError] variable as usual and even use the both methods at the same time.

↑↑