dotfiles/vim/plugins/javacomplete/doc/javacomplete.txt

*javacomplete.txt*	For Vim version 7.0 and above. Last change: 2011-01-30

		    JAVACOMPLETE REFERENCE MANUAL	by cheng fang~
		    					fangread@yahoo.com.cn~


1. Overview					|javacomplete-overview|
   1.1 Features					|javacomplete-features|
   1.2 Requirements				|javacomplete-requirements|
   1.3 Download					|javacomplete-download|
   1.4 Install					|javacomplete-install|
2. Usage    					|javacomplete-usage|
   2.1 Input contexts				|javacomplete-contexts|
   2.2 Kind letter				|javacomplete-kindletter|
   2.3 Options					|javacomplete-options|
   2.4 Commands					|javacomplete-commands|
3. Java parser in Vim    			|javacomplete-parser|
   3.1 Abstract Syntax Tree			|javacomplete-ast|
   3.2 Global Constants				|javacomplete-constants|
   3.3 Parsing Functions			|javacomplete-functions|
   3.4 Sample					|javacomplete-sample|
4. FAQ						|javacomplete-faq|
5. Limitations					|javacomplete-limitations|
6. History					
   6.1 javacomplete				|javacomplete-history|
   6.2 Parser					|java-parser-history|
   6.2 Reflection.java				|javacomplete-reflection|
7. Todo						|javacomplete-todo|
8. Thanks					|javacomplete-thanks|

==============================================================================
1. Overview 					*javacomplete-overview*

This is javacomplete, an omni-completion script of JAVA language for vim 7 and
above. It includes javacomplete.vim, java_parser.vim, Reflection.java, and 
javacomplete.txt.

1.1 Features					*javacomplete-features*

- List members of a class, including (static) fields, (static) methods and ctors.
- List classes or subpackages of a package.
- Provide parameters information of a method, list all overload methods.
- Complete an incomplete word.
- Provide a complete JAVA parser written in Vim script language.
- Use the JVM to obtain most information.
- Use the embedded parser to obtain the class information from source files.
- Tags generated by ctags can also be used.
- JSP is supported, Builtin objects such as request, session can be recognized.
  The classes and jar files in the WEB-INF will be appended automatically to the classpath.

1.2 Requirements				*javacomplete-requirements*

It works on all the platforms wherever
- Vim version 7.0 and above,
- JDK version 1.1 and above, 
exists.

1.3 Download					*javacomplete-download*

You can download the lastest version from this url:
	http://www.vim.org/scripts/script.php?script_id=1785

1.4 Install					*javacomplete-install*

1. Unzip javacomplete.zip to a directory of 'runtimepath', e.g.
$HOME/.vim (unix/linux), $VIM/vimfiles (windows). >
	> unzip javacomplete.zip -d ~/.vim

<   To update Vim help tags, run vim and run command: >
	:helptags $HOME/.vim/doc
<   or >
	:helptags $VIM/vimfiles/doc

NOTE: javacomplete.vim, java_parser.vim and Reflection.java should be in one
autoload directory of 'runtimepath'.
javacomplete.txt should be in one doc directory of 'runtimepath'.

2. Set 'omnifunc' option. e.g. >
	:setlocal omnifunc=javacomplete#Complete
<   Or, use autocmd: >
	:" Only do this part when compiled with support for autocommands.
	:if has("autocmd")
	:  autocmd Filetype java setlocal omnifunc=javacomplete#Complete
	:endif
You can add this command to your .vimrc or _vimrc.

3. Set 'completefunc' option to show parameters information IF YOU LIKE. e.g. >
	:setlocal completefunc=javacomplete#CompleteParamsInfo
You can map as follows for better display: >
	:inoremap <buffer> <C-X><C-U> <C-X><C-U><C-P>
	:inoremap <buffer> <C-S-Space> <C-X><C-U><C-P>

4. Reflection.java will be automatcally compiled and placed to $HOME when you
use first time. Assure that Reflection.java is in the same directory with
javacomplete.vim to be searched in autoload subdirectory of &rtp. 
If no Reflection.class is generated, check that you have the write permission
in $HOME directory.
If a previous Reflection.java is not compatible with the new version
javacomplete.vim, please compile Reflection.java manually.

==============================================================================
2. Usage    					*javacomplete-usage*

You can use it like other omni-completion script. Many samples of input context 
are gived in the following section.

