[[../../actions/workflows/build.yml/badge.svg]]
Unified way to perform IDEE/like tasks across multiple languages and frameworks in Emacs.
[[./doc/images/idee-ide-view.png]]
** Features
** Experimental features
** Installation
This project is not available on any emacs package repository so you will either have to install it manually, or using something like [[https://github.com/raxod502/straight.el][straight-use-package]]:
(use-package idee :straight (idee :host github :repo "iocanel/idee") :config (idee/init))
This will load all el files included in the project. Alternatively, you can trim down the list of el files to load. For example:
(use-package idee :defer t :straight (idee :host github :repo "iocanel/idee" :files ("idee.el" "idee-utils.el" "idee-vars.el" "idee-actions.el" "idee-comments.el" "idee-headers.el" "idee-navigation.el" "idee-views.el" "idee-hydra.el" "idee-treemacs.el" "idee-projects.el" "idee-templates.el" "idee-eshell.el" "idee-vterm.el" "idee-visitors.el" "idee-arch.el"))
Using `use-package` you can enable additional modules in a similar mannner, for example:(use-package idee-java :straight (idee-java :host github :repo "iocanel/idee" :files ("idee-java.el" "idee-java-utils.el" "idee-lsp-java.el" "idee-jshell.el" "idee-maven.el" "idee-spring.el" "idee-quarkus.el")) (use-package idee/javascript :straight (idee :host github :repo "iocanel/idee" :files ("idee-javascript.el") :config (idee/javascript-init)) (use-package idee/golang :straight (idee :host github :repo "iocanel/idee": files ("idee-golang.el") :config (idee/golang-init))
It's up to the user to decide how to slice and dice. Feel free to check my [[https://github.com/iocanel/emacs.d/blob/master/+ide.el][emacs ide settings]] for inspiration.
*** Installing required resources The first time idee gets installed it needs to install
To install these:
(idee/resources-init)
After this step these resources can be updated via git:
cd ~/.emacs.d/idee git pull --rebase origin master
** Overview
The initial idea behind this project was to provide an IDEE/like window layout (project tree, editor & command line interface). This is functionality already provided by existing plugins, so this plugin was meant to better integrate these plugins.
** Global shortcuts and functions for all languages and frameworks.
Golang developers may be using the oracle or guru, two different plugins with similar functions. To jump to the definition of a symbol guru users use go-guru-definition while oracle users use go-oracle-definition.
In python the same functionality is provided by anacoda-mode-find-definitions (for anacoda users) and so on.
The more languages and frameworks added, the harder it gets to remember the right functions and their shortcuts.
This plugin provides a gloabl set of functions and shortcuts that works for all underlying modes, languages and frameworks. Also this is backed by a hydra, which makes these functions easier to remember.
[[./doc/images/idee-hydra.png]]
** Advanced navigation control
Jumping to a symbols definition, finding callers, looking up functions etc, is of no use if you can't easily return to the point from which the query was originated.
Some plugins do provide jump back functionality, others don't. Even the ones that do provide jump back most of the time don't provide jump further back or jump forth.
And of course this is something that doesn't play nicely in polyglot projects or even across different projects.
This plugin does provide the following functions:
** File template support
For code snippets [[https://github.com/jaotavora/yasnippet][yasnippet]] has been an excellent choice. I often use [[https://github.com/jaotavora/yasnippet][yasnippet]] to provide a full-file template. But I always felt that there should be a line between snippets and templates (even though if the backing plugin is the same, e.g. [[https://github.com/jaotavora/yasnippet][yasnippet]]).
Why?
Because, I'd like the file template mechanism to kick in automatically when a new file is created. And this is how this plugin approaches file templates:
*** How it works?
When a new file is created `(via (idee/new-file)`, the plugin checks the file extension and detects the corresponding major mode that is going to be used.
Then it searches for the target major mode, all available file templates that are found under <template dir>/<major mode>.
A list of all available templates is provided to the user and after the user selected a new file based on the template is created.
For example for java files, the list of available templates can be: ("class", "annotation", "enum", "interface", "junit5" etc).[[./doc/images/idee-file-templates-junit.gif]]
** File header management
Open-source developers are familiar with the processes of adding license headers to their files. But even if this is a pretty common use-case nowadays, even commercial IDE doesn't have a good story around that. Most of the times, this is a configuration that needs to be performed per project with very little room for re usability.
This project introduces the idea of global license header repository that its a folder that users can store multiple different header profiles, which can then be selected per project.
[[./doc/images/idee-header-select-and-apply.gif]]
Regardless, of how you specify the header of choice, you can add a call to idee/header in your file template, so that all new files create contain the header.
[[./doc/images/idee-file-template.png]]
** Project factories
Each language and framework has its own way of creating or scaffolding a project. The idea behind project factories is to allow integrating these approaches into this plugin, so that its easy to create new project.
Each time the users want to create a new project, he is prompted to select one among the known project factories. Then the factory is invoked to generate the project. The factory may or may not require further input.
Provided factories:
*** Spring intializer project factory
A simple project factory that uses https://start.spring.io to scaffold a new project.
[[./doc/images/idee-create-project-spring.gif]]
The factory prompts the user to select from a list of:
- languages
- build tools
- dependencies
and then it generates and opens the project.** Maven support
To make life with maven easier the following features have been added:
*** Per project profile management
Under project root, you can create a file called .idee/maven.el and in there you can set the desired profiles:
(setq idee/maven-profiles ("profile-a" "profile-b"))
These profiles will be automatically used for all maven operations triggered through this plugin.
*** Maven command history Being able to execute the last maven command, using a short cut is cool. Being able to easily repeat any previously executed maven command is even cooler.
[[./doc/images-maven-from-history.gif]]
*** Maven hydra
[[./doc/images/idee-maven-hydra.gif]]
The maven hydra can be called via idee/maven-hydra/body.
** Archetypes
An archetype is a bundle of multiple templates + orchestration code for the purpose of code generation, that can help you boost your productivity. It's inspired by JBuilder's archeology feature, which was pretty similar to maven archetypes but on steroids. In this implementation, an archtype is an elisp command, which may or may not prompt for user input and controls code generation, which is of course based on templates.
*** An archetype for Java annotation processors
Imagine that we want to create an archetype for creating a java annotation and its processors. A processor requires a class file and an entry inside `src/main/resources/META-INF/services/javax.annotation.processing.Processor`.
So, the archetype needs to create two files (the annotation and the processor) and update another (to register the processor).
#+begin_src emacs-lisp
(defun create-java-annotation-and-processor ()
"A simple java annotation and annotation processor archetype."
(interactive)
(let* ((current-fqcn (idee/java-fqcn-of (buffer-file-name)))
(current-pkg (idee/java-package-of (buffer-file-name)))
(fqcn (read-string "Annotation processor fully qualified class name:" current-pkg)))
(idee/java-archetype-create-class fqcn "annotation")
(idee/java-archetype-create-class (concat fqcn "Processor") "apt")
(idee/java-register-spi "javax.annotation.processing.Processor" fqcn)))
#+end_src
*Note*: both [[./templates/java-mode/annotation][annotation]] and [[./templates/java-mode/apt][apt]] templates are provided.
The archtype function can be called directly via `(create-java-annotation-and-processor)` or you can register it to the archetype catalog using:
#+begin_src emacs-lisp
(idee-archetype-register
(make-idee-archetype
:name "Java Annotation and Processor"
:description "A java annotation and a java annotation processor"
:func 'create-java-annotation-and-processor))
#+end_src