--- 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
---------------------
--- 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
--------------------
--- /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?
--- 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
--- 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
--- 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.