CodeMirror


codemirror.net

I’m learning some CodeMirror. This is not the first time i try to learn CodeMirror, i had some unsuccessful attempts in the past, but after a lot of trial and errors trying to create my own highlight text editor in javascript, finally i adquire the knowledge to understand it a little bit better to the point were i was able to learn from it.

So, the first thing i didn’t understood about this (because all the code parsing was a new concept for me) was how the mecanism worked.  I was too n00b to understand the documentation, so now, here i will explain what i understood in simple terms in case someone else out there is trying to learn it but requires an easy introduction. This is for people wanting to create their own, custom syntax highlighters. If you want to use it for existing languages, read the “how to use” documentation from codemirror, they have really good examples.

—–

CodeMirror.defineMode()

This is what you use to define a mode. A mode is basically a syntaxt highligher (example: you have javascript modes, C++ mode, PHP mode, etc…) The mode object is the rsponsable of parsing the text and applying CSS styles to TOKENs (which will colorize the text)

1) The process is simple. CodeMirror will send a stream object to your parser, starting from char 0 and will go line by line to the end of the textarea.

2) The stream object represents a token, from it’s start ( the begining of a line or the end of another token ) to the end of the line. If you dont do anything, this token will represent one line of text in the textarea.

3) Your mode’s token method has to return a string, a CSS class name that will be applyed to the current token.  You set this class in the styles to format your custom highlighter.

3) The “cursor” or the position at which CodeMirror reads the text must be advanced, you are responsable of this.  You can move char by char, or by many chars at a time. Always inside a single line of text.

4) The stream object has many methods to move the position of the position of the “cursor”. When you move, what you are actually doing is changing the “length” of the current token. THe token starts at the begining of a line or at the end of a previous token. So if you move 3 chars ahead, the token will be 3 chars long.

5) Basic example. This highlighter will only highlight the word “hello” of a textarea:

CodeMirror.defineMode("hello", function() {
  return {
    token: function(stream,state) {

      //stream match moves the cursor forward, so the text token will start at the END of "hello"
      //So if the line of text said: "hello world" one token will be [hello] and the other [ world]
      //NOTICE: ^ matches the start of the token, not the start of the line!
      if ( stream.match(/^hello/) ) {
        return "red-text";
      }

      return;
    }
  };
});

6) Then you have a 2nd object, called “state object” this is just a plain javascript object that YOU setup to keep a state based on the parsing of the tokens. This object is set at the start of a parsing session and passed to your token method each time a token is analyzed. How you handle this object is up to you and it’s not the responsability of CodeMirror’s parser.

The common usage of the state object obviously will be to implement a State pattern to colorize tokens in a certain context.

I hope someone find this article helpful.

Advertisements