Add new stuff
This commit is contained in:
ViktorBarzin
parent
69661de82f
commit
07744f6823
333 changed files with 1989 additions and 6 deletions
|
|
@ -1,241 +0,0 @@
|
|||
*development-commands.html*
|
||||
|
||||
Commands
|
||||
********
|
||||
|
||||
For each eclipse feature that is exposed in eclim, there is a
|
||||
corresponding command on the daemon which handles calling the
|
||||
appropriate eclipse APIs and returning a result back to the client.
|
||||
This page will walk you through creating a simple command to
|
||||
familiarize you with the process.
|
||||
|
||||
|
||||
Creating a Command
|
||||
==================
|
||||
|
||||
Commands are simple classes which extend AbstractCommand and are
|
||||
registered using the @Command annotation. They then define an execute
|
||||
method which can return any object that can be serialized
|
||||
appropriately using gson (http://code.google.com/p/google-gson/).
|
||||
|
||||
Here is an example of a trivial command which returns a map of the
|
||||
arguments it was supplied, with the supplied project and file paths
|
||||
converted to absolute paths and the file byte offset converted to a
|
||||
character offset (eclim's vim function eclim#util#GetOffset() returns
|
||||
the offset in bytes since getting a character offset in vim with multi
|
||||
byte characters is less reliable, but most eclipse APIs expect
|
||||
character offsets):
|
||||
|
||||
Note: Eclim's source code is grouped by bundles (org.eclim,
|
||||
org.eclim.core, etc), each of which has java directory containing
|
||||
the java source code for that bundle.
|
||||
|
||||
>
|
||||
|
||||
package org.eclim.plugin.core.command.sample;
|
||||
|
||||
import java.util.HashMap;
|
||||
|
||||
import org.eclim.annotation.Command;
|
||||
|
||||
import org.eclim.command.CommandLine;
|
||||
import org.eclim.command.Options;
|
||||
|
||||
import org.eclim.plugin.core.command.AbstractCommand;
|
||||
|
||||
import org.eclim.plugin.core.util.ProjectUtils;
|
||||
|
||||
import org.eclipse.core.resources.IProject;
|
||||
|
||||
@Command(
|
||||
name = "echo",
|
||||
options =
|
||||
"REQUIRED p project ARG," +
|
||||
"REQUIRED f file ARG," +
|
||||
"REQUIRED o offset ARG," +
|
||||
"OPTIONAL e encoding ARG"
|
||||
)
|
||||
public class EchoCommand
|
||||
extends AbstractCommand
|
||||
{
|
||||
@Override
|
||||
public Object execute(CommandLine commandLine)
|
||||
throws Exception
|
||||
{
|
||||
String projectName = commandLine.getValue(Options.PROJECT_OPTION);
|
||||
String file = commandLine.getValue(Options.FILE_OPTION);
|
||||
|
||||
IProject project = ProjectUtils.getProject(projectName);
|
||||
|
||||
// translates client supplied byte offset to a character offset using the
|
||||
// 'project', 'file', 'offset', and 'encoding' command line args.
|
||||
int offset = getOffset(commandLine);
|
||||
|
||||
HashMap<String,Object> result = new HashMap<String,Object>();
|
||||
result.put("project", ProjectUtils.getPath(project));
|
||||
result.put("file", ProjectUtils.getFilePath(project, file));
|
||||
result.put("offset", offset);
|
||||
if (commandLine.hasOption(Options.ENCODING_OPTION)){
|
||||
result.put("encoding", commandLine.getValue(Options.ENCODING_OPTION));
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
}
|
||||
|
||||
<
|
||||
|
||||
|
||||
When registering the command with the @Command annotation, you give it
|
||||
a name and a comma separated list of options. Each option consists of
|
||||
4 parts in the form of:
|
||||
|
||||
>
|
||||
|
||||
REQUIRED|OPTIONAL s longname ARG|NOARG|ANY
|
||||
|
||||
<
|
||||
|
||||
|
||||
Where each part is defined as:
|
||||
|
||||
1. REQUIRED or OPTIONAL
|
||||
2. a single letter short name for the option
|
||||
3. a long name for the option
|
||||
4. whether the option requires an argument, no argument, or can
|
||||
have any number of additional arguments. In the case of ANY, you
|
||||
should only have one option with that value and when running the
|
||||
command from the command line, that option should be supplied last.
|
||||
That should give you the basics on what's involved with creating a new
|
||||
command, but the biggest hurdle for creating most commands is locating
|
||||
and deciphering the eclipse API calls that are necessary to implement
|
||||
the feature you want. Unfortunately most of the eclipse code that
|
||||
you'll need to hook into will most likely have little to no
|
||||
documentation so you're going to have to dig through the eclipse code.
|
||||
Eclim does provide a couple ant tasks to at least help you to quickly
|
||||
extract any docs or source code found in your eclipse install:
|
||||
|
||||
- eclipse.doc: This target will extract any doc jars from your
|
||||
eclipse install to a 'doc' directory in your eclipse home (or user
|
||||
local eclipse home).
|
||||
- eclipse.src: This target will extract any src jars from your
|
||||
eclipse install to a 'src' directory in your eclipse home (or user
|
||||
local eclipse home). If you download the sdk version of eclipse then
|
||||
the jdt and all the core eclipse source will be available. Some
|
||||
other plugins provide sdk versions which include the source code and
|
||||
this target can extract those as well, but some plugins don't seem
|
||||
to have this option when installing via eclipse's update manager
|
||||
(and may not include the source when installed from a system package
|
||||
manager). For those you can often download a zip version of their
|
||||
update site which should include source bundles. Once you've
|
||||
extracted that file, you can tell this target to extract source
|
||||
bundles from a specified directory. Here is an example of extracting
|
||||
the source from an unpacked dltk update site:
|
||||
>
|
||||
$ ant -Dsrc.dir=/home/ervandew/downloads/dltk-core-5.0.0/plugins eclipse.src
|
||||
|
||||
<
|
||||
|
||||
|
||||
Running a Command
|
||||
=================
|
||||
|
||||
Once you've created your command you then need to compile the code
|
||||
using eclim's ant build file. After you've done that you can then
|
||||
start eclimd and execute your command from the command line to test
|
||||
it:
|
||||
|
||||
>
|
||||
|
||||
$ eclim -pretty -command echo -p eclim -f org.eclim.core/plugin.properties -o 42 -e utf-8
|
||||
|
||||
<
|
||||
|
||||
|
||||
Note: As you are developing your commands, you can avoid restarting
|
||||
eclimd after every change by using eclim's reload command which will
|
||||
reload all of eclim's plugin bundles with the exception of
|
||||
org.eclim.core (so unfortunately it won't help with our example
|
||||
above if we put that command in the org.eclim.core bundle):>
|
||||
|
||||
$ eclim -command reload
|
||||
|
||||
<
|
||||
|
||||
|
||||
|
||||
Adding to Vim
|
||||
=============
|
||||
|
||||
Continuing with our echo command example, we can add the command to
|
||||
vim by first defining a new vim command in
|
||||
org.eclim.core/vim/eclim/plugin/eclim.vim:
|
||||
|
||||
Note: If the command should only be available for a specific file
|
||||
type, then you'd put it in a vim/eclim/ftplugin/somefiltetype.vim
|
||||
file instead.
|
||||
|
||||
>
|
||||
|
||||
command EclimEcho :call eclim#echo#Echo()
|
||||
|
||||
<
|
||||
|
||||
|
||||
Now that we've created the command, we then need to define our
|
||||
eclim#echo#Echo() function accordingly in
|
||||
org.eclim.core/vim/eclim/autoload/eclim/echo.vim:
|
||||
|
||||
>
|
||||
|
||||
" Script Variables {{{
|
||||
let s:echo_command =
|
||||
\ '-command echo -p "<project>" -f "<file>" ' .
|
||||
\ '-o <offset> -e <encoding>'
|
||||
" }}}
|
||||
|
||||
function! eclim#echo#Echo() " {{{
|
||||
if !eclim#project#util#IsCurrentFileInProject(0)
|
||||
return
|
||||
endif
|
||||
|
||||
let project = eclim#project#util#GetCurrentProjectName()
|
||||
let file = eclim#project#util#GetProjectRelativeFilePath()
|
||||
|
||||
let command = s:echo_command
|
||||
let command = substitute(command, '<project>', project, '')
|
||||
let command = substitute(command, '<file>', file, '')
|
||||
let command = substitute(command, '<offset>', eclim#util#GetOffset(), '')
|
||||
let command = substitute(command, '<encoding>', eclim#util#GetEncoding(), '')
|
||||
|
||||
let response = eclim#Execute(command)
|
||||
|
||||
" if we didn't get back a dict as expected, then there was probably a
|
||||
" failure in the command, which eclim#Execute will handle alerting the user
|
||||
" to.
|
||||
if type(response) != g:DICT_TYPE
|
||||
return
|
||||
endif
|
||||
|
||||
" simply print the response for the user.
|
||||
call eclim#util#Echo(string(response))
|
||||
endfunction " }}}
|
||||
|
||||
<
|
||||
|
||||
|
||||
And that's all there is to it. After re-building eclim, restarting
|
||||
eclimd, and restarting vim, you can now execute the command :EclimEcho
|
||||
to see the response printed in vim.
|
||||
|
||||
Now that you know the basics, you can explore the many existing eclim
|
||||
commands found in the eclim source code to see detailed examples of
|
||||
how to access various eclipse features to expose them for use in vim
|
||||
or the editor of your choice.
|
||||
|
||||
You should also take a look at the eclim Plugins (development-plugins)
|
||||
documentation which documents how to create a new eclim plugin,
|
||||
including information on adding new eclim settings, managing the
|
||||
plugin's dependencies through its META-INF/MANIFEST.MF, etc.
|
||||
|
||||
vim:ft=eclimhelp
|
||||
Loading…
Add table
Add a link
Reference in a new issue