Integrated Development Environment for Smallworld GIS

This is a fast and modern IDE for Smallworld application development and Magik programming language.

Features

• Language support for Magik source and Smallworld resource file types.
• Configure GIS Commands and run Smallworld sessions (Contributor: MarkerDave ).
• Magik code compiler, module and product loaders for Smallworld 5.x.
• Integrated Smallworld Class Browser for Smallworld 5.x.
• Magik F2-keys shortcut combinations and a traditional light theme.
• Code Outline, Definitions, References, Code Lense, Code Action, Hover and Symbol Provider features.

---

For Magik Developers

Get started with Smallworld 5.x cambridge_db example, based on your local installation in C:\Smallworld.

• Open the cambridge_db product folder in VSCode
• start a session by keyboard shortcut F2-z and enter the following command: -p C:\Smallworld\core -a %SMALLWORLD_GIS%..\cambridge_db\config\gis_aliases cambridge_db_open

• Optionally save the GIS Command in Settings to the list of GIS Commands pre-configured for F2-z.
• Open a Magik file to see the code outline for classes and methods in the file.
• Add some Magik code to the file and use F2-b to compile the file.

• Open the Symbol browser by CTRL-T for formatted search Package:Class.Method

• Access Object Exemplars, Methods, and Procs in the entire product tree, and click on Symbol search and Code Outline to jump to a definition in the code.

• Click on !swCB! icon (F2-F2) on the statusbar or to open the Class Browser prompt and type in a Class.Method combination to query method_finder.
• or Simply hover over a Class.Method combination, to get Class Browser hover action

• Click on a Class.Method combination, hold down CTRL to get Definition Peak or right-click for Definition and References in the context menu

---

Starting a Smallworld sessions

Redial the last Session

• When the extension is activated, on opening a folder or a workspace, the Redial dialog pops up to run the last run GIS Command or start a new command.

Run a GIS Command

• Press F2-z and enter a Smallworld 5 standard command line to start a session. [-p productPath] [-e environFile] -a gis_aliasFile alias

Run gis_aliases stanzas. (Contributor: MarkerDave )

• Open a gis_aliases file, the stanzas appear boxed in Orange and have Code Actions (Yellow light bulb).
• Click the Light bulb to get the command to Start a Smallworld Session.
• An environment.bat in the same path as gis_aliases will automatically be loaded.

• Set the Smallworld gis.exe path in the Settings and setup optional startup batch commands to run before the gis.exe.
• Open a gis_aliases file, the stanzas appear boxed in Orange and have Code Actions (Yellow light bulb).
• Click the Light bulb to Start a Smallworld Session.
• An environment.bat in the same path as gis_aliases will be loaded automatically.

Magik Compiler

• Compile Magik code in a Smallworld 5 session, from the Code Actions or using key sequences:
  • F2-b or F9 to compile the code buffer in the current editor
  • F2-r or Ctrl+F9 to compile the current code range (e.g. _method ... _endmethod)
  • F2-s or Alt+F9 to compile the current code selection
  • F2-l or Shift+F9 to compile the current single line of code
  • For F7 compiler keys see Extension Settings section below

Class Browser

Run Class Browser from !swCB! icons or from Class Browser Hover Actions over object.method definitions. * F2-F2 Open Class Browser prompt and the class Browser document. * F2-UP ARROW to fold up method_finder comments. * F2-DOWN ARROW to fold down method_finder comments. * Ctrl+/ to toggle the folding/unfolding method_finder comments.

The Class Browser prompt accepts the following syntax: [class].[method] [*loc/obj] [*b] [*a] [*s] [*r] [*d] [*dp] [*rs]

• Pragma flags filter the classification level as *b basic, *a advanced, *s subclassable, *r redefinable, *d debug, *dp deprecated, *rs restricted.
• If no pragma flags are defined, all classifications will be listed.
• Inheritance is filtered by *loc local methods only, *obj parents including object
• If inheritance filter is not defined all parents except object will be listed. Example: item.aspect *dp *rs lists all the method names containing aspect on class names containing item which are flagged as 'deprecated' or 'restricted'.

The Class Browser Editor/Title command ## toggles the folding and unfolding of method_finder comments and arguments.

---

Extension Settings

Open File-Preferences-Settings and search for Smallworld GIS under the Extensions.

Smallworld GIS Path configuration

The Smallworld.gisPath defines the location of Smallworld gis.exe or the product path. The gisPath is an array of strings that allows configuration for multiple product locations.
Example: "Smallworld.gisPath": [ "C:\Smallworld5\core", "C:\Smallworld4\product" ]

Smallworld Startup configuration

The Smallworld.startup is for the Windows DOS commands to run before gis.exe. This settings is a JSON array of strings. Invalid commands do not stop the startup process. Example:

{
	"Smallworld.startup": [
		"set JAVA_HOME=%SMALLWORLD_GIS%/jdk-11.0.1",
		"set PROJECT_DIR=//appserver/SW_Upgrade_5",
		"call %PROJECT_DIR%/set_my_environment.bat",
		"set SW_DB_CONTEXT_DIR=%PROJECT_DIR%/db_context",
		"if not exist %SW_DB_CONTEXT_DIR% mkdir %SW_DB_CONTEXT_DIR%"
	]
}	

You can edit Smallworld.startup in the Settings editor in Visual Studio Code 1.37.0+.

Simple GIS Command configurations

Smallworld.gisCommand section contains the configuration for GIS Commands that are executed by F2-z keys and starts a session from a standard Smallworld 5 command line. A basic GIS Command have the following format:

