Alan IF 3 syntax for Sublime Text 3.

• https://github.com/tajmone/sublime-alan-if

IMPORTANT CHANGES!!! — Both the repository and package were renamed, click here to read about the required actions you should take.

ALPHA STAGE — This project is still a WIP Alpha version! Most features are still experimental and subject to continuos changes. Screenshots and descriptions might not always accurately represent the latest changes.

The following document isn't always updated to cover all the added features, it's mainly intended to illustrate the project goals; for a full list of current features, see the CHANGELOG.

Table of Contents

• About
• Features
  • Syntax Highlighting
    • Ligatures Support
  • Color Schemes
  • Goto Symbols
  • Build Systems
  • Autocompletions
  • Snippets
    • New Adventure Boilerplate
  • Transcipt and Solution Syntaxes
    • Alan Solution Files Syntax
    • Alan Transcript Files Syntax
• Requirements
• Installation
• License
• Acknowledgements
• IMPORTANT CHANGES!!!
  • Package and Repository Renamed
• Links

I've created this Alan 3 syntax package just to add some support for Alan source files in Sublime Text, for my own personal use. I haven't really planned to make this a finished product to share on Package Control. Nevertheless, I've decided to share it publicly — just in case it might be useful to others too, or in the remote chance that someone else will join in the project and give me a hand to flesh it out.

I'll be polishing the sytnax and adding features as needs arise, and try to document changes. As a guideline, I'll be pushing to master only tested features, so you should be safe keeping the package synced to master branch.

A brief presentation of the features so far implemented.

Although the Alan syntax isn't yet fully implemented, it's already mature enough to provide some decent syntax highlighting.

I still need to implement semantic scoping of syntax elements, so that proper indexing can be achieved (Goto functionality, etc.).

For more info on the roadmap and wishlist, see:

• TODO.md
• CHANGELOG.md
• WORK_NOTES.md

The package also ships with additional syntax definitions and color schemes for:

• Compiler log in the the Build Systems
• Alan IF Solution files (aka "commands scripts").
• Alan IF Transcript files.

Alan syntax has been optimized to enable support of code ligatures. The following Alan operators and keywords are converted to ligatures (if enabled and if font supports them):

Not all code fonts implement in the same way ligatures for =>, <=, >= and =<, depending on which of those are treated as comparison operators and which as arrows (some fonts, like Fixedsys Excelsior, are available in dual choice). This is a crucial point for rendering correctly Alan's operators in ligatures.

The following code-ligatures fonts have been tested with Sublime Alan:

To disable ligatures for the Alan syntax, open/create your User settings file for Alan syntax and add "no_calt" to the "font_options" option:

{
    "font_options":
    [
        "no_calt",
    ],
}

Sublime-Alan ships with the "Alan DarkFluo" color scheme:

This color scheme is still pretty much work-in-progress. The goal is to provide a palette which doesn't strain the eyes, and where the prose parts of the Alan source stand out from the rest of the code, allowing to easily switch focus between the adventure text and its code.

Amongst the goals of this package is that of providing good indexing functionality of Alan language's symbols in order to maximize Sublime Text's Goto Symbol functionality.

Currently, the following syntax elements are captured and indexed:

• Class declaration identifiers.
• Instance declaration identifiers.

Quoted identifiers are transformed before indexing: the delimiting quotes are removed, and any escaped single quotes inside the identifier are replaced with one single quote (eg: 'Tom''s Cat' is indexed as Tom's Cat). This is intended to facilitate looking up identifiers in Goto Symbol functionality, by representing them sa they are seen in the Alan adventure world.

The build system allows compiling alan source files directly from within th editor (CtrlB). Errors reported by Alan compiler will be overimposed in the sourcecode panel, and the user can navigate through the results via F4 and CtrlF4:

The full error log from the compiler will also be shown in Sublime Text's console. This package syntax highlights the error log to improve visual navigations of the different error types and messages:

Currently there is only one build system, which compiles the current editor's alan source file ("*.alan" files only) without extra options (except -cc, to allow capturing error reports). Additional Build systems will be added soon.

NOTE — Build functionality requires Alan binary compiler to be available on the system PATH.

I'm working on autocompletions to provide a fast coding experience thanks to contextual suggestions.

NOTE — I haven't yet found the time to list main completions in this document. For a detailed and always up-to-date overview of the available completions, see the contents of completions/ folder.

Sublime-Alan ships with some useful snippets to simplify writing your adventures.

The New Adventure Boilerplate snippet provides a quick template for starting a new adventure using Alan Standard Library v2.1:

By typing "newadv"+Tab inside an Alan source file, you'll get:

The snippet provides some presets and placeholder values, you can then edit each field and/or skip to the next one via the Tab key.

The newadv snippets also supports custom environment variables as default values for some of its fields:

The supported variables are:

• ALAN_AUTHOR

When this environment variable is defined, its value will automatically be used to fill the author field.

To define these environment variables, create a "Alan Env Vars.tmPreferences" file (the actual filename doesn't really matter, only the extension) in "Packages/User/", and define them like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>name</key>
    <string>Custom Alan env vars</string>
    <key>scope</key>
    <string>source.alan</string>
    <key>settings</key>
    <dict>
        <key>shellVariables</key>
        <array>
            <dict>
                <key>name</key>
                <string>ALAN_AUTHOR</string>
                <key>value</key>
                <string>Tristano Ajmone</string>
            </dict>
        </array>
    </dict>
</dict>
</plist>

After creating this file, the newadv snippet will automatically fill-in the author field with your custom variable:

--==============================================================================
-- "Game Title" by Tristano Ajmone, 2018.
--==============================================================================
IMPORT 'library.i'. -- ALAN Standard Library v2.1


THE my_game ISA DEFINITION_BLOCK

  HAS title    "Game Title".
  HAS subtitle "".
  HAS author   "Tristano Ajmone".
  HAS year     2018.
  HAS version  "1".

END THE.


THE start_loc ISA LOCATION

END THE start_loc.


Start at start_loc.
DESCRIBE banner.

This package also provides additional syntax definitions for Alan game transcripts and solution files:

• Alan IF Solution files: *.a3s and *.a3sol.
• Alan IF Transcript files: *.a3t and *.a3log.

The alternative .a3sol and .a3log extensions were arbitrarily invented and introduced by this package, long before Alan adopted their new official counterparts .a3s and .a3t, respectively (See alan-if/alan#2). The package currently supports both new (official) and old (arbitrary) extensions because there are various projects still using the older extensions, so we want to provide a grace period to allow them to migrate to the new official extensions, before deprecating them.

The purpose of these syntaxes is to simplify handling of game transcript and solution files by settings Sublime Text to handle these files with ISO-8859-1 encoding, as well as providing some minimal syntax highlighting and allowing the user to associate custom color schemes to them. Without a basic syntax definition, and its encoding settings, Sublime Text would default to UTF-8 encoding, which would cause lots of problems and errors if the solution file contains special characters (like accented letters), and would not display correctly transcripts containing special chars.

Hopefully, these two extra syntaxes will simplify creating and using command scripts to test adventures during the authoring stage, and to correctly visualize game transcripts (i.e. provided the "*.a3s" and "*.a3t" file extensions are used).

• Alan IF Solution.sublime-syntax
• Alan IF Solution.sublime-settings

This package also defines an Alan IF Solution syntax associated to the *.a3s/*.a3sol file extensions.

Solution files (aka "commands scripts") are text files containing player commands used to run an adventure in automated mode, by passing the script to the interpreter. The *.a3s/*.a3sol file extensions are intuitively similar to the "*.sol" extension often used for solution files, but at the same time can be uniquely uniquely associated to Alan (Alan adventures having the *.a3c extension), allowing to enforce custom setting without the risk that they might affect other commonly used extensions.

In Alan IF Solution files, single-line comments are enabled via the usual comment keyboard shortcuts, producing the "; " comment delimiter.

• Alan IF Solution.hidden-tmTheme
• Alan IF Solution.YAML-propertyList-tmTheme (scheme source)

This package also sets a predefined hidden color scheme to preview Alan Solution files:

... which is intended to make editing command script file more pleasant to the eye.

The color scheme is created by converting the YAML source file "Alan IF Solution.YAML-propertyList-tmTheme" via PackageDev's build system "Convert to ... - Property List"; since the YAML format is easier to maintain.

A few snippets are also available to allow commenting solution files:

; ==============================================================================
; Heading 1 Frame
; ==============================================================================

; ------------------------------------------------------------------------------
; Heading 2 Frame
; ------------------------------------------------------------------------------

; ===============
; Heading 3 Frame
; ===============

; ---------------
; Heading 4 Frame
; ---------------

• Alan IF Transcript.sublime-syntax
• Alan IF Transcript.sublime-settings

This package also defines an Alan IF Transcript syntax associated to the *.a3t/*.a3log file extensions. While transcripts generated with the Alan interpreters used to have the .log file extension, now Alan as officially adopted the .a3t extension because .log is already being used in so many different contexts that it doesn't allow to enforce special editor settings on it.

The syntax also syntax highlights the player input lines, capturing the prompt (assuming it's always ">"), strings and comments. The output text from the adventure is not highlighted, as the scope of this syntax is to provide easy color separation between player commands and game output text.

In trasncripts of adventures which change the prompt (from the default ">" symbol) the player input line won't be captured and syntax highlighted.

In Alan IF Transcript files, single-line comments are enabled via the usual comment keyboard shortcuts, producing a "> ; " comment delimiter. The reason why commented lines are preceded by a prompt (unlike Solution files, which use just a semicolon) is that this is the expected behavior in this context. Transcipts are automatically produced by the interpreter, and the purpose of the Alan IF Transcript syntax is to allow a nicer preview of these files; but in some cases the user might wish to add some comments to the transcipts before sharing them with other (eg, to pinpoint a typo or a bug), and these added comments should be represented as a comment line added by the player during the game session (hence the addition of the prompt before the comment delimiter).

• Alan IF Transcript.hidden-tmTheme
• Alan IF Transcript.YAML-propertyList-tmTheme (scheme source)

This package also sets a predefined hidden color scheme to preview Alan Transcript files:

... which is intended to make previewing of game transcript files more pleasant to the eye.

The color scheme is created by converting the YAML source file "Alan IF Transcript.YAML-propertyList-tmTheme" via PackageDev's build system "Convert to ... - Property List"; since the YAML format is easier to maintain.

• Minum requirement: Sublime Text 3 BUILD >=3170 (uses new .sublime-color-scheme format).
• Recomended: bleeding-edge Sublime Text 3 Dev BUILD.

This package is being developed using the latests ST3 Dev Builds, and it might use features not included in the latest stable build; I can't grant that it will work with ST3 Stable Builds.

This package is being developed using the latests ST3 Dev Builds, but now that Sublime Text 3 has reached its end of life, and its next major incarnation is about to be released at any moment, there shouldn't be any longer any differences between ST3 Dev Builds and ST3 Stable Builds, since no further updates are expected, except for bug fixes.

Create an "Alan_IF" folder inside "<data_path>/Packages/", open a shell inside "<data_path>/Packages/Alan_IF/" and type:

git clone https://github.com/tajmone/sublime-alan-if .

Don't forget the "." after the repository URL! it's needed in order to clone the repository contents directly into the current folder, without creating a "sublime-alan-if" container folder.

• LICENSE

MIT License

Copyright (c) 2018 Tristano Ajmone
https://github.com/tajmone/sublime-alan-if

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

I would like to thank the following people who have helped me out with the difficulties of creating this syntax:

• Keith Hall (@kingkeith)
• Thomas Smith (@ThomSmith)
• @FichteFoll

Without their precious help I wouldn't have overcome many of the problems related to implementing the syntax and choosing the right scopes.

I'd also like to express my gratitude to the authors of invaluable guidelines and tutorials which fill the huge gaps of undocumented Sublime Text 3 features and guidelines:

• Daniel Spiewak (@djspiewak) for his Stateful Chaining guidelines.
• Thomas Smith for his Use the Stack guidelines.

June 7, 2021 — The repository was renamed from sublime-alan to sublime-alan-if to prevent clashes with the Alan Programming Language by Alan Technologies, Inc (see alantech/alan/#548).

Furthermore, the package was renamed from "Alan" to "Alan IF" to prevent conflicts in case a user would install both Alan IF and the Alan language by Alan Technologies, since they are planning to create a Sublime Text package in the future (see alantech/alan/#257).

Due to these changes, you should take the following action:

1. Update the Git remote of your local repository to point to the new repository URL:

   https://github.com/tajmone/sublime-alan-if

2. Rename the <data_path>/Packages/Alan/ folder to <data_path>/Packages/Alan_IF/.

Alan IF links:

• Alan website
• Alan-IF mailing list
• Alan Wiki
• IFWiki » Alan page
• Alan sourcecode on GitHub
• Alan Standard Library v2 on GitHub