Make sure a JVM launcher (default 'java') can be searched in the PATH enviroment
variable, otherwise Use javacomplete#SetJVMLauncher() to specify one. See option
`javacomplete-launcher`.

See FAQ in time if some problem occurs. When meeting other problems not
described in FAQ, you can contact with the auther by the following e-mail:
fangread@yahoo.com.cn

2.1 Input contexts				|javacomplete-contexts|
It recognize nearly all kinds of Primary Expressions (see langspec-3.0)
except for "Primary.new Indentifier". Casting conversion is also supported.

Samples of input contexts are as following: (Note that '|' indicates cursor)
    (1). after '.', list members of a class or a package
    - package.| 	subpackages and classes of a package
    - Type.| 		static members of the 'Type' class and "class"
    - var.| or field.|	members of a variable or a field
    - method().| 	members of result of method()
    - this.|		members of the current class
    - ClassName.this.|	members of the qualified class
    - super.|		members of the super class
    - array.|		members of an array object
    - array[i].|	array access, return members of the element of array
    - "String".|	String literal, return members of java.lang.String
    - int.| or void.|	primitive type or pseudo-type, return "class"
    - int[].|		array type, return members of a array type and "class"
    - java.lang.String[].|
    - new int[].|	members of the new array instance
    - new java.lang.String[i=1][].|
    - new Type().|	members of the new class instance 
    - Type.class.|	class literal, return members of java.lang.Class
    - void.class.| or int.class.|
    - ((Type)var).|	cast var as Type, return members of Type.
    - (var.method()).|	same with "var.|"
    - (new Class()).|	same with "new Class().|"

   (2). after '(', list matching methods with parameters information.
    - method(|) 	methods matched
    - var.method(|) 	methods matched
    - new ClassName(|)	constructors matched
    - this(|) 		constructors of current class matched
    - super(|) 		constructors of super class matched
    Any place between '(' and ')' will be supported soon.
    Help information of javadoc is not supported yet.

   (3). after an incomplete word, list all the matched beginning with it.
    - var.ab| 	subset of members of var beginning with `ab`
    - ab|	list of all maybes

   (4). import statement
    - " import 	java.util.|"
    - " import 	java.ut|"
    - " import 	ja|"
    - " import 	java.lang.Character.|"	e.g. "Subset"
    - " import static java.lang.Math.|"	e.g. "PI, abs"

   (5). package declaration
    - " package 	com.|"

   The above are in simple expression.
   (6). after compound expression:
    - PrimaryExpr.var.|
    - PrimaryExpr.method().|
    - PrimaryExpr.method(|)
    - PrimaryExpr.var.ab|
    e.g.
    - "java.lang	. System.in .|"
    - "java.lang.System.getenv().|"
    - "int.class.toString().|"
    - "list.toArray().|"
    - "new ZipFile(path).|"
    - "new ZipFile(path).entries().|"

   (7). Nested expression:
    - "System.out.println( str.| )"
    - "System.out.println(str.charAt(| )"
    - "for (int i = 0; i < str.|; i++)"
    - "for ( Object o : a.getCollect| )"


2.2 Kind letter					*javacomplete-kindletter*

A single letter indicates the kind of compeltion item. These kinds are:
	+	ctor
	v	local variable or parameter
	f	nonstatic field
	F	static field
	m	nonstatic method
	M	static method
	P	package
	C	class type
	I	interface type

2.3 Options					*javacomplete-options*

1. Set java compiler (default 'javac') using the following function:
	javacomplete#SetCompiler('javac')	*javacomplete-compiler*

2. Set java launcher (default 'java') using the following function:
	javacomplete#SetJVMLauncher('java')	*javacomplete-launcher*

3. Set classpath using the following function: >
	javacomplete#AddClassPath('jarfile_or_classes_path')
	javacomplete#DelClassPath('jarfile_or_classes_path')
	javacomplete#SetClassPath('semicolon_separated_string')
<
    Another two variables will be used if they are existing:
	|g:java_classpath|	global classpath
	|b:classpath|		associated with current buffer
    In one sense, s:classpath is like a classpath option for a PROJECT.
    If some of them are body set, the priority of these variables is:
	first,  b:classpath first,
	second, s:classpath
	third,  g:java_classpath
	last,   $CLASSPATH

4. Set sourcepath using the following function: >
	javacomplete#AddSourcePath('sources_file_path')
	javacomplete#DelSourcePath('sources_file_path')
	javacomplete#SetSourcePath('sources_file_path')

