purescript-gjs

GNOME JavaScript bindings for PureScript.

Use this library to write GJS programs.

Project using purescript-gjs:

• purescript-gnome-shell, a library to write gnome-shell extension.
• autochill, a gnome extension to help you chill by setting up breath time.
• gnome-mumble-push-to-talk, a gnome extension to enable Mumble push to talk.

Usage

Checkout the examples in the ./test/ directory.

Gio.Async

The library provides high level functions using the Aff type to escape callback hell. For example, to read a file, a raw gio usage looks like this:

import Gio.Raw.File as File
import GJS (log)

printFile :: String -> Effect Unit
printFile path = do
  file <- File.new_for_path path
  File.load_contents_async file Nothing $ \obj res -> do
    content <- File.load_contents_finish obj res
    log content

Instead, the higher level Gio.File module provides a convenient readFile function:

import Gio.File as File

printFile :: String -> Aff Unit
printFile path = do
  content <- File.readFile path
  liftEffect $ log content

The GJS does not provides a native setTimeout function which is required by Aff to handle errors. Use the Gio.Async.init function to install compatibility functions.

This blog post is a good read to learn more about Aff: Asynchronous PureScript.

For command line application, use GLib.MainLoop.withLoop, checkout the Test.Gio example for a parallel async demo.

For graphical application, checkout the Test.Gtk4 example for custom glib loop lifecycle.

Contribute

Contributions are most welcome.

The project needs help to complete the APIs bindings:

• add missing binding manually, or checkout the work in progress codgen.
• add higher level functions (e.g. in Gio.File or Gio.Subprocess) by following existing conventions (such as Data.Text.IO or SimpleCmd).

You will need a PureScript toolchain and the gnome developper tool.

Run test, for example:

$ make test
$ make test-gtk4

If you experience any difficulties, please don't hesistate to raise an issue.

References

Here are a collection of pointers to navigate the GNOME ecosystem.

GJS

GJS provides bindings to the GNOME ecosystem.

• https://gjs.guide
• https://gjs-docs.gnome.org/

Use the gjs command instead of node

GObject

GObject is the base upon which most of the GNOME platform is built.

• Guide: https://gjs.guide/guides/gobject/basics.html

• GJS Reference: https://gjs-docs.gnome.org/#q=gobject

• GObject.Object: https://gjs-docs.gnome.org/gobject20~2.66p/gobject.object

GLib

GLib is a general-purpose utility library.

• Reference: https://developer.gnome.org/glib/stable/

• GJS Reference: https://gjs-docs.gnome.org/#q=glib

• MainLoop: https://gjs-docs.gnome.org/glib20~2.66.1/glib.mainloop

• Variant format string: https://developer.gnome.org/glib/stable/gvariant-format-strings.html

Gio

GNOME input/output library:

• Guide: https://gjs.guide/guides/gio/file-operations.html

• GJS Reference: https://gjs-docs.gnome.org/#q=gio

• DBus: https://gjs-docs.gnome.org/gio20~2.66p/gio.dbusconnection

• Settings: https://gjs-docs.gnome.org/gio20~2.66p/gio.settings

DBus

D-Bus is a message bus for sending messages between various applications.

• Guide: https://www.andyholmes.ca/articles/dbus-in-gjs.html

• Reference: https://developer.gnome.org/platform-overview/unstable/tech-d-bus.html.en

• Example: ./test/DBus.purs

Cairo

Cairo is a 2D graphics library.

• GJS Reference: https://gjs-docs.gnome.org/#q=cairo

Gtk

GTK is a library for creating graphical user interfaces.

• Reference: https://developer.gnome.org/gtk4/4.0/

• GJS Reference: https://gjs-docs.gnome.org/#q=gtk40

• Migration from gtk3 to gtk4: https://developer.gnome.org/gtk4/4.0/gtk-migrating-3-to-4.html

• Example: ./test/Gtk4.purs

Clutter

Clutter is an free and open source software library for creating portable, dynamic, compelling and fast graphical user interfaces.

• Homepage: https://wiki.gnome.org/Projects/Clutter
• Guide: https://developer.gnome.org/clutter-cookbook/stable/
• GJS Reference: https://gjs-docs.gnome.org/#q=clutter

Clutter widgets are called Actors.

Changes

0.1

• Initial release.