"[-p productDir] [-e environFile] -a gis_aliasFile [alias]"

If [-p productDir] is not specified, Smallworld.gisPath will be used. If [-e environFile] is not specified, an environment.bat found in the same path as gis_aliasFile will be added to the command. If [alias] is not specified and gis_aliasFile is a fully resolved pathname, all of the aliases in that file will be listed for GIS Command entries. The Smallworld.startup Windows DOS commands are executed before a GIS command is run. You can edit Smallworld.gisCommand in the Settings editor in Visual Studio Code 1.37.0+.

Multi-environment GIS Session configuration

Smallworld.sessions section provides a flexible configuration for multiple and complex GIS Command definitions in the form of a JSON object. GIS Commands defined in Smallworld.sessions are self contained and do not share or use the Smallworld.startup or Smallworld.gisPath values. TheSmallworld.sessions setting is defined in the following format:

{
	"Smallworld.sessions": [
		{	
			"session": "< optional label displayed on the list of GIS Commands F2-z >",
			"gisPath": "< optional Smallworld Core product directory (%SMALLWORLD_GIS%) >",
			"startup": "< optional DOS commands to run before gis.exe >",
			"command": "<[-p productDir] [-e envFile] [-j options] ... [-a aliasFile] alias ...>"
		}
	]
}

An example configuration for multiple sessions is included in the next section. To edit the Smallworld.sessions, click on Edit in settings.json in the Settings editor.

A JSON Example for Smallworld Settings

The following is an example of a settings.json file for a VSCode Smallworld Magik extension:

{
	"Smallworld.gisPath": "//appserver/Smallworld/CST519/core/bin/x86/gis.exe",
	"Smallworld.startup": [
		"set JAVA_HOME=%SMALLWORLD_GIS%/jdk-11.0.1",
		"set PROJECT_DIR=//appserver/SW_Upgrade_5",
		"call %PROJECT_DIR%/set_my_environment.bat",
		"set SW_DB_CONTEXT_DIR=%PROJECT_DIR%/db_context",
		"if not exist %SW_DB_CONTEXT_DIR% mkdir %SW_DB_CONTEXT_DIR%"
	],
	"Smallworld.gisCommand": [
		"-p C:/Smallworld/core -a %SMALLWORLD_GIS%/../cambridge_db/config/gis_aliases cambridge_db_open",
		"-a C:/Smallworld/cambridge_db/config/gis_aliases cambridge_db_open"
	],
	"Smallworld.sessions": [
		{	
			"session": "Project 1 Test code on SW 5.1.9 on jdk 11",
			"gisPath": "C:/SW519/core",
			"startup": [ "set JAVA_HOME=C:/jdk-11.0.1","set PROJECT_DIR="C:/tst/project_1"],
			"command": "-a %PROJECT_DIR%/config/gis_aliases db_open"
		},
		{	
			"session": "Project 1 Development on SW 5.2.0 on jdk 12",
			"gisPath": "C:/SW520/core",
			"startup": ["set JAVA_HOME=C:/jdk-12.0.2","set PROJECT_DIR="C:/dev/project_1"],
			"command": "-a %PROJECT_DIR%/config/gis_aliases db_open"
		},
		{	
			"session": "Project 1 Production on SW 5.1.8 on jre 8",
			"gisPath": "C:/SW518/core",
			"startup": ["set JAVA_HOME=C:/jre","set PROJECT_DIR="C:/prd/project_1"],
			"command": "-a %PROJECT_DIR%/config/gis_aliases db_open"
		}
	],
	"files.autoGuessEncoding": true,
	"terminal.integrated.scrollback": 5000
}

Compiler F7 Key Combinations

To define F7 key combinations for the Magik compiler:

• Open Preferences Keyboard Shortcuts (Ctrl-K Ctrl-S)
• Type "SW Compile Magik" in the filter to find the Magik compiler commands
• Select the commands you want to change (for example F9 keys) and edit to F7

Release Notes

[1.5.0] - 10-11-2019

• New integrated Smallworld Class Browser (replacing apropos function).
• New Redial function to automatically start the last GIS Command session.
• Definition and Reference support for Message identifiers in .magik and .msg files.
• Various bug fixes and improvements.

Known Issues

No Support for Smallworld Sessions Prior to Version 5.0

This extensions does not support Smallworld sessions and its related functions on versions older than 5.0 which includes:

• GIS Command not supported on Smallworld 3.x and 4.x
• Magik Compiler commands do not support Smallworld 3.x and 4.x
• Class Browser is not supported for Smallworld 3.x and 4.x

Ctrl+C at Magik prompt terminates the Session.

Ctrl+C key combination at the Magik prompt is captured by the VSCode Terminal DOS command and terminate the Terminal and the GIS session.

Workspace Close\Open terminates the Session.

Opening/closing a Workspace or the active Folder while a Smallworld Session is running, will terminate the session.

• Use Add Folder to Workspace... to access the source tree
• Quit the Smallworld Session before switching the active Folder or Workspace.

Class Browser delays and synch issues.

The delay in Class Browser response from the GIS session and the VSCode thread priorities cause some aspects of the Class Browser UI no to work as expected.

• Click twice on the Comment fold/unfold icon ## when the swCB folding state is lost.
• For queries returning large number of classes and methods, the swCB editor might remain blank for a while.
• If the communication to the method_finder in the GIS session is lost, please re-run the Class Browser from !swCB! icon in the statusbar.