5. Set option for using JDK1.1 if you meet the problem described in FAQ 3: >
	javacomplete#UseJDK11()

6. Set methods to search declaration: >
	" 1 - by builtin searchdecl(), quickest but inaccurate in many cases.
	" 2 - by special Searchdecl(), work NOT WELL YET.
	" 4 - by java_parser, slowest but accurate in most cases. Not for JSP.
	javacomplete#SetSearchdeclMethod()

2.4 Commands					*javacomplete-commands*

==============================================================================
3. Java parser in Vim    			*javacomplete-parser*

3.1 Abstract Syntax Tree			*javacomplete-ast*

3.2 Global Constants				*javacomplete-constants*

3.3 Parsing Functions				*javacomplete-functions*

3.4 Sample Codes					*javacomplete-sample*
This parser can be a good candidate for anyone who needs a java parser to get 
a abstract syntax tree for many use. The following are sample codes: >

  " NOTE: The script contains a single parser instance. You cannot create 
  " another parser! The only way to parse another JAVA code is reset the
  " parser by calling java_parser#InitParser().

  " 1. Initialize the parser
  " for a code snippet,
  call java_parser#InitParser(['for (int i = 0; i < N; i++) {', '', '}'])
  " or for the current buffer,
  call java_parser#InitParser(getline('^', '$'))
  " or for a whole source file
  call java_parser#InitParser(readfile('java/util/Arrays.java'))

  " 2. Get the result tree
  call java_parser#compilationUnit()
  " or others according to the input code
  call java_parser#expression()
  call java_parser#block()
  call java_parser#statement()

  " 3. Use the tree as you like

  " 4. The default scan strategy is scanning only sklenton. 
  " You can change it by set the option 'scanStrategy'.
  " The values for 'scanStrategy' option are:
  "	0 - only class members when parse full file; 
  "	1 - keep statement as a whole string; 
  "	2 - all 
  call java_parser#InitParser(getline('^', '$'), {'scanStrategy': 2})

  " 5. I recommend that keeping scanStrategy as default. 
  " If you want to parse a code snippet such as a method body of the whole
  " file, you can call java_parser#GotoPosition() to go to what you are going 
  " to start parsing.
  " Then, call java_parser#block(), java_parser#statement() or 
  " java_parser#expression() to parse the smaller snippet.
  " NOTE: This way will keep the result tree reserved.
  call java_parser#GotoPosition(def.body.pos)
  call java_parser#block()

==============================================================================
4. FAQ						*javacomplete-faq*

(1). When you meets the following problem: >
	omni-completion error: Exception in thread "main" 
	java.lang.NoClassDefFoundError: Reflection
It is Reflection.class not found in autoload directory or $HOME that cause
this problem.
There are several reasons causing this problem:
    o	No compiler. Use javacomplete#SetCompiler() to specify one.
    o	No write permission for $HOME directory.

(2). Reflection.java should be searched in autoload subdirectory of &rtp.
Reflection.class should be searched in $HOME or autoload subdirectory of &rtp.
If not found, javacomplete try to compile it and place the generated class
file in $HOME.

(3). A error when using JDK1.1:
    Unable to initialize threads: cannot find class java/lang/Thread
When I tested JDK1.1.8 on Windows XP, I found -classpath options cause it.
There are two way to avoid it is:
    o	Add the runtime classes to classpath, like
	"${JDK118}\classes;${JDK118}\lib\classes.zip;${JDK118}\lib\classes.jar;"
    o	Add Reflection.class and others to the CLASSPATH enviroment variable.
	And call javacomplete#UseJDK11() to set option.

==============================================================================
5. Limitations					*javacomplete-limitations*

The embedded parser works a bit slower than expected.

==============================================================================
6. History					

6.1 javacomplete				*javacomplete-history*

v0.77.1.2
    2011-01-30	Fixed to adapt globpath() (vim < 7.2). Patched by Sam Lidder.

v0.77.1.1
    2010-11-12	Fixed to ignore the 'suffixes' and 'wildignore' options which 
    		make Reflection.class can not be found.

v0.77.1
    2007-09-19	Supported showing method parameters information in any place
    		between parenthesises.

