= Valencia =
Valencia is a plugin that turns gedit into a lightweight IDE for Vala.  The Valencia [http://yorba.org/valencia Web page] gives a brief overview of Valencia and its capabilities.  This Wiki page has complete documentation on using Valencia.

Mailing list: Send a message with a subject: of `subscribe` to [mailto:valencia-request@lists.yorba.org] or go to http://lists.yorba.org/cgi-bin/mailman/listinfo/valencia.

== Building and installing ==
To build Valencia, you'll need to have the following programs and libraries installed:

 * [http://live.gnome.org/Vala valac], the Vala compiler.
   * Valencia depends on the valac libraries for system vapi directory information; if valac is not installed, Valencia may not function correctly!
 * [http://gedit.org gedit]
 * [http://ftp.gnome.org/pub/GNOME/sources/vte/ libvte]

On Ubuntu (and perhaps Debian), you can install the required build dependencies like this:

{{{
sudo apt-get install valac libvala-dev gedit-dev libgee-dev libvte-dev
}}}
You can download the latest source release at [http://yorba.org/download/valencia/0.3/valencia-0.3.0.tar.bz2 valencia-0.3.0.tar.bz2] .  Or check out the latest code (possibly unstable) at `svn://svn.yorba.org/valencia/trunk`.  Then run `make` and `make install`.  (Do ''not'' run `sudo make install`.  Valencia installs in your ~/.gnome2/gedit directory, and if you install as root the permissions will be wrong.)

To enable Valencia in gedit, go to '''Edit ▸ Preferences ▸ Plugins''' and check the Valencia checkbox.

== Using Valencia ==
=== Jumping to symbols ===
To jump to the definition of any symbol in your project, place the cursor on the symbol name and choose '''Search ▸ Go to Definition''' or press '''F12'''. Valencia will jump to the position where the symbol is defined. Valencia can jump to variables, fields, methods, classes, interfaces and namespaces. Symbol jumping is context sensitive: if you place the cursor on the word `bar` in the expression `foo.bar()` and choose '''Go To Definition''', Valencia will find the appropriate implementation of `bar()` for the object `foo`.  After jumping to a symbol, you can browse backward and forward up to the most recent symbol to which you have jumped via the '''Search ▸ Go Back''' and '''Search ▸ Go Forward''' commands ('''Alt+Left''' and '''Alt+Right''').

The first time you jump to a symbol definition in a large Vala project (such as the valac compiler sources), Valencia will display a progress dialog as it indexes Vala source files.  All subsequent symbol jumps should be fast.

Valencia parses system vapi files such as glib.vapi and gtk.vapi, allowing you to jump to symbols defined in any vapi file defined in the default system directory.

When Valencia is enabled, the gedit status bar displays the class name containing the current cursor position.  This can help you tell you what class you've ended up in after jumping to a symbol definition.

The '''Search ▸ Go to Outer Scope''' command ('''Ctrl+F12''') jumps to the method containing the cursor position.  If the cursor is not inside a method, this command jumps to the class containing the cursor position.  So you can run this command once to jump to the enclosing method, and then again to jump to its enclosing class.

Valencia includes a symbol browser pane in the gedit sidebar.  The symbol browser lists only symbols in your project. It looks within local namespaces to find all top-level symbols, and does not include symbols found within scopes other than namespaces (e.g. methods or fields found in classes). To see the symbol browser pane, choose '''View ▸ Side Pane''', then click the magnifying class icon tab at the bottom of the sidebar. To search for a symbol, choose '''Search ▸ Find Symbol...''' or press '''Ctrl+Alt+S''' to go to the search entry box, where you can type the name of the symbol which you want to find.

=== Tooltips and Autocomplete ===
Both tooltips and autocomplete use the same menu item ('''Search ▸ !AutoComplete''') and shortcut key ('''Ctrl+Space'''). These features are context-sensitive and must be invoked manually to be used. You can cancel a tooltip or autocomplete dialog any time by pressing escape when it is on the screen. When trying to invoke autocomplete, sometimes the cursor may be in the context to get a tooltip. Simply invoke autocomplete again and a list will appear.

To see a tooltip for any method within the project, place the cursor anywhere within a method call after the opening parenthesis, and invoke autocomplete. To get an autocompletion list for an incomplete symbol, invoke autocomplete when the cursor is at the end of the symbol. If the cursor is inside a symbol, it will attempt to get an autocompletion list for the partial symbol before the cursor. Invoking autocomplete at an empty space will bring up a list of all members of the global and using namespaces. You can scroll through the list with the up and down arrows, browse by pages with pageup and pagedown, and skip to the beginning and end of the list with the home and end keys, respectively.

=== Building your project ===
To build your project, choose '''Project ▸ Build''' or press '''Ctrl+Alt+B'''. The build will occur in your project's root directory (see '''The project root''' below). Valencia runs `make` to perform the build; you must provide a Makefile that invokes `valac` on your source files. (You can write a Makefile by hand, or can generate one using a tool such as `automake`).  The build output will appear in a pane at the bottom of the gedit window. You can double-click on any build error to jump to the source line where it occurred.  You can also use the '''Search ▸ Next Error''' and '''Search ▸ Previous Error''' commands ('''Ctrl+Alt+N''' and '''Ctrl+Alt+P''') to move between build errors.

If you do not use `make`, or want to specify command line options (e.g. `make -j2`), you can tell Valencia a new command to use. Either choose '''Project ▸ Settings''' or press '''Ctrl+Alt+T''' to go to the settings dialog, where you can specify your own custom build command.

You can also clean the project's build output by choosing '''Project ▸ Clean''' or pressing '''Ctrl+Alt+C'''. Valencia by default runs `make clean`, but if you do not use `make`, or would rather run a different command (e.g. `rm *.o *.so`), you can also specify a custom clean command to use in the settings dialog, just like with the build command.

=== Running your program ===
After you've built your project, you can launch the generated program from within gedit.  To do this, you must add a variable definition `PROGRAM=name` to your Makefile, where ''name'' is the name of the program generated by your Makefile.  To run your program, choose '''Project ▸ Run''' or type '''Ctrl+Alt+R'''.  Valencia will launch your program and display its output in a pane in the gedit window.

The '''Project ▸ Run''' command is somewhat limited: it does not work for Autotools-based projects and it's not currently possible to specify arguments to be passed when running your program.

=== The project root ===
In Valencia, a ''project'' consists of a set of Vala files, plus an optional Makefile used for building.

If all of your Vala source files are in a single directory, you don't need to specify a project root in any way.  By default, when you open any source file, Valencia will let you browse to symbols in all other source files in the same directory.

If your project spans multiple directories, your project's root directory must contain either of the following:

 * a Makefile containing the definition BUILD_ROOT = 1
 * a file named `configure.ac` or `configure.in`

When you open any source file below the root directory, Valencia will find the project root and will consider the project to include all Vala (and .vapi) source files below the root.

== Future features ==
The following features are planned but not yet implemented for Valencia:

 * ''Alternate build systems'': There are other build systems besides autotools and make. Valencia should be flexible enough to allow the user to specify an alternate build system other than the default 'make'.
 * ''C support'': Thanks to Vala's close relationship with C, many times in order to investigate the source code of libraries bound to Vala or simply to debug generated code, searching through C code is inevitable. It would be nice to extend Valencia's parser to support browsing C symbols to ease the transitions between the two languages.
 * ''Autocomplete enhancements'': Autocomplete is a nice feature, but it could use several enhancements to make it even more streamlined with features like: type identifiers like full declarations or icons for completion suggestions, context-sensitive lists to avoid exposing nonstatic and protected/private members of classes, grouping suggestions by the most relevant (nested) scope.
 * ''Debugger'': it might be nice to build a front-end to GDB which works as part of Valencia inside gedit.  It's not completely clear whether we'll do this, since existing front-ends such as Nemiver seem to work somewhat reasonably well for debugging Vala code today.

== Other languages ==
Valencia was designed for the Vala language, but Vala and C# are so syntactically similar that Valencia also works fine with most C# code (and, in fact, Valencia will accept files with a .cs extension).

It would not be difficult to extend the Valencia parser to support Java; we'd like to do this.

== Architecture ==
Valencia contains a lightweight Vala scanner/parser which understands only as much of Vala as is necessary for symbol browsing.  The first time you jump to any symbol in a Valencia project, Valencia finds all source files in your project and parses them.  Valencia writes no files to disk: the parse tree for each source file is stored in memory, and is regenerated each time you run gedit.

Whenever you save a source file to disk, Valencia reparses it.  In addition, each time you jump to a symbol definition, Valencia reparses any source files which have been modified but not yet saved.  So symbol browsing always reflects your program as it exists in gedit, whether or not source files have been saved to disk.

We may add more details about Valencia's architecture here at some point.  If you're interested in working on the Valencia code and have questions about how anything works today, don't hesitate to ask questions on the Valencia [http://lists.yorba.org/cgi-bin/mailman/listinfo/valencia mailing list].