Emacs module for managing imports
Emacs Lisp
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
README.org
code-imports-test.el
code-imports.el

README.org

Description

code-imports is a module to help you manage code imports. The eventual goal is to handle all import-related logic for a variety of languages, so as to make developing with emacs faster.

Currently, this library lets your organize your imports according to predefined rules, as well as grabbing files to add as import, and adding those imports to a destination file.

This module is not designed to work with any existing module such as EDE.

Dependencies

code-imports should work with emacs version 23 and up. It uses the built-in cl module, but it doesn’t need any other module to be installed.

Languages

Right now, code-imports works with:

  • C
  • C++
  • Java

Usage

To use, install this module somewhere on your load-path, and put

in your .emacs file.

Organizing imports

To organize imports, this module needs to know how you want your imports grouped. There are two ordering variables used, code-imports-c++-ordering (which also is used for C), and code-imports-java-ordering. The C++ ordering is based off of Google’s Style Guide.

The ordering is defined as a list of possible elements, each one defining a matching rule:

  • self: The matches the .h file corresponding to the .c file you are editing.
  • t: This matches everything unmatched by another element.
  • regex string: This is a string, which is interpreted as a regex, and is matched against the whole import line.

Between each section a blank line will be inserted.

In Java, code-imports will try and remove unused Java classes, but it may not removal all.

To organize imports, run M-x code-imports-organize-imports.

Adding imports

The workflow for adding imports is currently simple. Say you want to add an import pointing to destination.h to the file target.h. Navigate to destination.h, and when you are in the destination.h buffer, grab the import. Then go to target.h and add the grabbed import, which will stick the correct include statement in the file, and organize your imports in that file as well. The following instructions will go over how to do this in detail.

Defining the root

For code-imports to be able to take a file name and make an import out of it, we have to know what the root of your project is. Store the root in code-imports-project-directory. For example, if the file you want to import is stored at /home/ahyatt/src/project/parser/parser.h, set code-imports-project-directory to /home/ahyatt/src/project, so that the include will be understood as parser/parser.h.

If you work on more than one project, use emacs 23 directory variables. In your project root, you can define a file called .dir-locals.el (or whatever your dir-locals-file is) and set your file there with:

((nil . ((code-imports-project-directory . "/home/ahyatt/src/project"))))

Grabbing imports

To add imports, first navigate to the file whose import you want to add, and run M-x code-imports-grab-import. The import will be stored in a clipboard. There are separate clipboards for Java and C++.

Adding grabbed imports

After adding as many files as you need, go to the file in which you want to add your imports and run M-x code-imports-add-grabbed-import. The import will be added and your imports re-organized.

Limitations

This module cannot handle imports with comment interspersed, such as

// This is to include the Foo class.
#include "foo.h"                                \
// This is is necessary for Bar
#include "bar.h"

If you try and organize or add an import to such a file, it will detect the unorganizable imports and throw an error.

However comments on the same line should not pose an issue:

#include "foo.h"  // for Foo
#include "bar.h"  // for Bar

Future improvements

  • Support grouping of regexes in each section (if anyone asks for it).
  • Adding support for other languages is not easy. We need more of a plugin approach.