v0.77
    2007-09-19	bug fix
    2007-09-18	Added GetCurrentFileKey() avoid empty key of s:files for current buffer.
    2007-09-16	Use a new strategy for searching inherited members.
    2007-09-11
    -	Supported new contexts "jav|", "var|", just after an incomplete word.
    -	Supported new context "abs(|)", a imported static method.
    2007-09-10
    -	Improved FoundClassDeclaration()
    -	Fixed bug calling cursor(0, 0)
    2007-09-09	Rewrote DoGetClassInfo(), GetFQN() and IsFQN()<29><>
    2007-09-08	Fixed a bug when merging superclass's members
    2007-09-05 -- 07
    -	Improved s:MergeLines() and s:ExtractCleanExpr().
    -	Rewrote CompleteAfterDot(). Added ParseExpr(). Removed s:GetNextSubexprType()
    -	Supported accessible static imported members.
    -	Supported accessible inherited members.

    2007-09-04	Used b:changedtick and getftime() to check buffer (or other file) for changing.
    2007-09-01	Supported not-file-name toplevel or static member class in source files.

v0.76.8
    2007-08-30
    -	Created the s:TreeVisitor to search type or symbol names.
    -	Supported local and anonymous class.

    2007-08-29
    -	Supported appending automatically classpath under WEB-INF for jsp files.

v0.76.7
    2007-08-28
    -	Fixed case of "new java.util.zip.ZipFile().|"
    -	Improved process of type arguments and method parameters. JAVA5+
    -	Reorganize codes in javacomplete#Complete()
    -	Added CONTEXT_NEED_TYPE, removed CONTEXT_INCOMPLETE_WORD

    2007-08-24	Add Context types for type declaration: CONTEXT_NEED_TYPE

v0.76.6
    2007-08-23	Improved GetStatement() and related. Bug fixed.

v0.76.5
    2007-08-21
    -	Fixed bug: "foo().|", "getFoo().foo().|", 
	"for (Enumeration entries = ; entries.|; )".
    -	Supported input contexts: "((Object)o).|", "((Object)o).getClass().|",
	"new ZipFile(path).|", "(new String().)|".

v0.76.4
    2007-08-17
    -	Improved input contexts: "int.class.toString().|", "list.toArray().|".
    -	Fixed recognizing "this(|)", "method1(|)"
    -	Added the 'kind' letter to distinguish between classes and packages.
    2007-08-14
    -	Support accessible nested classes.
    -	Support import static members and import accessible nested classes.
    2007-08-11
    -	Fixed a bug when Reflection.java is in the path which contains space.
    -	Improved process of this and super in JSP.
    -	Fixed an severe bug parsing current jsp file.

v0.76.3
    2007-08-10
    -	Add an option 'searchdecl' set by javacomplete#SetSearchdeclMethod().
    -	Make an improvement for jsp file.
    -	Clear cache when set options affecting classpath.
    -	Improved DoGetPackageList() and s:GenerateImports().
    -	Replace codes searching list of string with index().

v0.76.2
    2007-08-08
    -	Fix failing to list members of nested class.
    -	Combine members of local packages and loadable packages.
    -	Add quick recognition of package or import. 
    2007-08-06	Add inherited fields and methods to local class.

v0.76.1
    2007-08-04
    -	Fix using a: in javacomplete#SetClassPath()
    -	Fix a bug in javacomplete#GetClassPath()

v0.76 2007-08-04
    2007-08-04
    -	Fix a infinite loop bug in s:GetMatchedIndexEx()
    -	Fix that array type not recognised in compound expression.
    -	Add a option for JDK1.1. See FAQ 3.
    2007-08-03
    -	Improve for 'this' or 'super'.
    -	Support searching toplevel class in sourcepath.
    -	Clean
    2007-08-02  
    -	Improve the process of checking a class in one of packages.
    2007-08-01
    -	Add Searchdecl() using java_parser.vim to provide quick information.
    -	Supports input context: "StringLiteral".|, "int.|", "void.|"
    2007-07-28
    -	Automatcally compile Reflection.java and place it to $HOME.
    -	Add option 'javacompiler', default 'javac'
    -	Add option 'java', default 'java'

v0.75 2007-02-13
    -	Add java_parser.vim.
    -	Add b:sourcepath option.
    -	Improve recognition of classes defined in current buffer or in source path.
    -	Support generating class information from tags instead of returning list directly.

v0.74 2007-02-03
    -	Support jre1.2 (and above).
    -	Support input context like "boolean.class.|"
    -	Handle java primitive types like 'int'.

v0.73 2007-02-01
    -	Fix bug that CLASSPATH not used when b:classpath or g:java_classpath not set.
    -	Fix bug that call filter() without making a copy for incomplete.
    -	Improve recognition of declaration of this class

