The other day I made my first library (a 7-segment display controller) for my new Arduino Uno, following two nice tutorials. They both mention that it’s a good idea to make a keywords.txt file for new libraries, which gives hints to the Arduino IDE’s syntax highlighter. However, neither gives a thorough explanation of format of that file. I thought I would document my findings.

The built-in keywords are defined an a simple text file. On my computer, this lives at /Applications/Arduino.app/Contents/Resources/Java/lib/keywords.txt. Here’s how it starts:

[bash]# LITERAL1 specifies constants

HIGH LITERAL1 Constants
LOW LITERAL1 Constants[/bash]

The interesting thing here is that there are three fields which get parsed. Only the first two are useful.

  1. The keyword to highlight
  2. The type of keyword it is. This really just determines the color, but most people seem to use the following convention:
    • KEYWORD1 Classes, datatypes, and C++ keywords
    • KEYWORD2 Methods and functions
    • KEYWORD3 setup and loop functions, as well as the Serial keywords
    • LITERAL1 Constants
    • LITERAL2 Built-in variables (unused by default)
  3. Documentation page. This is used by the ‘Help<Find in Reference’ menu item. For example, the reference for HIGH in the example above would be file:///Applications/Arduino.app/Contents/Resources/Java/reference/Constants.html.

By default, Arduino 1.0 colors all the KEYWORD types orange, and all the LITERAL types blue. These defaults are set in the /Applications/Arduino.app/Contents/Resources/Java/lib/theme/theme.txt. Here’s the relevant snippet (the comments seem to be inaccurate or outdated):

[bash]# TEXT – KEYWORDS

# e.g abstract, final, private
editor.keyword1.style = #cc6600,plain

# e.g. beginShape, point, line
editor.keyword2.style = #cc6600,plain

# e.g. byte, char, short, color
editor.keyword3.style = #cc6600,bold

# TEXT – LITERALS

# constants: e.g. null, true, this, RGB, TWO_PI
editor.literal1.style = #006699,plain

# p5 built in variables: e.g. mouseX, width, pixels
editor.literal2.style = #006699,plain[/bash]

Just change any of the hexadecimal colors. I like the following:

[code]editor.keyword1.style = #cc6600,plain
editor.keyword2.style = #993300,plain
editor.keyword3.style = #993300,bold
editor.literal1.style = #006699,plain
editor.literal2.style = #0099CC,plain[/code]

If loop and setup aren’t showing up bold, you may be using Monaco, which doesn’t have a bold style. I recommend using another fixed-width font which does have a bold style, such as DejaVu Sans Mono. This can be set in the Arduino preferences file, ~/Library/Arduino/preferences.txt:

[code]editor.font=DejaVu Sans Mono,plain,10
editor.antialias=true[/code]

Make sure the Arduino IDE is not running, as it overwrites the preferences file upon exit.

12 thoughts on “Arduino IDE keywords

  1. Thanks for this. you should consider contributing it to the arduino playground site.

  2. One more. possibly known to others, but the method/function/class/etc and type of keyword should be tab separated.

    as in

    WireKEYWORD1

  3. Can you just tell me how to add a new field of Keyword… like i want to add “Keyword4”

    So want to use keyword4 in my library to give a different color to my functions and system functons.

    1. You would have to modify the Arduino IDE if you wanted to add an additional color to the syntax highlighter. It’s open source, so that should be possible. If you simply add ‘KEYWORD4′ lines to your keywords.txt they will probably be ignored by the file parser, or could possibly result in an exception.

  4. Thank you so much for posting! Thanks for sharing!

    FYI, I created an Arduino DC Motor class and a few keywords are properly highlighted (such as the name of the class ArduinoDCMotor and member functions stop, speed, etc) and other functions are not being heighlighted (such as run, brake, roll)

    I wonder if member function names such as brake are conflicting with other keywords?

    I would appreciate if you knew something about it. But first and foremost thank you for your post!

  5. Fixed the issue:
    Just for completeness. I was using emacs and using only on tab between my keyword and KEYWORD1 (etc)

    But somehow the tabs where not correct.

    Rewrote the file in gedit and now it works…

    Thanks again!

    1. Glad you fixed it. Emacs is often configured to auto-expand tabs into spaces, but it should be possible to turn this off. I use vi myself…

  6. In Windows 7, this file appears to be just off the root of the Arduino install, such as arduino-1.0.5lib

    Thanks for posting this!

Leave a Reply

Your email address will not be published. Required fields are marked *