+
+Vim + TopCoder = VimCoder
+=========================
+
+
+
+This plug-in makes it easy to use [Vim](http://www.vim.org/) as your
+text editor in the [TopCoder Competition Arena](http://topcoder.com/tc).
+It aims to be minimal in comparison to other editors such as
+[KawigiEdit](http://topcoder.yajags.com/) or
+[CodeProcessor](http://www.topcoder.com/tc?module=Static&d1=applet&d2=plugins)
+plug-in chains while also providing enough functionality to also be useful.
+
+### Features
+
+* Works on any platform that the TopCoder Arena applet itself supports.
+* Works with any language supported by TopCoder.
+* Keeps track of your code files locally so you always have a copy.
+* Downloads and stores a copy of the problem statement with your code for
+ off-line viewing.
+* Has support for simple templates (default templates provided only for C++
+ and Java).
+* Test-case "drivers" can be generated locally with the example test-case data
+ (currently C++ only).
+
+### License
+
+This software is licensed according to the terms and conditions of the
+[BSD 2-Clause License](http://www.opensource.org/licenses/bsd-license.php).
+Please see the COPYING file for more information.
+This project is neither supported nor endorsed by TopCoder, Inc.
+
+### Download
+
+The latest VimCoder jar files can be downloaded from
+[this FTP server](ftp://ftp.brokenzipper.com/pub/vimcoder/).
+
+### Install
+
+Unfortunately, installation is a bit cumbersome, but it is what it is:
+
+1. Download the latest version of the VimCoder jar file.
+2. Run the TopCoder Arena applet and log in.
+3. Click the "Options" menu and select "Editor" to show the editor
+ preferences.
+4. Click the "Add" button to bring up a new window.
+5. For "Name," type "Vim" or whatever you want to represent this plug-in.
+6. For "EntryPoint," type "com.dogcows.VimCoder" without the quotes.
+7. For "ClassPath," click on "Browse" and locate the VimCoder jar file. The
+ third field should now have the path to the jar file.
+8. Click "OK" to close the window with the three fields.
+9. Click "Save."
+
+You should now be able select "Vim" (or whatever you entered the first
+field) as your editor from the pull-down list on any problem statement
+window.
+
+### 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. Run the TopCoder Arena applet and log in.
+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 (e.g. `xterm -e vim`).
+
+The xterm example demonstrates using Vim without the GUI, running in
+a terminal emulator. 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
+TopCoder 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.
+
+Just enter your code into the Vim window and use the regular TopCoder Arena
+applet buttons to compiled, test, and submit your code.
+
+**Pro 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
+
+Knowing about the files created by VimCoder is useful if you ever need to do
+anything advanced with VimCoder.
+
+When you open a problem, VimCoder will check to see if you have already opened
+that problem by looking for the problem and solution files. If these files
+are found, 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:
+
+##### `$CLASSNAME$`.`$LANGUAGE$`
+
+This is the file where you write your solution 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 TopCoder 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 TopCoder Arena 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 Makefile template is not yet provided for any other language, but you can
+write one yourself if you are so inclined. Read on to learn how templates
+work.
+
+**Important:** Make sure you understand the difference between compiling
+locally and compiling remotely (on the TopCoder servers). If you use the
+Makefile to compile your solution (and maybe run the tests), you are not
+interacting with the TopCoder servers at all. When you compile *remotely*,
+you are sending a snapshot of your current solution to the 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 TopCoder servers** (by compiling
+remotely), and that may be different from what is currently in your Vim
+buffer, even if your Vim buffer was saved to disk. Therefore, it is very
+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.
+
+##### 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.
+
+##### `$CLASSNAME$`
+
+Sometimes the TopCoder 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 TopCoder Arena applet).
+
+### Templates
+
+VimCoder comes with default templates for C++ and Java, but you can create
+your own customized templates for any language supported by TopCoder. 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 name should start with the name of
+the language and end 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:
+
+```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$) {
+ }
+}
+```
+
+Something like this should be saved in a filed named `JavaTemplate` in your
+VimCoder storage directory.
+
+### Gotchas
+
+##### Vim Client/Server
+
+VimCoder requires Vim's client/server feature in order to work. If the log is
+showing errors with the invocation of Vim or if it's just not working and has
+other strange symptoms, make sure your version of Vim supports 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,
+then you'll need to get yourself another version of Vim.
+
+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.
+
+##### Vim Settings Not Applied
+
+The problem is that sometimes your settings (in your vimrc file) are not being
+applied as you would expect. This may be because you are using `setlocal` in
+your vimrc file 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
+file. 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.
+
projects / chaz / vimcoder / commitdiff
