Go Down

Topic: KEYWORDS.TXT (Read 17890 times) previous topic - next topic

hsteve


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 (<library>.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 ?

HazardsMind

#1
Feb 17, 2013, 12:05 am Last Edit: Feb 17, 2013, 12:21 am by HazardsMind Reason: 1
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.
My GitHub:
https://github.com/AndrewMascolo?tab=repositories

hsteve

#2
Feb 17, 2013, 12:16 am Last Edit: Feb 17, 2013, 12:19 am by hsteve Reason: 1
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.

AWOL

Nothing needs to go in there, it's not a part of the language.
"Pete, it's a fool looks for logic in the chambers of the human heart." Ulysses Everett McGill.
Do not send technical questions via personal messaging - they will be ignored.
I speak for myself, not Arduino.

marco_c

#4
Feb 17, 2013, 10:53 pm Last Edit: Mar 06, 2016, 06:31 am by marco_c
You ask a good question and here is what I have been able to glean from examples I have seen.

Code: [Select]
#######################################
# 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/
Arduino Libraries https://github.com/MajicDesigns?tab=Repositories
Parola for Arduino https://github.com/MajicDesigns/Parola
Arduino++ blog https://arduinoplusplus.wordpress.com

ptdecker

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

econjack

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

Quote
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.

Delta_G

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.
If at first you don't succeed, up - home - sudo - enter.

econjack

@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.

Delta_G

If it would only do it for the libraries I had included in the sketch I would probably feel differently. 
If at first you don't succeed, up - home - sudo - enter.

voxelman

Update to #4:

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

marco_c

That site does not exist?
Arduino Libraries https://github.com/MajicDesigns?tab=Repositories
Parola for Arduino https://github.com/MajicDesigns/Parola
Arduino++ blog https://arduinoplusplus.wordpress.com


MikeyMoMo

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

greenonline

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

Go Up