NAntColours (v1.0) – a Task library for output colouring in NAnt
[stextbox id=”info” caption=”Comment or Leave a Message”]
Please Comment or Leave a Message if this is what you are looking for or if you have any question/comment/suggestion/request.
[/stextbox]
[stextbox id=”download” caption=”Download”]NAntColours v1.0[/stextbox]
To me, one of the most surprising thing about NAnt is that it doesn’t support colours out of the box.
NAnt is an amazing tool that allows to build software through a set of really powerful tasks. You can download it from here: http://nant.sourceforge.net/.
I use it quite a lot in different projects and one thing I always missed is the support for colorised console output.
I think that echoing something using different colours helps a lot, even if only to provide a quick spottable info that can help the user (the guy in front of the pc that is waiting for the build to complete) to understand the build stage (especially if it is a long build with several stages).
As soon as I had some time to spend on it I decided to write this feature myself and here I am, sharing this with whoever needs it for its own personal/business process.
I provide the DLL that you can use freely. If you find it useful the only thing I ask is if you can leave a comment and if you have a web page, add a link to this page to help other users.
What it adds
In brief this is the list of functionalities that you will have:
- setcolour – to select the current colour
- pushcolour/popcolour/resetcolour – to manage a stack of colours, so that you can change a colour and go back to the previous when you are done.
- echocolour – an upgrade to the base echo task that colours the message
- execcolour – an upgrade to the base exec task that colours the output in case of error (behaviour and error colour configurable)
- colourfail – an upgrade to any other generic NAnt task, operation or set of operations that colours the output in case of failure (error colour configurable)
The list of tasks that allow to use those functionalities are (in more detail): (Note that you can have this list using the <helpcolour /> task)
[stextbox id=”info” caption=”Tasks”]
- <setcolour [colour=”fc”] [bg=”bc”] [preserve=”tf”] /> – Set the current colour.
- <pushcolour [colour=”fc”] [bg=”bc”] [preserve=”tf”] /> – Push the color in the stack of colours and set it as current colour.
- <popcolour /> – Remove the color on the top of the stack and set the previous one as current colour.
- <resetcolour /> – Reset the colours stack and set the original color as current colour.
- <seterrorcolour [colour=”fc”] [bg=”bc”] /> – Set the colour to use when an error occurs during the execution of execcolour task.
- <reseterrorcolour /> – Reset the default error colour (red on black background).
- <echocolour message=”Message Here” [colour=”fc”] [bg=”bc”] [preserve=”tf”] /> – Echoes the message in the chosen colour.”
- <execcolour [highlighterror=”tf”] …more… /> – Extends the default exec task adding colours capabilities (use the usual “exec” task parameter here). It shows the error using the error colour and, if used with failonerror=”false” and highlighterror=”true” shows the exec exit code using the error colour if it is different from 0 (and logs it as a warning).
- <colourfail [colour=”fc”] [bg=”bc”]> …any othe task there… </colourfail> – Extends the failure colour to everything executed inside the colourfail initial and closing tags. E.g. <colourfail> <fail message=”simulated failure” /> </colourfail>
- <initcolours [silent=”tf”] /> – Initialise the default colour using the current console colour. The default error colour is set to the current error color. Using silent=”true” the DLL version number will not be displayed when the first colour task will be used. NOTE: This task is optional and you can use all other tasks without worrying to use this at any time.
- <helpcolour /> – Shows this help…
Where:
fc : specify the foreground colour to use.
bc : specify the background colour to use.
[…] : specify an optional parameter.
tf : use “true” or “false” there.
…more… : indicates other parameters.
preserve : Preserve the current fc and/or bc when fc and/or bc is not specified. This is false if unspecified.
highlighterror: This is false if unspecified.
[/stextbox]
How to set-up
To use this dll, put it somewhere where your NAnt executable can reach it. If you prefer you can directly add it in the same folder of NAnt.exe.
Somewhere at the start of your NAnt script add this line (assuming that it sits in the same folder):
|
1 |
<loadtasks assembly="NAntColours.dll"/> |
From now on you will be able to access its functionalities in your script.
Feature – Colour Help Command (helpcolour)
Use this task as a reminder for the supported tasks:
|
1 |
<helpcolour /> |
Feature – Direct Colour Change (setcolour)
You can use console color using this syntax:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
<setcolour colour="Yellow" /> <echo message="sample message (Yellow)" /> <setcolour colour="DarkYellow" /> <echo message="sample message (DarkYellow)" /> <setcolour bg="DarkMagenta" /> <echo message="sample message (DarkMagenta Background)" /> <setcolour colour="White" preserve="true" /> <echo message="sample message (White, preserve bg)" /> <setcolour colour="Cyan" bg="Blue" /> <echo message="sample message (Cyan, Blue Background)" /> <echo message="another sample message (Cyan, Blue Background)" /> <setcolour colour="Green" /> <echo message="sample message (Green)" /> |
The output is:
Feature – Coloured Message (Echo Extension: echocolour)
A more direct way to output colour messages is using directly the echocolour task:
|
1 2 3 4 5 6 7 8 9 |
<setcolour bg="DarkRed" /> <echo message="Normal Echo after setting the bg to DarkRed" /> <echocolour message="sample message (Yellow)" colour="Yellow" /> <echocolour message="sample message (DarkYellow)" colour="DarkYellow" /> <echocolour message="sample message (DarkMagenta Background)" bg="DarkMagenta" /> <echocolour message="sample message (White, preserve bg... that is DarkRed!)" colour="White" preserve="true" /> <echocolour message="sample message (Cyan, Blue Background)" colour="Cyan" bg="Blue" /> <echocolour message="sample message (normal colour)" /> <echocolour message="sample message (Green)" colour="Green" /> |
With this result:
Feature – Use Colour Stack (pushcolour, popcolour, resetcolour)
There is a way to use the colours pushing and popping them in and from a stack. This can be useful when invoking sub targets that have to set the colour for themselves but you want them to restore the colour to the previous one when finished.
This is a simple Example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 |
<pushcolour colour="Yellow" /> <echo message="pushcolour Yellow" /> <pushcolour colour="Cyan" /> <echo message="pushcolour Cyan" /> <popcolour /> <echo message="popcolour (yellow)" /> <pushcolour colour="Red" bg="Green" /> <echo message="pushcolour Red, Green bg" /> <pushcolour colour="Black" preserve="true" /> <echo message="pushcolour Black, preserve bg" /> <popcolour /> <echo message="popcolour (Red, Green bg)" /> <popcolour /> <echo message="popcolour (Yellow)" /> <popcolour /> <echo message="popcolour (original)" /> <popcolour /> <echo message="popcolour (useless, again)" /> <pushcolour bg="Blue" /> <echo message="pushcolour Blue bg" /> <popcolour /> <echo message="popcolour (Original and so on...)" /> |
With this result:
To reset the stack at any point you can use the resetcolour task. Example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
<pushcolour colour="Yellow" /> <echo message="pushcolour yellow" /> <pushcolour colour="Cyan" /> <echo message="pushcolour cyan" /> <pushcolour colour="Red" bg="Green" /> <echo message="pushcolour red, green bg" /> <pushcolour colour="Black" preserve="true" /> <echo message="pushcolour Black, preserve bg" /> <resetcolour /> <echo message="back to the original colour after resercolour" /> <popcolour /> <echo message="nothing to pop" /> <pushcolour bg="blue" /> <echo message="pushcolour blue bg" /> <popcolour /> <echo message="popcolour (back to original), and so on..." /> |
Result:
This is a more complex example of stack usage:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 |
<target name="colour_stack_example"> <echo message="Sample of colour stack." /> <echo message="Calling the Cyan with Blue bg sub task..." /> <call target="some_cyan_with_blue_bg_task" /> <echo message="...Cyan with Blue bg sub task returned" /> <echo message="Calling the Geen sub task..." /> <call target="some_green_task" /> <echo message="...Green sub task returned" /> <echo message="End Sample of colour stack." /> </target> <target name="some_cyan_with_blue_bg_task"> <pushcolour colour="Cyan" bg="Blue" /> <echo message="[START] Cyan with Blue bg task" /> <pushcolour colour="Red" /> <echo message="Some red infos" /> <popcolour /> <echo message="Calling the Yellow sub task..." /> <call target="some_yellow_task" /> <echo message="...Yellow sub task returned" /> <echo message="Calling the Geen sub task..." /> <call target="some_green_task" /> <echo message="...Green sub task returned" /> <echo message="[END] Cyan with Blue bg task" /> <popcolour /> </target> <target name="some_yellow_task"> <pushcolour colour="Yellow" /> <echo message="[START] Yellow task" /> <echo message="Calling the Geen sub task..." /> <call target="some_green_task" /> <echo message="...Green sub task returned" /> <echo message="[END] Yellow task" /> <popcolour /> </target> <target name="some_green_task"> <pushcolour colour="Green" preserve="true" /> <echo message="Simple Green task with preserve bg" /> <popcolour /> </target> |
With this result:
Feature – Exec with coloured failures (Exec Extension: execcolour)
In order to quickly use the exec task but with coloured failures, you can use the execcolours task. Those are some examples:
A Simple exec that fails (Building a solution with an error in it):
|
1 2 3 |
<execcolour program="C:WindowsMicrosoft.NETFrameworkv3.5msbuild.exe" workingdir="C:samplesCompileErrorSolution"> <arg value="CompileErrorSolution.sln" /> </execcolour> |
This is the output:
An option is to suppress the failure (as in exec task), but force to highlight the error anyway. This is optional:
|
1 2 3 4 |
<execcolour program="C:WindowsMicrosoft.NETFrameworkv3.5msbuild.exe" workingdir="C:samplesCompileErrorSolution" failonerror="false" highlighterror="true"> <arg value="CompileErrorSolution.sln" /> </execcolour> <echo message="The script continues but we can spot the problem :)" /> |
Result:
Feature – Change Error Colour (seterrorcolour, reseterrorcolour)
The error colour can be changed at any time using seterrorcolour and reseterrorcolour (to bring it back to the default “red” colour):
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
<target name="error_colours"> <call target="exec_fail_nofail" /> <seterrorcolour colour="yellow" bg="blue" /> <call target="exec_fail_nofail" /> <reseterrorcolour /> <call target="exec_fail_nofail" /> </target> <target name="exec_fail_nofail"> <execcolour program="C:WindowsMicrosoft.NETFrameworkv3.5msbuild.exe" workingdir="C:samplesCompileErrorSolution" failonerror="false" highlighterror="true"> <arg value="CompileErrorSolution.csproj" /> </execcolour> <echo message="The script continues but we can spot the problem :)" /> </target> |
And this an excerpt of the output:
Feature – Color the failure of any other task (Generic Extension: colourfail)
If you want to highlight the build failure of any other NAnt task or your other custom task, you can still do so using colourfail!
Here is a really simple example of usage:
|
1 2 3 4 5 6 |
<colourfail> <echo message="Fail coloured sample" /> <echo message="Prepare to fail..." /> <fail message="fail task encapsulated in colourfail"/> <echo message="... Failed (useless message)" /> </colourfail> |
And the result will be:
Another different example is:
|
1 2 3 4 5 6 |
<colourfail bg="Yellow"> <echo message="Prepare to fail..." /> <if test="${4/0 == 0}"> <echo message="This cannot work!" /> </if> </colourfail> |
Resulting in:
Of course you can wrap the whole script in this task, having the coloured error feature always active.
An example that shows this is action is the following:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 |
<target name="colourfail_sample"> <colourfail colour="Yellow"> <echo message="Fail coloured sample" /> <call target="failing_task_caller" /> </colourfail> </target> <target name="failing_task_caller"> <echo message="Calling the failing target" /> <call target="failing_task" /> </target> <target name="failing_task"> <echo message="Prepare to fail..." /> <if test="${4/0 == 0}"> <echo message="This cannot work!" /> </if> <echo message="... Failed (useless message)" /> </target> |
With the expected result:
Feature – Init the default colour and error colour (initcolours)
This task is optional. Everything works even if this is never used.
You must use this as first task if you want to remove the display of the version number that is automatically shown the first time a colour task is used.
When used it will change the default colour and error colour using the current one. This allows to change the result of the task resetcolour and reseterrorcolour.
This is an example:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 |
<initcolours silent="true" /> <echo message="Normal Colour (No version number displayed above)." /> <setcolour colour="yellow" /> <echo message="Now it is Yellow. I will set the Error Colour to Green Now." /> <seterrorcolour colour="green" /> <initcolours /> <echo message="initcolour executed." /> <echo message="Now the default color is Yellow and the default error colour is Green." /> <setcolour colour="cyan" /> <seterrorcolour colour="magenta" /> <echo message="Now I changed the color to Cyan and the error colour to Magenta." /> <reseterrorcolour /> <resetcolour /> <echo message="I reset both colour and error colour. So I expect that:" /> <echo message="* the (new) default colour is Yellow." /> <echo message="* the (new) default error colour is Green." /> <colourfail> <exec program="lol.lol" /> </colourfail> |
Result:
Note that the colour of the console is still recovered despite the default colours have been changed.
More about Colours
The colours must be colours recognised by the console. The system is quite robust but it is safer if you specify the colour using the correct case sensitive string. This because the core tries to match the string to an internal enumeration and this is why it needs to match.
In any case, if the colour is not recognised, or simply wrong, an error will fire allowing to fix the mistake.
Example:
|
1 |
<setcolour colour="Amazing" /> |
Will generate:
Conclusion
I believe this DLL can offer a satisfying set of features to use colours in NAnt with a reasonable degree of flexibility.
Download and use it freely. If you like it, please add a comment and a link to this page to help others benefit of it.
If you have any suggestion, comments or if you want to make a request for something to add in future release, please leave a comment :).
[stextbox id=”download” caption=”Download”]NAntColours v1.0[/stextbox]
Precisely what I was searching for, appreciate it for posting .