# HG changeset patch # User Steve Losh # Date 1318478467 14400 # Node ID 93d00f94217aa4059fffe5092117d89b6db8797e # Parent 310f014b7beb5fb8e7ff762c56d9d8b7c265bfb3 Another chapter and some tweaks. diff -r 310f014b7beb -r 93d00f94217a chapters/00.markdown --- a/chapters/00.markdown Mon Oct 10 00:47:18 2011 -0400 +++ b/chapters/00.markdown Thu Oct 13 00:01:07 2011 -0400 @@ -4,18 +4,20 @@ To use this book you should have the latest version of Vim installed, which is version 7.3 at the time of this writing. New versions of Vim are almost always backwards-compatible, so everything in this book should work just fine with -newer versions. +anything after 7.3 too. -You should be comfortable editing files in Vim. You should know basic Vim -terminology like "buffer", "window", "normal mode", "insert mode" and "text -object". +You should be comfortable editing files in Vim. + +You should know basic Vim terminology like "buffer", "window", "normal mode", +"insert mode" and "text object". If you're not at that point yet go through the `vimtutor` program, use Vim exclusively for a month or two, and come back when you've got Vim burned into your fingers. You should have some programming experience. If you've never programmed before -check out [Learn Python the Hard Way](http://learnpythonthehardway.org/) first. +check out [Learn Python the Hard Way](http://learnpythonthehardway.org/) first +and come back to this book when you're done. Creating a Vimrc File --------------------- diff -r 310f014b7beb -r 93d00f94217a chapters/19.markdown --- a/chapters/19.markdown Mon Oct 10 00:47:18 2011 -0400 +++ b/chapters/19.markdown Thu Oct 13 00:01:07 2011 -0400 @@ -21,7 +21,8 @@ :echo foo Vim will display "42", because we've reassigned `bar` to the integer "42". From -this we can see that Vimscript is dynamically typed. +this it may seem that Vimscript is dynamically typed. That's not the case, but +we'll talk more about that later. Options as Variables -------------------- diff -r 310f014b7beb -r 93d00f94217a chapters/23.markdown --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/chapters/23.markdown Thu Oct 13 00:01:07 2011 -0400 @@ -0,0 +1,137 @@ +Functions +========= + +Like most programming languages, Vimscript has functions. Let's take a look at +how to create them, and then talk about some of their quirks. + +Run the following commands: + + :function meow() + +You might think this would start defining a functione named `Meow`. +Unfortunately this is not the case, and we've already run into one of +Vimscript's quirks. + +**Vimscript functions *must* start with a capital letter if they are unscoped!** + +Even if you *do* add a scope to a function (we'll talk about that in a bit) you +may as well capitalize the first letter of function names anyway. Most +Vimscript coders seem to do it, so don't break the convention. + +Okay, let's define a function for real this time. Run the following commands: + + :function Meow() + : echom "Meow!" + :endfunction + +This time Vim will happily define the function. Let's try running it: + + :call Meow() + +Vim will display "Meow!" as expected. + +Let's try returning a value. Run the following commands: + + :function GetMeow() + : return "Meow String!" + :endfunction + +Now try it out by running this command: + + :echom GetMeow() + +Vim will call the function and give the result to `echom`, which will display +"Meow String!". + +Calling Functions +----------------- + +We can already see that there are two different ways of calling functions in +Vimscript. + +When you want to call a function directly you use the `call` command. Run the +following commands: + + :call Meow() + :call GetMeow() + +The first will display "Meow!" but the second doesn't display anything. The +return value is thrown away when you use `call`, so this is only useful when the +function has side effects. + +The second way to call functions is in expressions. You don't need to use +`call` in this case, you can just name the function. Run the following command: + + :echom GetMeow() + +As we saw before, this calls `GetMeow` and passes the return value to `echom`. + +Implicit Returning +------------------ + +Run the following command: + + :echom Meow() + +This will display two lines: "Meow!" and "0". The first obviously comes from +the `echom` inside of `Meow`. The second shows us that if a Vimscript function +doesn't return a value, it implicitly return `0`. Let's use this to our +advantage. Run the following commands: + + :function TextwidthIsTooWide() + : if &l:numberwidth ># 80 + : return 1 + : endif + :endfunction + +This function uses a lot of important concepts we've seen before: + +* `if` statements +* Treating options as variables +* Localizing those option variables +* Case-sensitive comparisons + +If any of those sound unfamiliar you should go back a few chapters and read +about them. + +We've now defined a function that will tell us if the `textwidth` setting is +"too wide" in the current buffer (because 80 characters is, of course, the +correct width for anything but HTML). + +Let's try using it. Run the following commands: + + :set textwidth=80 + :if TextwidthIsTooWide() + : echom "WARNING: Wide text!" + :endif + +What did we do here? + +* First we set the `textwidth` globally to `80`. +* The we ran an if statement that checked if `TextwidthIsTooWide()` was truthy. +* This wound up not being the case, so the `if`'s body wasn't executed. + +Because we never explicitly returned a value, Vim returned `0` from the +function, which is falsy. Let's try changing that. Run the following commands: + + :setlocal textwidth=100 + :if TextwidthIsTooWide() + : echom "WARNING: Wide text!" + :endif + +This time the `if` statement in the function executes its body, returns `1`, and +so the `if` we manually typed in executes *its* body. + +Exercises +--------- + +Read `:help call`. Ignore anything about "ranges" for now. How many arguments +can you pass to a function? Is this surprising? + +Read the first paragraph of `:help E124` and find out what characters you're +allowed to use in function names. Are underscores okay? Dashes? Accented +characters? Unicode characters? If it's not clear from the documentation just +try them out. + +Read `:help return`. What's the "short form" of that command (which I told you +to never use)? Is it what you expected? If not, why not? diff -r 310f014b7beb -r 93d00f94217a introduction.markdown --- a/introduction.markdown Mon Oct 10 00:47:18 2011 -0400 +++ b/introduction.markdown Thu Oct 13 00:01:07 2011 -0400 @@ -4,7 +4,7 @@ Before reading this book you should be comfortable using Vim and know what terms like "buffer", "window" and "insert mode" mean. -The book is divided into three sections: +LVSTHW is divided into three sections: * The first covers basic Vim commands that you can use in your `~/.vimrc` file to customize Vim quickly and easily. @@ -13,6 +13,11 @@ * The third walks through the creation of a sample plugin intended for distribution to other Vim users. +Currently the book is a work in progress. Once it's finished you'll be able to +buy ebook and possibly hard copy versions. If you want to get on the mailing +list to know when it's officially completed you can sign up at [Learn Vimscript +the Hard Way on Leanpub][leanpub]. + The book is [copyright][license] 2011 by Steve Losh, all rights reserved. You can redistribute it as long as you don't make any changes and don't charge for it. @@ -26,3 +31,4 @@ [hg]: http://bitbucket.org/sjl/learnvimscriptthehardway/ [git]: http://github.com/sjl/learnvimscriptthehardway/ [license]: /license.html +[leanpub]: http://leanpub.com/learnvimscriptthehardway diff -r 310f014b7beb -r 93d00f94217a outline.org --- a/outline.org Mon Oct 10 00:47:18 2011 -0400 +++ b/outline.org Thu Oct 13 00:01:07 2011 -0400 @@ -22,7 +22,8 @@ ** DONE variable scopes ** DONE conditionals ** DONE comparisons -** TODO functions +** DONE functions +** TODO function scoping ** TODO function varargs ** TODO functions (more) ** TODO strings @@ -34,6 +35,7 @@ ** TODO looping ** TODO dictionaries ** TODO paths +** TODO exceptions ** TODO command! * part 3 - creating a full plugin ** TODO intro and plugin layout diff -r 310f014b7beb -r 93d00f94217a preface.markdown --- a/preface.markdown Mon Oct 10 00:47:18 2011 -0400 +++ b/preface.markdown Thu Oct 13 00:01:07 2011 -0400 @@ -35,15 +35,23 @@ understanding it straight away. If so: it doesn't matter. Learning Vim and Vimscript is a different experience from learning a normal programming language. -**Type. In. The. Exercises.** +**Type in *all* the commands.** + +**Do *all* the exercises.** -First, Vimscript is old and has a lot of dusty corners and twisty hallways. One -configuration option can change how the entire language works. By typing -*every* command in *every* exercise you'll discover problems with your Vim build -or configuration on the simpler commands, which will be easier to diagnose and -fix. +Vimscript is old and has a lot of dusty corners and twisty hallways. One +configuration option can change how the entire language works. + +By typing *every* command in *every* lesson exercise and doing *every* exercise +you'll discover problems with your Vim build or configuration on the simpler +commands, which will be easier to diagnose and fix. Second, Vimscript *is* Vim. To save a file in Vim, you type `:write` (or `:w` for short) and press return. To save a file in a Vimscript, you use `write`. Mastering a text editor means developing muscle memory, which you simply can't get from just reading. + +I hope you'll find this book useful. It's *not* meant to be a comprehensive +guide to Vimscript. It's meant to get you comfortable enough with the language +to read other people's code (with regular side-trips to `:help`) and recognize +some common pitfalls.