JSCL HOW TO

JSCL HOW-TO

This page is not intent to be a comprehensive JSCL user documentation, nor a page of FAQ (since those Lisp wizards never ask, they just dig into the code and cast the spell).

This is a page for those non-wizard JSCL users to find some clues to do something, with extra links for them to find out more.

Please feel free to edit this page, add more examples or more questions.

How to alert?

(#j:alert "this is an alert")

How to access JS object in JSCL?

With #j: and replace dot . with :, you can access almost everything.

To find out more:

https://github.com/jscl-project/jscl/wiki/JSCL-and-manipulations-with-JS-objects

https://github.com/jscl-project/jscl/wiki/FFI-Design-Discussions

CL-USER> #j:navigator:appVersion
"5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/103.0.0.0 Safari/537.36"
CL-USER> 

How to access JS object properties? (without reader syntax)

Use jscl::oget to read, jscl::oset to set.

Syntax:

(jscl::oget obj key)

(jscl::oset value obj key)

Also, jscl::oget is setf-able:

(setf (jscl::oget obj key) value)

How to call methods of JS objects? (without reader syntax)

Use jscl::oget to get the method and then call it:

((jscl::oget obj method-name) &rest args)

Example, call send method of websocket object, passing message as argument:

((jscl::oget websocket "send") message)

How to convert between JS and Lisp representations?

Use jscl::js-to-lisp and jscl::lisp-to-js.

How to add JSCL function to DOM event listener as callback?

Use lambda:

(#j:document:body:addEventListener "mousedown" (lambda (ev) (#j:console:log "Mouse down")))

(#j:setTimeout (lambda () (#j:alert "Timeout")) 2000)

Or function:

(defun on-mousedown (event) (format t "mouse is down: ~A~%" event))
(#j:document:body:addEventListener "mousedown" #'on-mousedown)

How to expose a Lisp function to Javascript world?

Set the value of #j:myJSFunction to the Lisp function.

Example:

(setf #j:myJSFunction (lambda (x y z) (format nil "~a, ~a and ~a" x y z)))

Then we can access the function from Javascript. At the console evaluate:

myJSFunction(1,2,3) => "1, 2 and 3"

How to compile my Lisp file?

sbcl --load jscl.lisp \
     --eval '(jscl:bootstrap)' \
     --eval '(jscl:compile-application (list "~/source/file1.lisp" "~/source/file2.lisp" "~/source/file3.lisp") "~/source/app.js")' \
     --eval '(quit)'

add the generated app.js to your HTML:

    <script>
      var jqconsole = $("#console").jqconsole("", "");
    </script>
     <script src="jscl.js" type="text/javascript"></script>
+    <script src="app.js" type="text/javascript"></script>
    <script src="jscl-web.js" type="text/javascript"></script>

How to compile my Lisp file and expose functions/macros to the REPL?

This is tricky, but feasible, and problematic.

sbcl --load jscl.lisp \
     --eval '(jscl:bootstrap)' \
     --load bundle.lisp \
     --eval '(jscl:compile-application (list "~/source/file1.lisp" "~/source/file2.lisp" "~/source/file3.lisp") "~/source/app.js")' \
     --eval '(quit)'

Where is the bundle.lisp?

https://github.com/jscl-project/jscl/issues/443#issuecomment-1233404538

REPLACE jscl.js with the generated app.js to your HTML:

    <script>
      var jqconsole = $("#console").jqconsole("", "");
    </script>
-     <script src="jscl.js" type="text/javascript"></script>
+     <script src="app.js" type="text/javascript"></script>
    <script src="jscl-web.js" type="text/javascript"></script>

Discussion about this feature:

https://github.com/jscl-project/jscl/discussions/468#discussioncomment-5653148

Caused problem:

https://github.com/jscl-project/jscl/discussions/469#discussioncomment-5666608