This page is related to Summer of Code 2011

See the list of Summer of Code 2011 Ideas

This is a Summer of Code 2011 student page

Project: SoC_Ideas_Eclipse_Plugin2011

Description

timotei - Improving the Eclipse Plugin

I aim at improving the plugin, so it will become the tool used by all UMC Authors.

Contacts

IRC

timotei, timotei21

Other

Forum: timotei
gna.org: timotei

SoC Application

Battle for Wesnoth - Google Summer of Code Application

Proposal Summary

Page Last Updated: 05 April 2011

In the following lines I will give details on how I'm planning to implement some of the required tasks, and also add some new ones.

Multiple Wesnoth installations

Having multiple wesnoth setups, and working with them at the same time would be nice to be done from inside the plugin. For that, there will be a new preferences page. The page will look something like this:

There will be buttons that add/remove/edit a certain wesnoth installation. When adding/editing an installation, a new page like the current one (in which we set the paths), will be shown. The user will be able to name it and specify the version (I could automatically get the version by invoking wesnoth --version). The current page for setting the paths will act as a default installation.

After we have configured the paths, the user can chose the installation to which the (new) projects are bound, by opening the project properties. There will be a wesnoth-related page, where the user will be able to chose to what installation the project binds. With that, every command that uses the paths, won't use the single current paths, but the ones assigned to each project.

There would be a problem in case the project will be migrated between 2 different plugin's versions. For example, in one place we would have defined "1.9.4svn" but on the other there would be "trunk".

We can solve this in 3 ways:

Alert the user that the installation doesn't bind, and let him chose the current matching installation for his plugin.
Default automatically to the current plugin's default installation.
"Hardcode" the version, so that there may be defined just installations like: 1.8.0, 1.9.3. With this we lose some flexibility, but we could use this as base version for new installations, so for example, a user can have two 1.9.3 installations. Provided this, we have again a possible problem, which can be solved again by 1. or 2., but this time, trying to match the base version first.

With this feature, the user won't need to restart the plugin at all, switching workspaces.

Regarding the technical PoV, all paths will be stored using eclipse's preferences system, by appending an unique id of each installation to each path in that set.

Enhance the Content Assist(CA) feature

The CA framework is very extensible but it lacks proper contexts for providing the content. I was thinking of trying to accomplish the generating of CA list either by using a config file, in case something like that can be used or writing directly the code that does that.

Another factor that is involved in a better auto-complete, is the schema.cfg the plugin bases on. Depending on whether the schema is worked on during this summer of code, I'll need to redo a bit the parser of the schema, in case the format/semantics change.

Project files dependecy tree

In order for the CA to work better - and maybe other areas would benefit from this - we will need to build a project file tree. With that tree, we can see how a certain declared macro/variable will affect subsequent related files and also their scope. Basically, we can see the relation from a file to anothers

This tree will be (re)built in 2 situations:

A file is added/removed/changed it's name
A full rebuild is triggered (for example, the project is added for the first time in the workspace)

The tree will be built by the WML parser's rules:

files are processed in the alphabetically order
_initial.cfg is the first processed before anything else.
_final.cfg is the last processed after anything else.
if there is a _main.cfg in the directory, it is the only one processed.

Since the current WesnothProjectBuilder doesn't take in account the previous rules, I will create my own method of visiting each folder's children in the correct order. This method will look close to wesnoth's one, namely get_files_from_in_dir() found in src/filesystem.cpp:93.

For a very fast lookup, as a data structure we will use a Hashtable, which has as the key the local project path to the file, and as a value a custom structure, which has the previous/next/parent/son properties, used to traverse the tree. The previous/next go on the same tree level, while the parent/son go up/down in the tree. I will use this instead of a tree, because this will give us access to info about a file, faster, in O(1) compared to a breadth-first search which has O(V+E) - where V is number of vertices and E number of edges.

Content Assist Config(CAC) Files

The CAC files will provide values that are default/available to config files from the wesnoth engine itself. There will be several files that define the values based on their context. This will allow a very great flexibility editing the CA list.

A CAC file will be just a simple text file, that has on each line one (or more) value(s) depending on the context.

The cac/variables.txt will contain variables available. The list is currently available at [1]. For example the file could look like:

$side_number
$turn_number
...

The cac/events.txt will contain the game events. The list is availabe at: [2]. Since the events that have spaces in their names can replace that with an underscore '_', the file will contain the underscore instead space variants also.

Variables

The variables are either defined by user or defined by default by the wesnoth engine. User's variables will be parsed from each processed file by the WesnothProjectBuilder, using the WMLSaxHandler. The default variables will be parsed and added from the CAC file. (cac/variables.txt)

Variables definitions can be triggered using the VARIABLE macro:

{VARIABLE var_name "value"}

or the [set_variable] tag:

[set_variable]
	name=my_var
	value="value"
[/set_variable]

The ConfigFile class in the org.wesnoth.wml.core already has a list of variables. The Variable class has some fields that allow its identification. We will build that list when we parse each file, adding each variable found by the previous defined triggers. When the content assist finds the '$' character, it will supply the user + default variables gathered so far.

Since the variables can be cleared, thus they have scope, the Variable class needs to be extended, so it can represent the scope aswell.

//TODO: detail about: scoping for same vars name, expanded macros that use variables, getting the original line in the file -> maybe use a custom parser?

Events

Besides the default event names, supplied by the wesnoth engine, there can be created custom ones, wich will be triggered with [fire_event]. As usual the default events names will be available in the cac/events.txt file.

The events defined by the user will be parsed from the name attribute of the [event] tag.

Attributes

All attributes are currently got from the schema.cfg

Attributes Values

Macros

