smallworld-magik-vscode

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

smallworld-magik-vscode

★ 11 Open GitHub ↗

Visual Studio Code extension for Smallworld Magik

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Integrated Development Environment for Smallworld GIS

This is a fast and modern IDE for [Smallworld](https://en.wikipedia.org/wiki/Smallworld) application development and [Magik](https://en.wikipedia.org/wiki/Magik_%28programming_language%29) programming language.

## Features

* Language support for Magik source and Smallworld resource file types.
* Configure GIS Commands and run Smallworld sessions (Contributor: [MarkerDave](https://github.com/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

![Run GIS Command](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/GisCommand.png)

* 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.

![Snippet](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/snippet.png)

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

![SymbolSearch](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/SymbolSearch.png)

* 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.

![CodeOutline](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/CodeOutline.png)

* 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

![ClassBrowser](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/ClassBrowser.png)

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

![References](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/CodeReferences.png)

---
# 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.

![Redial Command](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/RedialCommand.png)

### 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](https://github.com/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.

![Run GIS Alias](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/SWRunGisAlias.png)

* 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.

![ClassBrowserComments](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/ClassBrowserComments.png)

---
# 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" ]

![GIS Path Settings](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/gisPathSettings.png)

## 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+.

![Startup Settings](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/startupSettings.png)

## 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+.

![GIS Command Settings](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/gisCommandSettings.png)

## 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. 
The`Smallworld.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.

![Smallworld Sessions Settings](https://github.com/siamz/smallworld-magik-vscode/raw/master/images/sessionsSettings.png)

## 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.

smallworld-magik-vscode

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README