2 Vim + TopCoder = VimCoder
3 =========================
5 ![VimCoder Logo](http://chazmcgarvey.github.com/vimcoder/img/vimcoder.png)
7 This plug-in makes it easy to use [Vim](http://www.vim.org/) as your
8 text editor in the [TopCoder Competition Arena](http://topcoder.com/tc).
9 It aims to be minimal in comparison to other editors such as
10 [KawigiEdit](http://topcoder.yajags.com/) or
11 [CodeProcessor](http://www.topcoder.com/tc?module=Static&d1=applet&d2=plugins)
12 plug-in chains while also providing enough functionality to also be useful.
17 * Works on any platform that the TopCoder Arena applet itself supports.
18 * Works with any language supported by TopCoder.
19 * Keeps track of your code files locally so you always have a copy.
20 * Downloads and stores a copy of the problem statement with your code for
22 * Has support for simple templates (default templates provided only for C++
24 * Test-case "drivers" can be generated locally with the example test-case data
30 This software is licensed according to the terms and conditions of the
31 [BSD 2-Clause License](http://www.opensource.org/licenses/bsd-license.php).
32 Please see the COPYING file for more information.
33 This project is neither supported nor endorsed by TopCoder, Inc.
38 The latest VimCoder jar file can be downloaded from the
39 [vim.org script page](http://www.vim.org/scripts/script.php?script_id=3321).
44 Unfortunately, installation is a bit cumbersome, but it is what it is:
46 1. Download the latest version of the VimCoder jar file.
47 2. Run the TopCoder Arena applet and log in.
48 3. Click the "Options" menu and select "Editor" to show the editor
50 4. Click the "Add" button to bring up a new window.
51 5. For "Name," type "Vim" or whatever you want to represent this plug-in.
52 6. For "EntryPoint," type "com.dogcows.VimCoder" without the quotes.
53 7. For "ClassPath," click on "Browse" and locate the VimCoder jar file. The
54 third field should now have the path to the jar file.
55 8. Click "OK" to close the window with the three fields.
58 You should now be able select "Vim" (or whatever you entered into the first
59 field) as your editor from the pull-down list on any problem statement window.
64 Depending on your preference or system attributes, you may want or need to
65 first configure the plug-in so that it will work how you want it to. You can
66 bring up the plug-in preferences window by following these steps:
68 1. Run the TopCoder Arena applet and log in.
69 2. Click the "Options" menu and select "Editor."
70 3. In the new window, make sure the entry for VimCoder is selected from the
71 list, and click the "Configure" button.
73 ![VimCoder Preferences](http://chazmcgarvey.github.com/vimcoder/img/prefs.png)
75 ##### Storage Directory
77 VimCoder saves the problem files and the code you're working on in
78 a particular directory you can set. By default, this directory is `.vimcoder`
79 in your home directory. This is an "invisible" directory on most systems.
80 Within this storage directory are several sub-directories, one for each
81 problem you open. Each sub-directory is named after the problem identifier
82 and contains your source code and other files related to the problem.
84 If you want to change the storage directory, click the "Browse" button in the
85 VimCoder preferences window and navigate to the directory you would like to
86 use. If you have already saved some problems to the previous storage
87 directory, you may also want to actually move the directory to the new
88 location so that VimCoder can find the work you've already done.
92 By default, VimCoder tries to invoke Vim using the `gvim` command (or
93 `C:\WINDOWS\gvim.bat` on Windows). This will typically work just fine unless
94 you don't have gvim in your PATH (or your installation of Vim on Windows
95 didn't include the wrappers for the command line). If you get errors about
96 the vim process not being able to run and no Vim session comes up when you use
97 the VimCoder plug-in, you need to either make sure the Vim command exists in
98 your PATH, or else change the Vim command in the VimCoder preferences window
101 You may use an absolute path to your vim executable, such as
102 `/usr/local/bin/gvim` or `C:\Program Files\Vim\vim73\gvim.exe`
103 or wherever your actual Vim executable is. You may also invoke vim through
104 some other command (e.g. `xterm -e vim`).
106 The xterm example above demonstrates using Vim without the GUI, running in
107 a terminal emulator. You can enter any elaborate command you want as long as
108 Vim ultimately gets executed with the arguments that will be appended to the
109 command when it is invoked. After changing this value and saving your
110 preferences, the command you enter will be used the next time you open
116 To use VimCoder once it is installed and configured, go to a room in the
117 TopCoder Arena applet and open one of the problems. If you have set VimCoder
118 as your default editor, you will see the usual problem statement window come
119 up as well as a separate Vim editor window. Otherwise, you can change the
120 editor from the problem statement window, and the Vim editor window will come
121 up. You will see that the area usually devoted to editor will be used for log
122 messages; you will do your actual coding in the Vim window that comes up.
124 Just enter your code into the Vim window and use the regular TopCoder Arena
125 applet buttons to compile, test, and submit your code.
127 **Pro Tip:** If you accidentally close your Vim session, you can get it back
128 by switching to a different editor (such as the default editor) and then
129 switching back to VimCoder. Alternatively, the session will also reappear
130 (and load a buffer to a different source code file) if you switch languages.
132 Storage Directory Structure
133 ---------------------------
135 Knowing about the files created by VimCoder is useful if you ever need to do
136 anything advanced. When you open a problem, VimCoder will check to see if you
137 have already opened that problem by looking for the problem and solution
138 files. If these files are found, it will load your previous work. Otherwise,
139 it will fill out the templates based on the problem class name, parameter
140 types, and so on, and will create several files in a sub-directory of the main
143 ##### `$CLASSNAME$`.`$LANGUAGE$`
145 This is the file where you write your solution code. If the class name for
146 the problem was BinaryCode and your language was Java, the name of this file
147 would be `BinaryCode.java`. When you open a problem, Vim will load this file
148 into a new buffer so that you can start coding. If there is a template for
149 the language you're using, that template will be used to fill in this file to
150 give you a reasonable place to start. When you save your code to TopCoder or
151 compile remotely, this is also the file that will be read to provide the code
156 This file contains the example test cases that are associated with the
157 problem. The format is pretty simple. For each test case, there is one line
158 for the expected return value followed by the inputs (i.e. the method
159 arguments), in order, each on its own line. The format of this file is meant
160 to be easy for a human to write and easy for a program to read so that
161 a driver program (more on this later) can easily be written to run the test
162 cases against your code.
164 While you are coding a solution, you may want to open this file in a new
165 buffer (type ":e testcases.txt") and add additional test cases to make sure
166 your code doesn't mess up on edge cases for which an example test case was not
171 This file contains the problem statement which is what you see in the top half
172 of the problem window. You can load this in a browser to read the particulars
173 of the problem when you aren't running the TopCoder Arena applet. You
174 typically shouldn't edit this file, but it's up to you.
178 If there exists a Makefile template for the selected language, it will also be
179 filled out and saved in the problem directory. The purpose of the Makefile is
180 to compile your code locally. You can execute targets in the Makefile using
181 Vim's `:make` command. You also shouldn't need to edit this file directly,
182 but of course you can if the need does arise. Exactly what happens when you
183 use the `:make` command depends on the Makefile template.
185 If you are using the default Makefile template for C++, typing ":make" without
186 any arguments will compile your code. Typing ":make run" will run all of the
187 test cases against your code. Typing ":make test" will also run the test
188 cases against your code, except it will abort at the first failed test.
190 A Makefile template is not yet provided for any other language, but you can
191 write one yourself if you are so inclined. Read on to learn how templates
194 **Important:** Make sure you understand the difference between compiling
195 locally and compiling remotely (on the TopCoder servers). If you use the
196 Makefile to compile your solution (and maybe run the tests), you are not
197 interacting with the TopCoder servers at all. When you compile *remotely*,
198 you are sending a snapshot of your current solution to the servers for
199 processing. The distinction becomes important when it comes time for you to
200 submit your solution. When you push the "Submit" button, you are submitting
201 the **last version that was uploaded to the TopCoder servers** (by compiling
202 remotely), and that may be different from what is currently in your Vim
203 buffer, even if your Vim buffer was saved to disk. Therefore, it is very
204 important that you get into the habit of always pushing the "Compile" button
205 right before you submit your code. This point can't be overemphasized.
207 ##### driver.`$LANGUAGE$`
209 If there exists a driver template for the selected language, it will also be
210 filled out and saved in the problem directory. If the language was currently
211 set to C++, the driver code would be in the driver.cc file. You normally
212 don't have to do anything with this file. It just provides supporting code
213 for running the test cases against your code.
215 The driver should output TAP (Test Anything Protocol) so that tests can be run
216 in a test harness such as [prove](http://search.cpan.org/perldoc?prove). The
217 default Makefile template has a `prove` target (type ":make prove") that can
218 run the tests in a test harness; the test harness is `prove` unless otherwise
219 configured. TAP output is also very human-readable all by itself, so having
220 a test harness isn't really required.
222 A default driver template is currently only provided for the C++ language.
223 You could write your own template if you wanted to.
227 Sometimes the TopCoder Arena applet will pass back what source code it has
228 saved. This will be saved in a file named after the class, without any file
229 extension. You can open this file if you need to access this code for any
230 reason (say, you messed up some code and need to revert back to the last time
231 you saved from the TopCoder Arena applet).
236 VimCoder comes with default templates for C++ and Java, but you can create
237 your own customized templates for any language supported by TopCoder. To use
238 your own template, you need to add a file to the storage directory with a file
239 name depending on the language. The file name should start with the name of
240 the language and end with "Template" with no file extension. For example, if
241 you wanted to create a C# template and your storage directory was
242 `/home/foo/.topcoder`, you would need to create the file
243 `/home/foo/.topcoder/C#Template`.
245 A template is like a regular source code file with special keywords that will
246 be replaced as the template is "filled out" whenever you open a new problem.
247 Keywords are surrounded by two dollar signs so they're not confused with other
248 parts of the source code. The template expansion process is rather
249 simplistic, so if you can't get the right format for the terms you need, you
250 might have to change the plug-in source code to get the effect you're trying
251 to achieve. Here are the possible keywords and replacement terms:
255 This keyword is replaced by the name of the class you must use in your
256 solution to the problem.
260 This keyword is replaced by the name of the public method your class needs to
265 This keyword is replaced by the type of the return variable of your public
268 ##### `$METHODPARAMS$`
270 This keyword is replaced by a comma-separated list of method parameter types
275 Other keywords are also available, but the rest are intended to be used in
276 driver or Makefile templates, though any keyword can be used in any type of
277 template. You can create other types of templates by adding specially-named
278 files to the storage directory. Driver templates are named starting with the
279 name of the language and ending with "Driver" with no file extension.
280 Similarly, Makefile templates are named starting with the name of the language
281 and ending with "Makefile" with no file extension.
283 Drivers provide additional code that allows the test cases to be run against
284 your solution. Currently, Makefile and driver templates are only provided for
285 the C++ language. Makefiles should have the commands needed to compile the
286 solution source code and/or make a driver program that will perform the tests.
287 If you want automatic building and testing for one of the other languages, you
288 will need to create a driver and Makefile template for that language. Here
289 are more keywords that may be useful for these types of templates:
291 ##### `$METHODPARAMDECLARES$`
293 This keyword is replaced by C-style declarations of the method parameters. In
294 other words, each parameter is declared with its type on its own line
295 terminated by a semicolon.
297 ##### `$METHODPARAMNAMES$`
299 This keyword is replaced by a comma-separated list of only the method
302 ##### `$METHODPARAMSTREAMOUT$`
304 This keyword is replaced by a list of the method parameter names separated by
305 the C++ output stream operator (<<). The C++ driver template uses this to
306 display the input values of the test case data.
308 ##### `$METHODPARAMSTREAMIN$`
310 This keyword is replaced by a list of the method parameter names separated by
311 the C++ input stream operator (>>). The C++ driver template uses this to read
312 in the test case data from testcases.txt.
316 To give you an idea of how this all fits together, here is an example template
317 for Java, similar to the built-in default Java template:
320 import static java.lang.Math.*;
321 import static java.math.BigInteger.*;
322 import static java.util.Arrays.*;
323 import static java.util.Collections.*;
327 public class $CLASSNAME$ {
328 public $RETURNTYPE$ $METHODNAME$($METHODPARAMS$) {
333 Notice that it looks just like regular code but has some keywords surrounded
334 by dollar signs that will be expanded to real values. Something like this
335 could be saved in a filed named `JavaTemplate` in your VimCoder storage
341 ##### Vim Client/Server
343 VimCoder requires Vim's client/server feature in order to work. If the log is
344 showing errors with the invocation of Vim or if it's just not working and has
345 other strange symptoms, make sure your version of Vim supports the
346 client/server feature. If you are unsure, use Vim's `:version` command and
347 look for "+clientserver" in the output. If you see "-clientserver" instead,
348 then you'll need to get yourself another version of Vim.
350 I think this feature was introduced in Vim 6.x, but I haven't done any testing
351 with any versions of Vim less than 7.2. If you're still on 6.x, you should
352 really upgrade anyway.
354 ##### Vim Settings Not Applied
356 The problem is that sometimes your settings (in your vimrc file) are not being
357 applied as you would expect. This may be because you are using `setlocal` in
358 your vimrc file rather than `set`. The `setlocal` command applies settings
359 only to the current buffer or window (see `:help setlocal` for more
360 information), but VimCoder works by first launching Vim and then loading
363 The solution is to consider whether or not such settings should actually be
364 global; if they should be global, change `setlocal` to `set` in your vimrc
365 file. Alternatively, if you want certain settings to be set only for certain
366 kinds of buffers, you can use the `autocmd` command to selectively set
367 settings according to file path pattern and various events.
368 See `:help autocmd` for more information.