The support for macros is already built in, but it needs a way to let them have scope. That is, when an #undef is found, the certain macro would not be available to subsequent files unless redeclared.

Support for custom luaWML tags

The lua can create new WML Tags. It would be nice that the plugin suggest those aswell besides the schema.cfg. The lua will be easily parsed, since there is a simple pattern for creating new tags:

wesnoth.wml_actions.<tag name>(cfg)

The parser will just run over the lua code/file, over each line, trying to match the 'function *wesnoth.wml_actions.*' pattern. If it finds something, it will add the tag name to the list of tags. There is also a small thing we might have missed. The user could use a shorthand notation for the actions namespace, so when searching for the pattern, I will add to the 'pattern to match' list, the respective variable when searching for new WML Tags.

Thus, like the wml-tags.lua from the data/lua uses:

local wml_actions = wesnoth.wml_actions

the 'to match' list will contain: 'function *wesnoth.wml_actions.*' and 'function *wml_actions.*', thus finding other tags too.

Going further more, for an optional enhancement, I could also search that function to see if it needs/has some extra attributes. //TODO: find a pattern for this.

Automatic/headless building

The eclipse plugins can be automatically built from command line, provided there is the eclipse sdk and the eclipse delta pack on the builder's machine. The plugin can also use Buckminster tool to automate the building of the plugin.

More info at:

Standalone app auto-update

The current standalone application doesn't offer the same eclipse's update system. I will add it, so anytime there is a new version of the plugin, it can be updated with a single click by the user, without the needing to download a new standalone app again.

Documentation

The current existing readme will be split in 2 manuals: User Manual and Developer Manual (Don't forget to add images where relevant).

The user manual will contain:

Prerequisites and Installing the prerequisites
Installing the plugin / standalone version
Using the plugin
Plugin features
Step-by-step use cases
- Setupping the workspace
- Creating a new project and running it in the game
- Importing existing projects
- Using the WML Editor
- Updating the plugin
Frequently Asked Questions

The developer manual will contain:

Prerequisites and Installing the prerequisites
Adding the plugin's projects in the
Compiling and Running the plugin
Deploying the plugin and standalone app

Other ideas

Addons management

There will be a new Addons management view. It will behave much like the in-game addon manager, but it will be more handy since the user doesn't need to start the game for that (and also wait till the cache refreshes after downloading it). This view will be based on the python script from data/tools/wesnoth_addon_manager, like it does currently for uploading the project as an addon.

The view will let the user see the list/details for each of the addons currently on the server. There will be also a filter based on what addon server to use (trunk/1.8/1.9/etc)

The user will be able to just right click on an addon and download it to it's user data folder. Optionally a new project will be created, based on the just downloaded addon.

File Templates

- new file/projects templates management -> download from webserver? <_use apache velocity

Unit testing

Grammar

For a better wml handling with in the editor, I will create a Testing class for the current grammar. The class will do testing on all *.cfgs in the data directory. That way after modifing something in the grammar we will be able to see how many errors we have introduced/eliminated. This will greatly help the developing of a better grammar that can hold all current WML formats.

//TODO: Grammar: don't allow empty keys

Parsing and getting information from files

I will create some basic (or taken from existing campaigns) config files that will be parsed in order to check if the correct behaviour - correct information is extracted from the files.

This will check for extracting the:

scenario name
campaign name
next_scenario
first_scenario
variables
macros

Timeline

The GSOC period is between 24th May and 20th August. But since I have exams for about 3 weeks (during 31.05-20.06.2010), I will start working on the plugin before the 24th of May. The timeline will be written as the coding starts on 23 May.

Here is a table with key periods of the time spend on this project.

Period	Actions
23 May	Work starts
23 May - 3 June	Add Support for multiple installations
4 June - 11 June	Allow headless build of the plugin
12 June - 19 June	Add the auto-update feature for the standalone app
20 June - 25 June	Create the documentation
26 June - 17 July	Enhance Content Assist
15 July	Mid-term evaluations deadline
18 July - 25 July	Addons management view
26 July - 2 August	Unit testing


15 August	Suggested 'pencils down' date. Take a week to scrub code, write tests, improve documentation, etc.
22 August	Firm 'pencils down' date. Mentors, students and organization administrators can begin submitting final evaluations to Google.

Tasks

This is a list of the "atomic" tasks that need to be done, based on the project part. Since the big tasks are split into smaller task, the progress will be seen better and any problems that arise with the timeline will be seen faster. I will update this table based on my current progress.

Project part	Details	Status (Legend: None, Done, Not done, In Progress)
Multiple installations	Implement the preferences pages	None
Multiple installations	Implement the logic for saving and loading the installations's paths on the disk	None
Multiple installations	Implement the project preferences page	None
Multiple installations	Rewrite the current mechanisms that use the paths to use the ones based on the project.	None
Headless build	Research about what system to use for automatic building of the plugin	None
Headless build	Implement the chosen system for the wesnoth plugin	None
Auto-update	Implement the auto-update feature.	None
Documentation	Write the User Manual	None
Documentation	Write the Developer Manual	None
Enhance Content Assist	Project dependency tree	None
Enhance Content Assist	Content assist files	None
Enhance Content Assist	Variables	None
Enhance Content Assist	Events	None
Enhance Content Assist	Lua tags	None
Enhance Content Assist	Lua tags attributes	None
Addon management	Create the GUI of the view	None
Addon management	Create the view's logic	None
Unit testing	Tests for the grammar	None
Unit testing	Tests for parsing the config files	None
		None

Questionnaire

The questionnaire can be found here: http://wiki.wesnoth.org/User:Timotei21/Questionaire

SummerofCode2011 Timotei21

Contents