branch: elpa/geiser-kawa
commit 5521b2830673e7a5b66a53ab0d64ff25fd9a2768
Author: spellcard199 <spellcard...@protonmail.com>
Commit: spellcard199 <spellcard...@protonmail.com>
Update README after joining of geiser-kawa and kawa-geiser projects
---
README.org | 98 +++++++++++++++++++++++++++++++++-----------------------------
1 file changed, 52 insertions(+), 46 deletions(-)
diff --git a/README.org b/README.org
index abc40a4..1bec66c 100644
--- a/README.org
+++ b/README.org
@@ -2,7 +2,11 @@
* geiser-kawa
** Project description
-geiser-kawa is the emacs side of a geiser-kawa implementation that uses
[[https://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]] for its Kawa side.
+=geiser-kawa= is a geiser implementation for Kawa Scheme.
+
+It has 2 parts:
+- =geiser-kawa=: elisp package inside the =elisp= directory that gives the
name to the whole project
+- =kawa-geiser=: maven project written using Kawa's Java API that adds the
functions that geiser-kawa calls to get the data it needs to a Kawa Scheme REPL
** Supported Kawa versions
:PROPERTIES:
@@ -11,18 +15,6 @@ geiser-kawa is the emacs side of a geiser-kawa
implementation that uses [[https:
Only versions of Kawa > 3.1 are supported, mostly due to the fact that before
the 3.1 release some necessary Kawa classes were private.
-** Try geiser-kawa without modifying your emacs configuration
-
-1. Get Emacs, Cask, Maven and make them available through your $PATH
-2. Clone this repository
-3. cd into the cloned dir
-4. Tell cask to install emacs dependencies with:
- : cask install
-5. Pull [[http://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]] maven
dependencies (the first time takes ~1 minute), compile them and start
geiser-kawa's scratch buffer and repl with:
- : cask emacs -Q --load quickstart.el
-
-The reason you don't need Kawa to try geiser-kawa is that =quickstart.el= uses
the compiled [[https://gitlab.com/groups/kashell/][Kawa's master branch]] that
is one of [[http://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]]'s
dependencies. To do so =quickstart.el= calls =mvn package= (wrapped by
=geiser-kawa-compile-java-dependencies=), which produces a jar that includes
all [[http://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]]'s dependencies.
-
** Supported features
- geiser-related:
@@ -41,7 +33,42 @@ The reason you don't need Kawa to try geiser-kawa is that
=quickstart.el= uses t
- kawa- and java-specific:
- completion for java classes' fields and methods accessed through
colon-notation: don't expect java-grade reliability
-*** About completion for java classes' fields and methods
+** Unsupported features
+
+geiser-related:
+- macroexpand
+- find-file
+- symbol-location
+- module-location
+- symbol-documentation
+- module-exports
+- callers
+- callees
+- generic-methods
+
+kawa- and java-specific:
+- completion for java package names and class names
+
+** Try geiser-kawa without modifying your emacs configuration
+
+1. Get Emacs and [[https://github.com/cask/cask][Cask]] and make them
available through your $PATH
+2. Clone this repository
+ : git clone "https://gitlab.com/spellcard199/geiser-kawa.git";
+3. cd into the cloned dir:
+ : cd geiser-kawa
+4. Tell cask to install emacs dependencies:
+ : cask install
+5. Pull kawa-geiser maven dependencies (the first time takes ~1 minute),
compile them and start geiser-kawa's scratch buffer and repl:
+ : cask emacs -Q --load quickstart.el
+6. You should now have an emacs frame containing a scratch buffer in
=geiser-mode= and a repl buffer, both with geiser-kawa support
+
+To try geiser-kawa you need neither Maven nor Kawa:
+- =mvnw= ([[https://github.com/takari/maven-wrapper][maven-wrapper]]) takes
care of downloading a project-specific Maven version
+- kawa-geiser has [[https://gitlab.com/groups/kashell/][Kawa's master branch]]
as one of its dependencies. When =quickstart.el= calls =./mvnw package=
(wrapped by =geiser-kawa-compile-java-dependencies=), it produces a jar that
includes kawa-geiser and all its dependencies, including Kawa itself.
+
+** About completion for java classes' fields and methods
+
+The whole project is in a persistent "experimental" state, but this part even
more so.
The main interactive elisp function is
=geiser-kawa-complete-java-fom-at-point=. It's not bound to a key by default.
@@ -50,11 +77,11 @@ For this to work you have to:
- avoid syntax errors (e.g. unbalanced parentheses, wrong number of children
sexps inside a form, etc...)
How it works (the region getting part is quite rudimentray):
-1. A region of the current buffer and cursor point inside it are sent to
[[https://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]], which uses
[[https://gitlab.com/spellcard199/kawa-devutil][kawa-devutil]] for actual
functionality. The region of the buffer goes:
- - from either:
+1. A region of the current buffer and cursor point inside it are sent to
kawa-geiser, which uses
[[https://gitlab.com/spellcard199/kawa-devutil][kawa-devutil]] for actual
functionality. The region of the buffer goes:
+ - from: either:
- =(geiser-syntax--pop-to-top)=, if non-nil
- =(line-beginning-position)=, if =(geiser-syntax--pop-to-top)= is
=nil=
- - to either:
+ - to: either:
- end of sexp beginning at toplevel, if =(geiser-syntax--pop-to-top)=
is non-nil
- =(line-end-position)=, if =(geiser-syntax--pop-to-top)= is =nil=
2. An arbitrary symbol is added at cursor point, so it can be found again in
the AST
@@ -63,41 +90,20 @@ How it works (the region getting part is quite rudimentray):
- one of them matches: the matcher function itself then also has to tell
which class we are completing for
- none are left: empty data
-** Unsupported features
-
-geiser-related:
-- macroexpand
-- find-file
-- symbol-location
-- module-location
-- symbol-documentation
-- module-exports
-- callers
-- callees
-- generic-methods
-
-kawa- and java-specific:
-- completion for java package names and class names
-
** Difference from
[[https://gitlab.com/spellcard199/geiser-kawa-scheme][geiser-kawa-scheme]]
-- The Kawa side of geiser-kawa uses
[[https://gitlab.com/spellcard199/kawa-geiser][kawa-geiser]], which is written
using Kawa's Java API.
-- The Kawa side of geiser-kawa-scheme is written directly in Kawa Scheme.
-- I'm going to add more features to geiser-kawa but I probably won't port them
to geiser-kawa-scheme.
-
-Reasons for rewriting and translating the old geiser-kawa from Kawa Scheme to
Java:
-- Easier to add as a scripting language in Java projects: just add the jitpack
repo and the kawa-geiser dependency (see pom.xml as an example)
-- Easier to inculde external java libraries via maven central for additional
functionalities (e.g. [[https://github.com/classgraph/classgraph][classgraph]])
-- Tooling for Java is excellent, tooling for Kawa is poor
+This project (geiser-kawa) is a translation/rewrite of
[[https://gitlab.com/spellcard199/geiser-kawa-scheme][geiser-kawa-scheme]],
which has been my first attempt at writing geiser-kawa. After
geiser-kawa-scheme confirmed me that a geiser-kawa implementation was possible
I decided to rewrite the Kawa side using Kawa's Java API, for the several
reasons:
+- Easier to add as a scripting language in Java projects: just add the jitpack
resolver and this project's repository as a dependency
+- Easier to inculde external java libraries via maven central for additional
functionalities
+- Tooling for Java is excellent, tooling for Kawa is not
- Fully static type checking: probably it's because I'm bad at programming,
but it helps me a lot
-- Possibility to share code between kawa-devutil and Kawa's Language Server
- The old geiser-kawa's scheme implementation logic has been split in 2
projects:
- - [[https://www.gitlab.com/spellcard199/kawa-devutil][kawa-devutil]]:
functions that take care of getting data and general functionalities (e.g. eval
capturing output)
+ - [[https://www.gitlab.com/spellcard199/kawa-devutil][kawa-devutil]]:
functions that take care of getting data and general functionalities (e.g.
output-capturing eval)
- kawa-geiser:
- - it's the maven project included with this project, made up by the
file =pom.xml= and the directory =src=
+ - the included maven project
- gets data and features through kawa-devutil and wraps the result in
the geiser protocol
-
-The fact that kawa-devutil is now a project separated from geiser means that
it may also be used to avoid re-writing the data-getting logic if one wanted to
implement a protocol for a tool other than geiser (e.g. nrepl, jupyter,
swank/slime).
+- Possibility to share code between kawa-devutil and Kawa's Language Server
+- Since kawa-devutil is now a different project from geiser-kawa, one could
use it to avoid re-writing the data-getting logic if he wanted to implement a
Kawa server for a tool other than geiser (e.g. nrepl, jupyter, swank/slime)
geiser-kawa VS geiser-kawa-scheme - recap table:
