# HG changeset patch # User Steve Losh # Date 1321489006 18000 # Node ID 2b0626af776b8c8a34f58e7fb925026b8ba4d5a1 # Parent 9a3df947974857eb7a3b8f790a39e1e8e7a5605f Moar. diff -r 9a3df9479748 -r 2b0626af776b chapters/44.markdown --- a/chapters/44.markdown Sun Nov 13 19:18:31 2011 -0500 +++ b/chapters/44.markdown Wed Nov 16 19:16:46 2011 -0500 @@ -32,6 +32,13 @@ 8! is: 40320 9! is: 362880 +If you don't get this output, or you get an error, stop and figure out what's +gone wrong. The code should work exactly as-is. + +Take some time to understand how the code works. Refer to the Potion docs +liberally. It's not critical to understanding Vimscript but it will make you +a better programmer. + Detecting Potion Files ---------------------- @@ -45,13 +52,14 @@ Create `ftdetect/potion.vim` in your plugin's repo. Put the following lines into it: - augroup potion_detect - au! - au BufNewFile,BufRead *.pn set filetype=potion - augroup END + au BufNewFile,BufRead *.pn set filetype=potion -This creates an autocommand group with one autocommand inside: a command to set -the filetype of `.pn` files to `potion`. Pretty straightforward. +This creates a single autocommand: a command to set the filetype of `.pn` files +to `potion`. Pretty straightforward. + +Notice that we *didn't* use an autocommand group like we usually would. Vim +automatically wraps the contents of `ftdetect/*.vim` files in autocommand groups +for you, so you don't need to worry about it. Close the `factorial.pn` file and reopen it. Now run the previous command again: diff -r 9a3df9479748 -r 2b0626af776b chapters/45.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/chapters/45.markdown Wed Nov 16 19:16:46 2011 -0500 @@ -0,0 +1,120 @@ +Basic Syntax Highlighting +========================= + +Now that we've gotten the boilerplate out of the way it's time to start writing +some useful code for our Potion plugin. We'll start with some simple syntax +highlighting. + +Create a `syntax/potion.vim` file in your plugin's repo. Put the following code +into the file: + + if exists("b:current_syntax") + finish + endif + + echom "Our syntax highlighting code will go here." + + let b:current_syntax = "potion" + +Close Vim, and then open your `factorial.pn` file. Nothing will happen, but if +you run `:messages` you'll see that the file was indeed loaded. + +**Note:** Whenever I tell you to open the Potion file I want you to do it in +a *new Vim window/instance* instead of in a split/tab. Opening a new Vim window +causes Vim to reload all your bundled files for that window, whereas using +a split does not. + +The lines at the beginning and end of the file are a convention that prevents it +from being loaded if syntax highlighting has already been enabled for this +buffer. + +Highlighting Keywords +--------------------- + +For the rest of this chapter we'll ignore the `if` and `let` boilerplate at the +beginning and end of the file. Don't remove those lines, just forget about them. + +Replace the placeholder `echom` in the file with the following code: + + syntax keyword potionKeyword to times + highlight link potionKeyword Keyword + +Close the `factorial.pn` file and reopen it. The `to` and `times` words will be +highlighted as keywords in your color scheme! + +These two lines show the basic structure of simple syntax highlighting in Vim. +To highlight a piece of syntax: + +* You first define a "chunk" of syntax using `syntax keyword` or a related + command (which we'll talk about later). +* You then link "chunks" to highlighting groups. A highlighting group is + something you define in a color scheme, for example "function names should be + blue". + +This lets plugin authors define the "chunks" of syntax in ways that make sense +to them, and then link them to common highlighting groups. It also lets color +scheme creators define colors for a common set of programming constructs so they +don't need to know about individual languages. + +Potion has a bunch of other keywords that we haven't used in our toy program, so +lets edit our syntax file to highlight those too: + + syntax keyword potionKeyword loop times to while + syntax keyword potionKeyword if elsif else + syntax keyword potionKeyword class return + + highlight link potionKeyword Keyword + +First of all: the last line hasn't changed. We're still telling Vim that +anything in the `potionKeyword` syntax group should be highlighted as +a `Keyword`. + +We've now got three lines, each starting with `syntax keyword potionKeyword`. +This shows that running this command multiple times doesn't *reset* the syntax +group -- it adds to it! This lets you define groups piecemeal. + +How you define your groups is up to you: + +* You might just toss everything onto one line and be done with it. +* You might prefer to break the lines up so they fit within 80 columns to make + them easier to read. +* You could have a separate line for each item in a group, to make diffs looks + nicer. +* You could do what I've done here and group related items together. + +Highlighting Functions +---------------------- + +Another standard Vim highlighting group is `Function`. Let's add some of the +built-in Potion functions to our highlighting script. Edit the guts of your +syntax file so it looks like this: + + syntax keyword potionKeyword loop times to while + syntax keyword potionKeyword if elsif else + syntax keyword potionKeyword class return + + syntax keyword potionFunction print join string + + highlight link potionKeyword Keyword + highlight link potionFunction Function + +Close and reopen `factorial.pn` and you'll see that the built-in potion +functions are now highlighted. + +This works exactly the same way as keyword highlighting. We've defined a new +syntax group and linked it to a different highlighting group. + +Exercises +--------- + +Think about why the `if exists` and `let` lines at the beginning and end of the +file are useful. If you can't figure it out, don't worry about it. I had to +ask Tim Pope to be sure. + +Skim over `:help syn-keyword`. Pay close attention to the part that mentions +`iskeyword`. + +Read `:help iskeyword`. + +Read `:help group-name` to get an idea of some common highlighting groups that +color scheme authors frequently use.