magik-mode: Emacs major mode for Smallworld Magik files

Content

1. Installation
2. Features
3. Usage with Smallworld 4.x or older
4. Side effects
5. Familiar with SW 4.x EMACS? Some tips for you!

Installation

These packages are available on MELPA. See Emacs Wiki for instructions on how to set up and install packages.

The alternative, and recommended, way of installing magik-mode is using use-package:

(use-package magik-mode
  :ensure t
  :config
  (magik-global-bindings)
  (magik-menu-set-menus))

Features

Automatic completion support

Automatic completion is supported by this package. By default it is on.

Tested frontends are corfu and company. Orderless is inheritly used and needs a minor configuration to work with dynamics.

Orderless configuration

(use-package orderless
  :custom
  (completion-styles '(orderless basic))
  (completion-category-overrides '((file (styles basic partial-completion))))
  :hook ((magik-completion-mode) .
         (lambda ()
           "Disable the `!' orderless dispatcher."
           (setq-local orderless-affix-dispatch-alist
                       (assoc-delete-all ?! (copy-alist orderless-affix-dispatch-alist))))))

Recommended corfu package configuration

(use-package corfu
  :custom
  (corfu-auto t)
  (corfu-auto-delay 0.05)
  (corfu-auto-prefix 2)
  (corfu-cycle t)
  (corfu-preselect 'prompt)
  :init
  (global-corfu-mode))

(use-package corfu-popupinfo
  :after corfu
  :ensure nil
  :custom
  (corfu-popupinfo-delay '(0.5 . 0.3))
  (corfu-popupinfo-max-width 80)
  (corfu-popupinfo-max-height 20)
  :init
  (corfu-popupinfo-mode))

Recommended company package configuration

(use-package company
  :diminish
  :hook (after-init . global-company-mode)
  :custom
  (company-backends '(company-capf))
  (company-idle-delay 0.05)
  (company-minimum-prefix-length 2)
  (company-selection-wrap-around t)
  (company-tooltip-align-annotations t)
  (company-require-match nil))

(use-package company-quickhelp
  :after company
  :hook (after-init . company-quickhelp-mode)
  :custom
  (company-quickhelp-delay 0.5))

Don't want completions?

Well here's what you need to do:

(use-package magik-mode
  :ensure t
  :config
  (global-magik-completion-mode -1)
  (magik-global-bindings)
  (magik-menu-set-menus))

Global keys

Global keys are set by calling (magik-global-bindings) after the package has been loaded.

Key	Description
F6	Copy current method to kill-ring
F7	Transmit current method to Magik session
F8	Transmit current region to Magik session
F9	Mark current method
F2-Return	Transmit thing at point to Magik session
F2-F7	Transmit current method to Magik session
F2-F8	Transmit current region to Magik session
F2-#	Comment region
F2-Esc #	Uncomment region
F2-b	Transmit buffer to Magik session
F2-e	Toggle magik-electric-mode
F2-m	Transmit current method to Magik session
F2-q	Fill public comment
F2-r	Transmit current region to Magik session
F2-s	Open Magik version selection
F2-t	Trace current statement
F2-Space	Explicitly trigger electric space
F2-Tab	Hippie expand
F2-z	Start a Magik session
F3-F3	Open Class Browser
F3-b	Paste method and class into Class Browser
F3-c	Paste class name into Class Browser
F3-j	Jump to source of method under point
F3-m	Paste method name into Class Browser
F3-/	Open Class Browser and clear search

magik-version

Major mode for managing multiple Magik environments.

Key	Description
Return	Select the current selected line as the current active environment.
Space or Down	Move to the next environment.
a	Open gis_aliases file of selected version. Will prompt for layered product to use if selected version has more than one aliases file available.
+	Add a new entry to the currently open file.
o	Open the gis_version.txt file to add or edit the file itself.
q	Quit the buffer.

magik-aliases

Major mode for editing Magik aliases files.

Key	Description
Shift-Return	Run a Magik session for the selected alias.
Space or Down	Move to the next alias.
q	Quit the buffer.

magik-session

Major mode for running a Magik session as a direct sub-process. Provides command recall, history folding, traceback navigation, output filtering, and drag-and-drop file loading.

Key	Description
Return	Insert newline, or send command when at the prompt.
C-a	Move to beginning of line, or after the prompt.
M-p	Recall previous command from history.
M-n	Recall next command from history.
F2-↑ or F2-C-p	Fold buffer to show command history.
F2-↓ or F2-C-n	Unfold buffer.
F2-=	Print last traceback.
F2-f	Toggle output filter.
F2-i	Invalidate completion caches.
F2-p	Recall previous command matching current input.
F2-n	Recall next command matching current input.
F4-F4	Complete symbol at point.
F4-↑	Navigate to previous traceback frame.
F4-↓	Navigate to next traceback frame.
F4-$	Start an external shell.
F4-g	Go to the file referenced in the current error.
F4-m	Copy current method to work buffer.
F4-r	Copy current region to work buffer.
F4-s	Insert a debug statement.
F4-w	Set work buffer name.
F4-P	Print traceback.
F4-S	Save traceback to file.
F8	Send command at point.
C-c C-c	Kill the Magik session process.
C-c C-</kbd>	Send quit signal to the session.
C-c C-z	Send stop signal to the session.
C-c C-d	Send EOF to the session.

magik-mode

Major prog mode for editing Magik code. Provides syntax highlighting, smart indentation, method navigation, pragma management, and direct transmission to a Magik session.

Support for outline-minor mode. Try: (outline-minor-mode)

Support for imenu. Try: (add-hook 'magik-mode-hook 'imenu-add-menubar-index)

Key	Description
Return	Newline with indentation.
Tab	Indent current line, or cycle through pragma fields.
#	Smart comment insertion.
Space	Expand yasnippet template at point (if any).
/	Cycle pragma option forward.
</kbd>	Cycle pragma option backward.
C-M-h	Mark current method; repeat to extend selection.
M-↑ or F2-↑	Move to previous method.
M-↓ or F2-↓	Move to next method.
F2-$	Transmit current $ chunk to session.
F2-i	Invalidate completion caches.
F2-d	Check documentation for method at point.
F2-D	Check documentation for all methods in file.
F2-p	Check pragma for method at point.
F2-P	Check pragma for all methods in file.
F4-F4	Complete symbol at point.
F4-c	Copy current method to kill-ring.
F4-e	Compare methods between windows with ediff.
F4-m	Copy current method to work buffer.
F4-n	Set work buffer name.
F4-r	Copy current region to work buffer.
F4-s	Insert a debug statement.
F4-w	Compare methods between windows.

magik-ts-mode

Major Mode for Using Tree-sitter with Magik

You can use M-x treesit-install-language-grammar to install and build the grammar, or download the latest prebuilt artifact from GitHub for your operating system. If downloading from GitHub, place the extracted file in ~/.emacs.d/tree-sitter.

With magik-ts-mode enabled, you can use M-x treesit-explore-mode to view the syntax tree of the current buffer.

For more information about Tree-sitter, see the Mastering Emacs tutorial.

magik-cb

Major mode for the Magik Class Browser. Searches for methods and classes using a running method_finder process and lets you jump directly to source.

Global keys (set by magik-global-bindings):

Key	Description
F3-F3	Open Class Browser.
F3-b	Paste method and class name into Class Browser.
F3-c	Paste class name into Class Browser.
F3-j	Jump to source of method at point.
F3-m	Paste method name into Class Browser.
F3-/	Open Class Browser and clear the search.

Keys inside the Class Browser buffer:

Key	Description
Space or F3-h	Quit the Class Browser.
; or F3-s	Edit topics and flags.
/	Clear the search field.
Tab	Cycle to the next input field.
Mouse-2 or F3-j	Jump to source.
F3-↑	Fold (collapse) the result list.
F3-↓	Unfold (expand) the result list.
F3-$	Open GIS shell.
F3-f	Show family tree of class under point.
F3-F or F3-o	Toggle override flags.
F3-T	Toggle override topics.
F3-t	Toggle all topics.
F3-2	Toggle 200-result limit.
F3-g	Switch to associated GIS session buffer.
F3-l	Cycle to next inheritance setting.
F3-r	Reset Class Browser.

magik-module

Major mode for editing Magik module.def files. Provides commands to load and manage modules from within Emacs.

Key	Description
F2-b	Load (transmit) the module to the Magik session.
F2-c	Compile messages for the module.
F2-d	Reload the module definition.
F2-m	Toggle the save-magikc option.
F2-r	Toggle the force-reload option.
F2-R	Remove the module from the session.

magik-product

Major mode for editing Magik product.def files.

Key	Description
F2-b	Load (transmit) the product to the Magik session.
F2-r	Reinitialise the product.

magik-msg

Major mode for editing Magik message files (.msg, .hmsg). Provides navigation between messages and direct compilation.

Key	Description
F2-↑	Move to previous message.
F2-↓	Move to next message.
F2-b	Transmit buffer to Magik session.
F2-c	Compile module messages.
F2-m	Mark current message.

magik-loadlist

Major mode for editing Magik load_list.txt and patch_list.txt files. Provides syntax highlighting that distinguishes file stems from subdirectory entries, and can synchronise the list against the actual directory contents.

Key	Description
F2-b	Transmit the load list to the Magik session (load_file_list).
C-c r	Refresh the buffer contents from its directory, prompting to add, remove, or update entries. With a prefix argument, accept all changes without prompting.

magik-trn

Major mode for editing Magik translation files (.trn).

Key	Description
F2-b	Transmit translation buffer to Magik session.

magik-doc-gen

Automatically fills in missing documentation stubs in Magik methods and exemplars. Two documentation formats are supported:

sw-method-doc — the native Magik convention. Parameter names are written in ## UPPERCASE lines inside the method body. Missing parameters are detected by comparing the method signature against existing ## lines and inserted automatically.

type-doc — a structured annotation style using ## @param {:} name for parameters, ## @return {:} for return values, and ## @slot {:} name for exemplar slots.

Commands are bound in magik-mode and accessible via F2-d / F2-D:

Key	Command	Description
F2-d	magik-single-method-sw-method-doc	Insert missing sw-method-doc stubs for the method at point.
F2-D	magik-file-sw-method-doc	Insert missing sw-method-doc stubs for all methods in the file.

Additional commands available via M-x:

Command	Description
magik-single-method-type-doc	Insert missing type-doc stubs for the method at point.
magik-file-type-doc	Insert missing type-doc stubs for all methods and exemplar slots in the file.
magik-single-exemplar-type-doc	Insert missing @slot stubs for the exemplar nearest point.

magik-lint

Magik-lint support.

To enable automatic linting in magik-mode buffers, the following conditions have to be met:

• Package flycheck needs to be installed and loaded.
• magik-lint-VERSION.jar (download) has to be installed in ~/.emacs.d/magik-lint/ (location can be customized with the variable magik-lint-jar-file).
• The java executable path should be in exec-path, or the variable flycheck-magik-lint-java-executable has to be set. flycheck-magik-lint-java-executable will automatically be set when the environment variable JAVA_HOME is set.
• flycheck-mode has to be enabled for magik-mode buffers. Or use global-flycheck-mode to enable it for all buffers.

YASnippet

yasnippet is a required dependency and its snippets are loaded automatically. In magik-mode, magik-ts-mode, and magik-session-mode, the Space key is bound to magik-yas-maybe-expand: if the word before point matches a snippet key it expands the snippet, otherwise it inserts a regular space. Use Tab to jump between fields inside an expanded snippet.

The snippets below are available in magik-mode, magik-ts-mode, and magik-session-mode. magik-module-mode, magik-product-mode, and magik-trn-mode have their own dedicated snippet sets listed after.

magik-mode / magik-ts-mode / magik-session-mode snippets, organised into groups:

Methods

Key	Snippet
method	_method / _endmethod with pragma and docstring
private	_private _method / _endmethod
abstract	_abstract _method / _endmethod
iter	_iter _method / _endmethod with _loopbody

Control structures

Key	Snippet
if	_if / _then / _endif
ife	_if / _then / _else / _endif
ifel	_if / _then / _elif / _endif
ifele	_if / _then / _elif / _else / _endif
if_ol	_if ... _then ... _endif (one line)
elif	_elif / _then
for	_for / _over / _loop / _endloop
over	_over / _loop / _endloop
while	_while / _loop / _endloop
loop	_loop / _endloop
loopbody	_loopbody(...)
block	_block / _endblock
protect	_protect / _protection / _endprotect
protect_locking	_protect with _lock / _endlock inside
lock	_lock / _endlock
try	_try / _when / _endtry
try_with	_try / _when / _with / _endtry
catch	_catch / _endcatch
throw	_throw / _endthrow
throw_with	_throw / _with / _endthrow
proc	_proc() / _endproc
proc_ol	_proc(...) ... _endproc (one line)

Object-oriented

Key	Snippet
def_slotted_exemplar	Full exemplar definition with slots and parents
def_indexed_exemplar	Indexed exemplar definition
def_mixin	Mixin definition
construct	Filled new() and init() method pair with slot assignments
clone	_clone.$0
.	_self.$0
super	_super.$0
remex	remex(:filename) using the current file name
add_child	add_child(...) call

Slots and properties

Key	Snippet
slot	{:name, _unset} slot entry
define_slot_access	define_slot_access(...)
define_slot_externally_readable	define_slot_externally_readable(...)
define_slot_externally_writable	define_slot_externally_writable(...)
define_pseudo_slot	define_pseudo_slot(...)
define_shared_constant	define_shared_constant(...)
define_shared_variable	define_shared_variable(...)
define_print_attributes	define_print_attributes(...)
define_show_attributes	define_show_attributes(...)
define_binary_operator_case	define_binary_operator_case(...)
def_property	Property definition

Documentation and pragmas

Key	Snippet
pragma	_pragma(classify_level=, topic={}, usage={})
doc	Single ## docstring line
dob	Multi-line docstring block

Conditions and messages

Key	Snippet
define_condition	condition.define_condition(...)
raise	condition.raise(...)
message_handler	message_handler.new(...) using the current class name

Keywords

Key	Snippet
pack	_package <name>

magik-module-mode snippets:

Key	Snippet
new	New module.def skeleton
description	description block
requires	requires dependency entry
optional	optional dependency entry
required_by	required_by entry
install_requires	install_requires entry
requires_datamodel	requires_datamodel entry
requires_java	requires_java entry
language	language <name>
templates	templates block
test	test block
tests_modules	tests_modules block
condition_message_accessor	condition_message_accessor <name>
dnt	do_not_translate
hidd	hidden
messages	messages block (deprecated)

magik-product-mode snippets:

Key	Snippet
new	New product.def skeleton
description	description block
title	title block
version	version major.minor.patch
requires	requires dependency entry
dnt	do_not_translate

magik-trn-mode snippets:

Key	Snippet
enumerator	enumerator translation block
external_name	external_name translation block
field_value	field_value translation block

magik-electric-mode

Minor mode providing the older electric template system. Use F2-Space to trigger an electric expansion explicitly at point, regardless of whether magik-electric-mode is enabled. Toggle the mode with F2-e or M-x magik-electric-mode.

Usage with Smallworld 4.x or older

If you plan to use this package with Smallworld-Versions 4.x or older, you should consider the following points:

• Customize the variable magik-session-auto-insert-dollar to non-nil.
• You might customize the variable magik-aliases-layered-products-file to "$SMALLWORLD_GIS/product/config/LAYERED_PRODUCTS". If you also want to use EMACS for Smallworld 5.x, it's easier to create the directory $SMALLWORLD_GIS/../smallworld_registry and copy or soft-link the original LAYERED_PRODUCTS file there. This ensures the same structure as in Smallworld 5.x.
• There is no support (yet) for the Smallworld dev-tools. So if you want to do things like F4-d to start debugging a method, you may still want to use the EMACS which has been delivered with the Smallworld 4.x (or older) software.
• Some more things which are at least partly not supported by Smallworld 5.x are not supported (e.g. deep-print)

Side effects

Some keys bindings are changed with respect to a standard EMACS installation, at least when using (magik-global-bindings):

Key	Function in standard EMACS	Change in Magik Mode package
F2	2C-command	globally changed to prefix key
F3	kmacro-start-macro-or-insert-counter	globally changed to prefix key
F4	kmacro-end-or-call-macro	used in magik-mode and magik-session-mode as prefix key

The reason for that is, that many Magik developers are familiar with these bindings from former EMACS installations.

For quick usage of the keyboard-macro functions you may e.g. bind the Ctrl-F2 and Ctrl-F4 combinations by putting the following lines into your .emacs file:

(global-set-key [C-f3] 'kmacro-start-macro-or-insert-counter)
(global-set-key [C-f4] 'kmacro-end-or-call-macro)

Familiar with SW 4.x EMACS? Some tips for you

If you've been using the EMACS delivered by GE with Smallworld version 4.3 and earlier, you might want to customize some variables with default values changed with respect to the former "GE"-EMACS:

actual variable	actual default	former variable	former default	Remarks
magik-electric-mode	t	electric-magik-mode	nil	If non-nil, typing Space after keywords like if inserts the matching control structure. If nil, you have to use F2-Space to achieve the same behaviour.
mouse-drag-copy-region	nil	dto.	t	Paste a mouse selection (even to other programs). (Default has been changed in standard EMACS)
show-paren-mode	nil	dto.	t	if point is on opening or after closing bracket, show the matching one. (GE's EMACS had done this customization)

Eventually you'll find some more customazations in of the former GE's EMACS' installation in emacs/site-lisp/smallworld/sw_defaults.el, but you'll have to check, whether these will work the the EMACS installation you are using now.