KEYWORDS.TXT

KEYWORDS.TXT

Postby steveh » Sat Feb 16, 2013 10:16 am Good evening,

I've just written a Library file for Arduino, and the Tutorial I did said I should create a KEYWORDS.TXT for the Library, but doesn't really explain what this file does.

Is it necessary, if so what does it do ?

Also, every time I change the library, is it correct that I have to delete the object file (.cpp.o) ? This seems to go in a different directory each day and I have to look around to find it.

Is there any compiler directives I can use to automatically delete this ?

The function of it use is in the name, KEYWORDS. If you make a library, you need to make a keywords file so the Arduino can recognize what your doing. Every library has one, and without it you may have problems.

Try this, go into the servo library, keywords and take out SERVO, then see if your still able to use that library correctly.

Thanks, but what needs to go in there and why ?

I have a very basic KEYWORDS.TXT file that only contains a couple of the function names and not others, and it does not appear to affect compilation of the program.

Nothing needs to go in there, it's not a part of the language.

You ask a good question and here is what I have been able to glean from examples I have seen.

#######################################
# Syntax Coloring Map
#######################################

#######################################
# Datatypes (KEYWORD1)
#######################################

MD_AButton  KEYWORD1

#######################################
# Methods and Functions (KEYWORD2)
#######################################
setKeyId    KEYWORD2
setDetectTime   KEYWORD2
setRepeatTime   KEYWORD2
getKey  KEYWORD2

######################################
# Constants (LITERAL1)
#######################################
KEY_NONE    LITERAL1

KEYWORD1 is generally used for the classes that you define in your library. KEYWORD2 is used for the public member functions of the class. Basically these are the class' methods. LITERAL1 is used for any #defines that are relevant for the user of the library.

I am sure there is more ...

If anyone knows where the reference for the content of this file is located, it would be good to share :).

Update: Quick search on Google landed this article that did not exist last time I looked http://acsweb.ucsd.edu/~sbliven/2012/01/arduino-ide-keywords/

Thank you @marco_c for your helpful response. Documentation on such things seems to be pretty scant.

The following quote is taken from my Beginning C for Arduino book, 2nd ed., page 295:

The keywords.txt File The Arduino IDE lets you add keywords for syntax highlighting if you wish to do so. For the Dates library, the keywords.txt file contains the following lines:

Dates KEYWORD1 IsLeapYear KEYWORD2 GetEaster KEYWORD2

Note that the format used in the keywords.txt file is pretty fussy. That is, in the first line, Dates is immediately followed by a Tab space, then KEYWORD1. This change causes the class name Dates to appear in the color reserved for KEYWORD1 keywords in your source code files. Using the entries shown here, the word Dates, for example, takes on the same color as for, which, else, etc. when it appears in the source code window of the Arduino IDE. The next two lines cause the functions defined in the Dates library to have coloring as defined by KEYWORD2. As before, a Tab space must separate the function name from the KEYWORD2 constant. When you view your source code, the words IsLeapYear and GetEaster take on the same color at any other class methods you may use. The two function names, for example, will now have the same color as print in Serial.print().

For the keywords.txt file to take effect, you need to close and reopen the Arduino IDE.

The Dates library mentioned in the quote is taken from a sample library that the chapter builds as an example. The next paragraph in the book explains the themes.txt file, which allows you to change the colors associated with the KEYWORD? directives. I have trouble seeing certain colors, so I changed the colors to make syntax highlighting more readable for me.

The ONLY purpose it serves is for the IDE to be able to recognize keywords and turn them orange in the editor window. That's it. And the messed up thing is that it will turn any keyword from any keywords.txt file in any library orange regardless of whether or not it is included in the sketch. So with too many of those around you start ending up with a bunch of orange on the screen that doesn't mean anything in the context of the program you're working on.

Many of the standard libraries come with it, but most contributed libraries do not. There is absolutely no consequence to leaving it out. The only difference is that you can't make text in the editor window turn orange. But it has no effect on the performance of the IDE or your program.

@Delta_G: true, it does "colorize" the matching keywords in the file. However, I disagree that it doesn't mean anything. If nothing else, you can use it for its designed purpose: To highlight keywords and class methods if you wish to do so. As I said, I have trouble seeing certain colors and the default color (i.e., orange) is one of them, so I changed it to a different color in the themes.txt file which helps me quite a bit when reading source code files.

I agree there is no performance consequence of leaving it out, but of the 71 libraries that I have in my libraries directory, almost 75% (53) do use the keyword.txt file. The individuals who wrote those libraries evidently thought it worthwhile to add the keyword.txt file for whatever reason. If colorizing bothers anyone else, you can go into the themes.txt file and change the KEYWORD? colors to black, which would have the effect of removing the colorizing.

If it would only do it for the libraries I had included in the sketch I would probably feel differently.

Update to #4:

https://spencer.bliven.us/index.php/2012/01/18/arduino-ide-keywords/

That site does not exist?

The site appears to have moved to: https://spencer.bliven.us/index.php/2012/01/18/arduino-ide-keywords/

Here's something I just discovered by accident. Can't find any documentation on this action.

There only seem to be 3 variations, a strong and dim orange and dim green/blue. LITERAL2 does not seem to exist, giving dim orange. Here's how to get the 3 variations.

This makes a strong Orange -- 1 Tab and KEYWORD1

OneTabKW1 KEYWORD1

This makes a dim Orange -- 2 Tabs and KEYWORD1

TwoTabKW1 KEYWORD1

This makes dim Blue/Green -- 1 Tab and LITERAL1

OneTabLT1 LITERAL1

Same as TwoTabKW1, dim Orange -- 2 Tabs and LITERAL1

TwoTabLT1 LITERAL1

keywords.txt OneTabKW1 KEYWORD1 TwoTabKW1 KEYWORD1 OneTabKW2 KEYWORD2 TwoTabKW2 KEYWORD2

OneTabLT1 LITERAL1 TwoTabLT1 LITERAL1 OneTabLT2 LITERAL2 TwoTabLT2 LITERAL2

Just to add a point, as it does not seem to be stated explicitly:

  • You must use tab characters to separate the keyword and KEYWORD[1/2]
  • If you use spaces on a line, instead of tab characters, then the keyword on that particular line will not be recognised by the IDE