RCodeLeveler main library.
RCodeLeveler is a Ruby preprocessor (used when requiring files) that interprets some comments in source files to enable or disable parts of the source code.
Its goal is to activate parts of the source code without any performance issue. For example, logging some information only when the program is run with a given option. The simple implementation would be to dynamically test a condition enabling some parts of the code, but sometimes even a simple condition testing is harmful enough to performances to want to comment/uncomment the function call when needed. RCodeLeveler does it for you.
As it alters tbe source code (in memory) before being interpreted by Ruby, it is not fit to enable source code based on dynamic conditions. It is used while requiring a Ruby source file. The conditions can be dynamically computed before requiring the file, but once it has been done it is too late: disabled code cannot be enabled back (unless you clear every class/module/constant defined by this file, delete its reference from Ruby’s loaded files’ cache and re-require it).
In order to use the functionalities of RCodeLeveler, you have to require your Ruby files using requireLevel function instead of require. Please note it works only with Ruby files.
The files being required using requireLevel can then use some special comments:
##__LVL__ <Lvl> <Line>: <Line> will be enabled only if the default level while requiring this file is greater or equal than <Lvl>.
##__LVLCAT__ <Cat> <Lvl> <Line>: <Line> will be enabled only if the level for category <Cat> is greater or equal than <Lvl> while requiring this file.
##__LVLRUBY__ <Code> ### <Line>: <Line> will be enabled only if the ruby code <b><Code> returns true while requiring this file. Levels for categories while requiring the file can be referenced using the variable $RCLLevels that is of type map< String, Integer > giving the level corresponding to a given category. The default level can be referenced with $RCLLevels[K_Default_Category]. This starts a level section.
##__LVLBEGIN__ <Lvl>: All subsequent lines will be enabled only if the default level while requiring this file is greater or equal than <Lvl>. This starts a level section.
##__LVLCATBEGIN__ <Cat> <Lvl>: All subsequent lines will be enabled only if the level for category <Cat> is greater or equal than <Lvl> while requiring this file. This starts a level section.
##__LVLRUBYBEGIN__ <Code>: All subsequent lines will be enabled only if the ruby code <Code> returns true while requiring this file. Levels for categories while requiring the file can be referenced using the variable $RCLLevels that is of type map< String, Integer > giving the level corresponding to a given category. The default level can be referenced with $RCLLevels[K_Default_Category]. This starts a level section.
##__LVLEND__: End the last opened level section of lines to be enabled/disabled that has been started with ##__LVLBEGIN__, ##__LVLCATBEGIN__ or ##__LVLRUBYBEGIN__ directives.
Level sections can be hierarchically embedded one in another. If the inclusion of a level section is useless (because it will have the same activation level as its surrounding level section), RCodeLeveler will issue a warning during the file parsing.
The following functions can be used to set levels before requiring the file:
RCodeLeveler::setLevel(iLevel): Set the default level.
RCodeLeveler::setLevel(iLevel, iCategory): Set the level for a given category.
RCodeLeveler::resetLevels: Reset all levels for all categories to 0.
Please note that using only ##__LVL__, ##__LVLCAT__ and ##__LVLRUBY__ directives enables you to also require the file without RCodeLeveler, with all leveled code commented. This can be useful if you use RCodeLeveler to just activate source code for debugging purposes only.
You can also define different behaviour while encountering warnings during a file’s parsing with function:
where iWarningSeverity can be:
0: No warning.
1: Display them on stderr.
2: Throw an exception (default)
It is also possible to get the content of a file once leveled in a list of strings using function RCodeLeveler.getLeveledFileContent(iLibraryName). RCodeLeveler can also write in a repository all files that have been leveled, by settinhg a directory name using function RCodeLeveler.setOutputDirectory(iDirectory) (setting the argument to nil disables the functionality). Those 2 last functionalities (added in versions >= 0.1.X) provide ways to release your files without any dependency on RCodeLeveler itself: you use it to generate your Ruby files leveled, and then you can require them normally without RCodeLeveler.
Please check the tests to find examples of all possible functionalities and uses.