VimCoder User Manual

Download the latest version of VimCoder from the project page.

Intro

VimCoder is an editor plug-in for the  TopCoder Arena designed especially for  Vim users. It replaces the very limited built-in editor with Vim. This plug-in aims to be minimal in comparison to other editors such as  KawigiEdit or  CodeProcessor plug-in chains, though providing just enough functionality to actually be useful.

Requirements

You need  Vim installed. Duh. You should also make sure your copy of Vim was compiled with the client/server feature. If you are unsure, use Vim's :version command and look for "+clientserver" in the output. If you see "-clientserver" instead, that's a problem. I think this feature was introduced in Vim 6.x, but I haven't done any testing with any versions of Vim less than 7.2. If you're still on 6.x, you should really upgrade anyway.

You also need Java. If you can run the TC Arena applet, you're probably okay.

Install

Installation of VimCoder follows a similar or identical process to that of most other editor plug-ins. Unfortunately, there isn't really an automated way to do this, but the steps should be fairly straightforward.

1. Download the latest VimCoder jar file to wherever you'd like to store it.

2. Launch the TC Arena applet.

3. Click the "Options" menu and select "Editor" to show the editor preferences.

4. Click the "Add" button to bring up a new window for adding plug-ins.

5. In the "Name" field, type "Vim" or whatever you want. This is for your own reference when identifying the plug-in.

6. In the "EntryPoint" field, type "com.dogcows.VimCoder" without the quotes.

7. For the "ClassPath" field, click on "Browse" and locate the VimCoder jar file you downloaded in the first step.

8. Click "OK" to close the plug-in adding window.

9. Click "Save" in the editor preferences window, and close this window, too.

Configure

Depending on your preference or system attributes, you may want or need to first configure the plug-in so that it will work how you want it to. You can bring up the plug-in preferences window by following these steps:

1. Launch the TC Arena applet.

2. Click the "Options" menu and select "Editor."

3. In the new window, make sure the entry for VimCoder is selected from the list, and click the "Configure" button.

Storage Directory

VimCoder saves the problem files and the code you're working on in a particular directory you can set. By default, this directory is ".vimcoder" in your home directory. This is an "invisible" directory on most systems. Within this storage directory are several sub-directories, one for each problem you open. Each sub-directory is named after the problem identifier and contains your source code and other files related to the problem.

If you want to change the storage directory, click the "Browse" button in the VimCoder preferences window and navigate to the directory you would like to use. If you have already saved some problems to the previous storage directory, you may also want to actually move the directory to the new location so that VimCoder can find the work you've already done.

Vim Command

By default, VimCoder tries to invoke Vim using the "gvim" command (or "C:\WINDOWS\gvim.bat" on Windows). This will typically work just fine unless you don't have gvim in your PATH (or your installation of Vim on Windows didn't include the wrappers for the command line). If you get errors about the vim process not being able to run and no Vim session comes up when you use the VimCoder plug-in, you need to either make sure the Vim command exists in your PATH, or else change the Vim command in the VimCoder preferences window to something else. You may use an absolute path to your vim executable, such as:

/usr/local/bin/gvim

or

C:\Program Files\Vim\vim73\gvim.exe

or wherever your actual Vim executable is. You may also invoke vim through some other command:

roxterm -e vim

This example demonstrates using Vim without the GUI, running in a terminal. You can enter any elaborate command you want as long Vim ultimately gets executed with the arguments that will be appended to the command when it is invoked. After changing this value and saving your preferences, the command you enter will be used the next time you open a problem.

Usage

To use VimCoder once it is installed and configured, go to a room in the TC Arena applet and open one of the problems. If you have set VimCoder as your default editor, you will see the usual problem statement window come up as well as a Vim editor window. Otherwise, you can change the editor from the problem statement window, and the Vim editor window will come up. You will see that the area usually devoted to editor will be used for log messages; you will do your actual coding in the Vim window that comes up.

Tip: If you accidentally close your Vim session, you can get it back by switching to a different editor and then switching back to VimCoder. Alternatively, the session will also reappear if you switch languages.

Problem and Solution Files

What happens behind the scenes when you open a problem is that VimCoder will check to see if you have already opened that problem. If so, it will load your previous work. Otherwise, it will fill out the templates based on the problem class name, parameter types, and so on, and will create several files in a sub-directory of the main storage directory:

<class name>.<language>

This is the file where you write your code. If the class name for the problem was BinaryCode and your language was Java, the name of this file would be BinaryCode.java. When you open a problem, Vim will load this file into a new buffer so that you can start coding. If there is a template for the language you're using, that template will be used to fill in this file to give you a reasonable place to start. When you save your code to TC or compile remotely, this is also the file that will be read to provide the code for your solution.

testcases.txt

This file contains the example test cases that are associated with the problem. The format is pretty simple. For each test case, there is one line for the expected return value followed by each of the method parameters, each on its own line. This file typically read by the driver program (more on this later) in order to run the test cases against your code. While you are coding a solution, you may also want to add additional test cases to make sure your code is doing what you think it is and to make sure your code doesn't mess up on edge cases for which an example test case was not provided.

Problem.html

This file contains the problem statement which is what you see in the top half of the problem window. You can load this in a browser to read the particulars of the problem when you aren't running the TC applet. You typically shouldn't edit this file.

Makefile

