Code Recommenders 2.1 Early Access: What’s New? (part 2)

Last week, we have shown you how Snipmatch, Eclipse Code Recommenders’ all new code-snippet search engine, can help you find the right code snippet to solve your particular coding problem. You just hit Alt + Space and can immediately search a repository full of code snippets. But where do these snippets come from? That’s what we will show you this week.

In a nutshell, Snipmatch retrieves its snippets from a shared repository that is maintained by the community – and that includes you. In particular, you can create new snippets and share them with the whole Eclipse community.

Creating New Snippets

Currently, the community repository contains a snippet that inserts a synchronized block, but a similar snippet using the java.util.concurrent.locks.Lock API is missing so far. So let’s fix this. First, open the Snippets view.

The Snippets view

Clicking Add takes you to Snipmatch’s snippet editor. Here you can edit both the snippet’s source and its metadata. Let’s start on the Metadata tab:

Snippet metadata for the ”Lock” snippet

Of course, every proper snippet needs a name. But if you want your snippet to be found by others, better make sure to give it a useful description as well. Moreover, consider assigning extra search terms (i.e., terms which didn’t fit into the description, but which users might also search for) and tags. Here, we picked the extra term unlock; while unlocking is mentioned in neither name nor description, it’s conceivable that users will search for it. As tag with picked concurrency. That way Snipmatch users will be able to quickly browse through all concurrency-related snippets with a query of tag:concurrency.

Once you are satisfied with your human-readable description of what the snippet does, you need a machine-readable description as well. Switch to the Snippet Source tab.

Snippet source for the ”Lock” snippet

On this tab, you’ll need to describe your snippet in the JFace template language. This little-known but powerful template language is also used elsewhere in Eclipse, e.g., in the Template Proposals Content Assist. JFace template language allows you to intersperse the Java code of your template with special template variables. For example, the current selection (if any) will automatically be inserted in place of the ${line_selection} variable. Moreover, we use the ${var} variable so that the template engine will automatically pick up and use any variable of type java.util.concurrent.locks.Lock (if defined in the current scope). Finally, we explicitly position the cursor using ${cursor}.

Once you are done with your snippet, just save it. It immediately becomes available to you in your Snipmatch snippet search. Just hit Alt + Space to try it out.

Sharing Snippets

So far, the Lock snippet sits only on your local disc. Now, let’s share it with others.

To facilitate easy snippet sharing, Snipmatch teams up with (E)Git and Gerrit. Under the hood, all snippets are kept in a Git repository hosted by the Eclipse Foundation. (If you are curious how the repository looks like, you can browse it here.) Now, let’s import your local copy of this repository into your workspace. Select File > Import > Existing Projects into Workspace and select the hidden .recommenders directory inside your workspace as a root folder. You should now be offered a project named Code Recommenders Snippets, which you simply import.

If you have saved your previously created snippet, the Code Recommenders Snippet project should now be flagged by EGit as having uncommitted changes (indicated by a > in front of the project name). So let’s commit them. Select Team > Commit from the project’s context menu.

Commit Changes dialog for new snippet

Choose a descriptive commit message for the the snippet you’ve just created (we recommend the snippet’s name + description) and ask EGit to automatically Add Signed-off-by and Compute Change-Id for Gerrit Code Review. Once your are satisfied with the commit message, just Commit and Push.

If you submit your first snippet, you will then be asked for your credentials.

Login dialog when pushing snippets to Gerrit Code Review

Assuming you have an account with eclipse.org already, you can look up your credentials on Gerrit’s settings page. (Please note: The password is not your SSH passphrase, but rather a special password generated by Gerrit.) Once the server is satsfied with your credentials and the legal paperwork is in order (you need to fill out a Committer License Agreement first), you can view your new snippet in Gerrit Code Review and discuss it with the community. (Have a look at the Lock snippet from this tutorial.)

As you can see, committing and pushing new snippets in the UI is quite straight-forward. But of course you can also push your snippet to Gerrit for review using the command-line (if you have git installed). Simply change into the Git repository below the hidden .recommenders/snipmatch/repositories directory and issue the following command:

git commit -a
git push

Again, this will ask you about your eclipse.org credentials, so enter username and password.

Please note: The EGit- and Gerrit-based sharing workflow currently implemented is a prototype with which we want to gather your feedback. So please don’t hesitate to send us your comments and suggestions for improvement. Either file a bug in Bugzilla or contact us directly via Twitter, Google+ or the mailing lists/forum.

Outlook

We hope this two-part blog post gave you a good overview what’s possible right now with Snipmatch in Code Recommenders 2.1, i.e. to search for, create, and share snippets with the Eclipse community.

But there’s more to come: As part of the Google Summer of Code 2014, Olav Lenz will extend Snipmatch so that it can handle multiple snippet repositories and is no longer restricted to a Git backend. Support for multiple snippet repositories opens up new venues for Snipmatch: For example, you can set up your own Git-based repository containing snippets useful to you and your colleagues, while still benefiting from the community repository hosted by the Eclipse Foundation. Support for backends other than Git make it possible to integrate a snippet “repository” that does a web search for snippets on the fly (cf. Bing Codesearch).

Another Google Summer of Code project is helmed by Stefan Prisca, who will reimplement the current Snippet Source editor using Xtext. You can thus look forward to error and syntax highlighting as well as code completion (it wouldn’t be Code Recommenders without it).

Update Site Manual

Add new comment