Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/deech/shen-elisp


https://github.com/deech/shen-elisp

Last synced: 3 months ago
JSON representation

Awesome Lists containing this project

README 

        
#+TITLE: Shen Elisp

#+AUTHOR: Aditya Siram



* Shen Elisp

This is an implemenatation of the [[http://shenlanguage.org][Shen programming language]] in Elisp. The end goal is to provide:

1. an easy way to play with Shen with no other [[Installation][installation]] hassle (assuming you use Emacs).

2. a first-class development experience when writing Shen. The idea is that an

   editor that understands the code can be much more helpful than one that does

   not. To this end the roadmap involves a full gamut of source code

   introspection and debugging tools.

* Installation

This port is completely self-contained. However since it leans heavily on the

relatively new ~lexical-binding~ feature Emacs 24.3 or above is required.



Also note the installation will emit a large number of byte-compiler warnings.

Nothing to worry about but they are annoying and my attempts to silence them

have thus far failed.



** Manual Download and Setup

Download shen-elisp onto your system somewhere.

#+begin_src elisp

;; add this to your init file in an appropriate location

(add-to-list 'load-path "~/path/to/shen-elisp/")

(require 'shen-elisp)

(require 'shen-repl)

#+end_src



You should really byte-compile the code; running the following snippet should do it:



#+begin_src elisp

(byte-recompile-directory "~/path/to/shen-elisp/" 0 t)

#+end_src



** Quelpa

To install the package directly from Github using `quelpa` tool:

#+BEGIN_EXAMPLE

  (quelpa

     '(shen-elisp

        :repo "deech/shen-elisp"

        :fetcher github

        :files ("shen*.el"))

     :upgrade 't)

#+END_EXAMPLE



Since this is alpha software the ~:upgrade 't~ at the end always pulls the latest version.



If you are a [[https://github.com/syl20bnr/spacemacs][Spacemacs]] user you can do the following:



1. Add the following to the ~dotspacemacs-additional-packages~ variable:

#+BEGIN_SRC elisp

  dotspacemacs-additional-packages '(

                                     (shen-elisp

                                      :location (recipe :repo "deech/shen-elisp"

                                                        :fetcher github

                                                        :files ("shen*.el"))

                                      :upgrade 't)

                                     )

#+END_SRC



2. ~SPC : spacemacs/emacs-reload~

3. Invoke ~shen/repl~ after installation has completed.



It also uses the `quelpa` tool underneath.

* Running

Once the package is installed the Shen REPL should start with:

#+BEGIN_EXAMPLE

M-x shen/repl

#+END_EXAMPLE

* Getting Started

To get started here is a sample REPL session showing how to

- define a function,

- toggle typechecking

- evaluate an expression and

- load a sample file



This session assumes a file called ~add.shen~ in the ~tmp~ directory containing:

#+BEGIN_EXAMPLE

  (define add

    { number --> number }

    X -> (+ X 1))

#+END_EXAMPLE



#+BEGIN_EXAMPLE

  Shen, copyright (C) 2010-2015 Mark Tarver

  www.shenlanguage.org, Shen 19.2

  running under Elisp, implementation: Elisp

  port 1.7 ported by Aditya Siram



  (0-) (define say-hello-to Name -> (@s "Hello " Name))

  say-hello-to



  (1-) (say-hello-to "World")

  "Hello World"



  (2-) (tc +)

  true



  (3+) (map (/. X (+ 1 X)) [1 2 3])

  [2 3 4] : (list number)



  (4+) (load "/tmp/add.shen")



  add : (number --> number)

  run time: 0 secs



  typechecked in 93 inferences

  loaded : symbol



  (5+) (add 1)

  2 : number



  (6+) (add "some string")



  type error



#+END_EXAMPLE



To learn more about Shen see the [[http://shenlanguage.org/learn-shen/index.html][the website]].

** Caveats

The port is still alpha so some REPL features which you might expect are not available. This is being addressed. Starting with the most unpleasant:

- multi-line definitions are not allowed in the REPL. If you hit Return before completing a function definition, for example, the REPL spits out a cryptic error with a list of bytes.

- Ctrl-G does not work. This leaves the REPL in a state where the only thing you can do is delete the buffer, followed by ~M-x shen/repl~. Any functions/datatypes defined in the REPL, however are saved.

- When expressions/functions etc are compiled to Elisp the byte-compiler spits out warnings that may steal focus away from the REPL.

- The REPL still emits Elisp errors on occasion.

- comments are not supported in the REPL.

* Documentation

This port is a literate program written using [[http://orgmode.org/worg/org-contrib/babel/][org-babel]] so the complete source

is documented in ~shen-elisp.org~. It has also been exported to

~shen-elisp.html~ for easy browsing.