If there exists a Makefile template for the selected language, it will also be filled out and saved in the problem directory. The purpose of the Makefile is to compile your code locally. Vim contains the command :make which you can use to interact with the Makefile. You also shouldn't need to edit this file directly. Exactly what happens when you use the :make command depends on the Makefile template.

If you are using the default Makefile template for C++, typing ":make" without any arguments will compile your code. Typing ":make run" will run all of the test cases against your code. Typing ":make test" will also run the test cases against your code, up until the first failed test at which point it will abort.

A default Makefile template is not yet provided for any other language, but you can write one yourself if you are so inclined.

driver.<language>

If there exists a driver template for the selected language, it will also be filled out and saved in the problem directory. If the language was currently set to C++, the driver code would be in the driver.cc file. You normally don't have to do anything with this file. It just provides supporting code for running the test cases against your code.

A default driver template is currently only provided for the C++ language. You could write your own template if you wanted to.

<class name>

Sometimes the TC Arena applet will pass back what source code it has saved. This will be saved in a file named after the class, without any file extension. You can open this file if you need to access this code for any reason (say, you messed up some code and need to revert back to the last time you saved from the TC Arena applet).

---

Once you come to a point that you want to compile your code on the TC servers or submit your solution, just save your file in Vim and use the normal buttons on the TC Arena problem statement window. The plug-in will read what you have saved to disk and send the file contents to the server.

Important: Make sure you understand the difference between compiling locally and compiling remotely (on the TC servers). If you use the Makefile to compile your solution (and maybe run the tests), you are not interacting with the TC Arena at all. When you compile remotely, you are sending a snapshot of your current solution to their servers for processing. The distinction becomes important when it comes time for you to submit your solution. When you push the "Submit" button, you are submitting the last version that was uploaded to the TC servers (i.e. by compiling remotely), and that may be different from what is currently in your Vim buffer. Therefore, it is critically important that you get into the habit of always pushing the "Compile" button right before you submit your code. This point can't be overemphasized.

Templates

VimCoder comes with default templates for C++ and Java, but you can create your own customized templates for any language supported by the TC Arena. To use your own template, you need to add a file to the storage directory with a file name depending on the language. The file should be named starting with the name of the language and ending with "Template" with no other file extension. For example, if you wanted to create a C# template and your storage directory was /home/foo/.topcoder, you would need to create the file /home/foo/.topcoder/C#Template.

A template is like a regular source code file with special keywords that will be replaced as the template is "filled out" whenever you open a new problem. Keywords are surrounded by two dollar signs so they're not confused with other parts of the source code. The template expansion process is rather simplistic, so if you can't get the right format for the terms you need, you might have to change the plug-in source code to get the effect you're trying to achieve. Here are the possible keywords and replacement terms:

$CLASSNAME$

This keyword is replaced by the name of the class you must use in your solution to the problem.

$METHODNAME$

This keyword is replaced by the name of the public method your class needs to have.

$RETURNTYPE$

This keyword is replaced by the type of the return variable of your public method.

$METHODPARAMS$

This keyword is replaced by a comma-separated list of method parameter types and names.

---

Other keywords are also available, but the rest are intended to be used in driver or Makefile templates. You can also create these templates by adding specially-named files to the storage directory. Driver templates are named starting with the name of the language and ending with "Driver" with no other file extension. Similarly, Makefile templates are named starting with the name of the language and ending with "Makefile" with no other file extension.

Drivers provide additional code to implement running the test cases. Currently, a default driver template is only provided for C++. Makefiles should have the commands needed to compile the solution source code and/or make a driver program that will perform the tests. Since there is only a driver template for C++, there is similarly only a default Makefile template provided for C++. If you want automatic building and testing for one of the other languages, you will need to create a driver and Makefile template for that language. Here are more keywords that may be useful for these types of templates:

$METHODPARAMDECLARES$

This keyword is replaced by C-style declarations of the method parameters. In other words, each parameter is declared with its type on its own line terminated by a semicolon.

$METHODPARAMNAMES$

This keyword is replaced by a comma-separated list of only the method parameter names.

$METHODPARAMSTREAMOUT$

This keyword is replaced by a list of the method parameter names separated by the C++ output stream operator (<<). The C++ driver template uses this to display the input values of the test case data.

$METHODPARAMSTREAMIN$

This keyword is replaced by a list of the method parameter names separated by the C++ input stream operator (>>). The C++ driver template uses this to read in the test case data from testcases.txt.

---

To give you an idea of how this all fits together, here is an example template for Java:

import static java.lang.Math.*;
import static java.math.BigInteger.*;
import static java.util.Arrays.*;
import static java.util.Collections.*;
import java.math.*;
import java.util.*;

public class $CLASSNAME$
{
        public $RETURNTYPE$ $METHODNAME$($METHODPARAMS$)
        {
        }
}

Problems/Solutions

Vim Settings Not Applied

The problem is that sometimes your settings (in vimrc) are not being applied as you would expect. This may be because you are using setlocal in your vimrc rather than set. The setlocal command applies settings only to the current buffer or window (see :help setlocal for more information), but VimCoder works by first launching Vim and then loading a brand new buffer.

The solution is to consider whether or not such settings should actually be global; if they should be global, change setlocal to set in your vimrc. Alternatively, if you want certain settings to be set only for certain kinds of buffers, you can use the autocmd command to selectively set settings according to file path pattern and various events. See :help autocmd for more information.

Conclusion

That's pretty much all there is to it. Feel free to send back bug reports and patches if you'd like. Happy Vimming!