v0.72 2007-01-31	Handle nested expression.
v0.71 2007-01-28	Add Basic support for class in current folder.
v0.70 2007-01-27	Complete the reflection part.
v0.60 2007-01-25	Design TClassInfo, etc.
v0.50 2007-01-21	Use java and Reflection.class directly.


6.2 Parser					*java-parser-history*

v0.67
    2007-09-11	Append a error string to imported qid when error occurs.
    2007-09-10	Improved regexp constants.
    2007-09-07	Fixed type2Str(). Removed qualident2Str(). 

v0.66.1	08-30	Changed classCreatorRest().
v0.66	08-27	Minor changes

v0.65
    2007-08-23
    -	Improved s:scanComment(), s:Strpart(), s:String2Flags().
    -	Improved recognizing methods, ctors, and variable declarators declared in most common form.
    -	Added s:optFinalParameter(), s:methodDeclaratorRest_opt(). 
    -	Removed s:GetLine() and s:GetCol().
    -	Rewrote binary functions.

v0.64
    2007-08-21
    -	Added quick recognizing fields or methods declared in most common form.
    -	Optimized code: s:modeAndEXPR(), formalParameter(), and others.

v0.63
    2007-08-10	
    -	Removed the unclear s:tokens and s:modifier_keywords.
    -	Add java_parser#GetSnapshot() and java_parser#Restore().
    2007-08-09	Fixed a bug when no top level class defined

v0.62 2007-08-08
    2007-08-08	Fix values in s:Flags and s:modifiersOpt() and the related.
    2007-08-07	Optimize code of scanDoubleQuote() and importDeclaration().

v0.61 2007-08-04
    2007-08-01 Fix a bug typetag(). return a:token -> return tolower(a:token)
    2007-07-31
    -	Rename all script functions matching "s:Java_\(\i\+\)" to "s:\1".
    -	Change s:EOI = ''
    -	Use get() instead of s:GetOption(). Remove it.
    -	Use repeat() instead of s:PrependChar(). Remove it.
    -	Improve scanChar()

v0.60 2007-07-31	Now it nearly is a complete parser and support Java5,6.
			And tested correctly on all java files in jdk6 src.zip.
    2007-07-19	Support new language features in java 5 and above.
    2007-07-25	Add supports for parsing statement, block or expression
    2007-07-28	Place it to autoload directory. 
    2007-07-30	Clean this script.

v0.51 2007-02-13	Optimize several scan function.
v0.50 2007-02-10	Complete the skeleton.


6.3 Reflection.java			*javacomplete-reflection*

v0.77
    2007-09-14	Improved generating information of all packages in jar files.
    2007-09-06	
    -	Improved getting paths of all system jar files for different JDKs 
	in different platforms.
    2007-08-14	Major improvement. Support nontoplevel classes.

v0.76.3
    2007-08-09	Redefined '-P' option for returning all packages and subpackages info in one time.

v0.76.2
    2007-08-06	Return a modifier value as a string because it more than 32bit.

v0.76
    2007-08-04	Support checking and reading package members for '-E'.
    2007-08-02
    -	Add an option '-E'.
    -	Use ZipFile and ZipEntry instead of JarFile and JarEntry,
	so that it can be compiled by and run on JDK1.1 and above.
v0.7  2007-02-17	

==============================================================================
7. Todo						*javacomplete-todo*

-  Improve performance of the embedded parser. Incremental parser.
-  Add quick information using balloonexpr, ballooneval, balloondelay.
-  Add javadoc
-  Give a hint for class name conflict in different packages.
-  Support parameter information for template

==============================================================================
8. Thanks					*javacomplete-thanks*
        * Bram Moolenaar and all Vim contributors for Vim
        * The insenvim project
        * The javac and gjc sources
        * All of you for using this script :)

        * For help, documentation, bug report :
	 	Martin Stubenschrott	author of IComplete
		Vissale NEANG		author of OmniCppComplete
		David Fishburn		author of SQLComplete and others
		Nico Weber		testing on the Mac
		Thomas Link		testing on cygwin+bash
		Zhixing Yu
	* For the bug of 'wildignore' options
		Rodrigo Rosenfeld Rosas
		Alexandru Mo?oi

FeedBack:
Any problem, bug or suggest are welcome to send to fangread@yahoo.com.cn

==============================================================================
 vim:tw=78:ts=8:ft=help:norl: