Scopes

Iron Resource Documents

 

Iron scope resource files are text files that are compiled and used by Iron to define scopes and scope sets.

The iron.scope file currently only associates a color with a scope. In the future, other attributes such as font sizes, font attributes (bold, italic), theme elements and other settings can be associated with scopes.

This document will describe the Zinc scope file format, it’s grammar, content and uses.

Refer to the Iron Resource Files: Customizing documentation on how to compile (press F7) and debug (press F4) Zinc files in more detail.

To really change the world, we have to help people change the way they see things.

Suzy Kassem

American writer, poet, philosopher, and multi-faceted artist.

Scopes

A scope is a name that represents a set of attributes or settings that can be applied to various elements within Iron. For example, a scope can include RGBA (red, green, blue, alpha) color attributes that are used when rendering fonts, selected text, pane backgrounds, the caret, shadows, etc.

Often, scopes are used in conjunction with lexers to contextually highlight source code. In other words, source code elements such as variables, function names, numbers, punctuation, comments, keywords and more are rendered in different colors based on the color attributes associated with a scope. This is known as syntax highlighting.

A lexer is defined to parse source code (not strictly speaking) for a specific computer language and categorizes bits of text into regions and associates a name for each type of region recognized by the lexer.

The regions of text may be a single character, an identifier or number, a block comment, an entire function, a type declaration, etc. The regions of text may overlap or have no length at all e.g. the beginning of a file is a region but doesn’t have a length.

Each region type has a name associated with it referred to as a selector. Iron uses selectors to seek out a matching scope to determine what color to use when rendering regions of text.

Scope Names and Selectors

Scope names and selectors both use a dot-notation to impart a hierarchy amongst related scopes. Scope names are made up of parts. The first part connotes a very general meaning or group, the name getting more specific and descriptive as parts are appended to the right separated by dots (periods).

Consider these scopes as found in the iron.scope file:

//  Token colors.
scope_add( “token”,                                  color( 0.972549, 0.972549, 0.949020, 1.0 ) );
scope_add( “token.integer”,                color( 0.682353, 0.505882, 1.0,                1.0 ) );
scope_add( “token.real”,                        color( 0.682353, 0.505882, 1.0,                1.0 ) );
scope_add( “token.string.open”,       color( 0.855,          0.657,          0.125,          1.0 ) );
scope_add( “token.string.quoted”,  color( 0.901,          0.858,          0.454,          1.0 ) );

There are five scope names related to tokens in this snippet. Tokens are small regions of text that represent different elements such as integers, real numbers or possibly two types of strings as suggested here.

You can see how the scope names are partitioned by dots (periods) and get more descriptive, that is more specific in meaning, as additional parts of the scope name are added to the right. For example, the last scope token.string.quoted is a quoted string, a type of token. It’s not an integer token nor a string that doesn’t have a closing quote (which would be open).

When Iron parses a line of source code such as:

print( “Word starts with ” + ‘W’ );

for the text Word start with, the lexer will apply the selector token.string.quoted.double to that region of text and apply a selector token.string.quoted.single to the W’.

When Iron goes to render this line of text into a pane, as it renders each region of text it will compare the region’s selector to the scopes currently active in the iron.scope file to find the most appropriate color attributes to apply. Seeking out a scope is known as resolving the selector or simply finding a “matching” scope.

In this example, neither of the selectors token.string.quoted.single or token.string.quote.double are defined. So how does Iron resolve these selectors?

To resolve a selector, Iron checks for an exact matching scope name. If not found, it shrinks the scope name by removing the right-most part up to and including the dot. It then seeks a matching scope name which is more general in meaning. And then repeats until it finds a matching scope. If no scope is matched, Iron will use a default color (usually white for fonts, otherwise black).

In this example, both string selectors resolve to the token.string.quoted.

Note:  Iron currently has only one built-in lexer for the language called Slang. Thus the selectors being employed are fixed, not definable by you at this time. The default iron.scopes file uses only scopes employed by the Slang lexer.  Slang is DarkViking Software’s proprietary computer language used to author Iron.

Note:  Iron assigns the Slang lexer based on the file’s file name extension. Iron assigns the Slang lexer to these extensions: slang, debug, cpp, hpp, c, h, y, keymap, macro, menu and scope. All other files use plain text highlighting (none). Once other computer languages are supported, you will be able to change the lexer assigned to any particular file and create your own.

Scope File Format

The scope file format is defined by the Zinc grammar. In relation to scopes, the grammar is very simple and will evolve with time.

At present, only one type of attribute can be associated with a scope and that’s to specify a color. More attribute types such as font sizes, graphical element dimensions, audio settings and more will eventually be defined to support skins and 3D themes.

You can inspect the iron.scope file by loading it from the menu item Tools|Scopes|Load Scope File or use the Command Palette (press F8) and type iron.scope and Enter.

Zinc files are composed of declarations and statements (terminated with semicolons), comment blocks, sides comments and blank lines. Other than inside quoted strings and to separate tokens, whitespace is ignored.

Ignoring the comment header block, all Zinc files start with a namespace statement. Though required, at this time, the namespace statement is ignored. In the future, namespaces will be used in Iron to control semantic scoping and visibility between Zinc files (e.g. global vs local elements).

There are four types of declarations: scope_set(), macro(), keymap_set() and menu(). Though any declaration type can appear in any Zinc file, Iron’s default set of resource files keeps them well-partitioned by type, that is, only scope sets appear in the iron.scope file.

Here’s a minimum scope file:

namespace scope_iron;
scope_set scope_monokai( void )
{
                    scope_add( “select”, color( 0.286, 0.282, 0.243, 0.8 ) );
}

The name of the scope set is scope_monokai(). It has no parameters. In the body of the scope set declaration, between open and close curly braces {}, are statements. Scope statements can only call one function: scope_add(). More built-in scope-related functions will be added later as themes develop.

A scope_add() function has two parameters: a scope name and an attribute.

Scope names use dot-notation to implement a relational hierarchy as described Scope Names and Selectors above. Scope names are quoted strings and are case-sensitive.

There is only one type of attribute associated with a scope at this time, color(), and only one attribute per scope. The color attribute has four real number parameters representing an RGBA (red, green, blue and alpha) color space. The valid range for each color element is clamped from 0.0 to 1.0.

Note:  To distinguish real numbers from integers, real numbers must include a decimal point and at least one digit before and after the decimal point (no spaces).

Note:  In the future, color attributes can be expressed as a vector of three or four integers ranging from 0 to 255 or as a hexadecimal number as often used for HTML e..g #FF5733.

Three Color Schemes (so far)

Why only three color schemes? And why these?

At present, Iron supports just three color schemes (found under the Themes main menu drop-down). They are Monokai (default), DarkViking Legacy, and Black on White.

Monokai is the default theme that is in popular use. It meets the current fad in software and art tools that lean toward darker themes. For computer programmers who like to focus and engage deeply with their source code, Monokai is comfortable, the syntax highlighting is easy to interpret and the scheme complements working at night or in a subdued lighting environment.

DarkViking Legacy is Iron’s author’s long-time preference. In fact, this color scheme goes back to the early days of the Brief text editor (by Underware) when 256 color modes were just coming into vogue on PC-ATs. 16 colors was the norm and generally based on combinations of the primary colors (red, green and blue) either at full intensity or off. It’s a little bit “rainbowy” but works well in lots of lighting conditions.

Black on White is for working in brightly lit environments such as when Iron’s development hits the road and the author taps out new features sitting in the great outdoors. New programmers who are mostly familiar with editing in Word, Google Docs or writing blog entries will find this color scheme a natural transition from word processing to source code editing. Eventually, the lack of color, which makes syntax highlighting difficult to interpret, will likely lead coders to seek more informative color schemes.

You can customize the colors in any of these three schemes but creating entirely new scope sets is not yet possible. In the future, you will be able to create and name as many color schemes your creative mind desires.

Warning:  Don’t change the names of the three scope sets.

TLDR:  To change scope sets requires turning on one scope set and turning off all other scope sets defined in the iron.scopes file. The Monokai and DarkViking Legacy scope sets employ clear type fonts while Black on White does not for higher contrast. The scope file does not yet support font attributes for specifying the clear type support so it’s temporarily hardcoded internally. That is, most technically, the reason there are only three color schemes at present.

Scope Sets, Schemes, Themes or Skins?

So is a scope set a color scheme, a theme or skin or what? Well, to answer this requires a quick description of Iron’s future. But let’s start with the present…

A scope set is simply a collection of scopes that can be referenced by Iron. Since only colors can be defined, a scope set equates to a color scheme. Down the road, scopes can refer to sizes, shapes and other attributes and referenced by themes.

An Iron theme, in addition to selecting a syntax-highlighting color scheme, will also define the components of what folks refer to as a skin. During Iron’s early development (the present), Iron employs a Steampunk theme with pipes, globes, brass and glass objects as part of its skin. The Steampunk theme can be turned off in the Themes drop-down menu but that makes Iron rather dull looking.

Iron themes will go well-beyond just skins and color schemes. The plan is to make the Re-Imagined Workspace a  more immersive environment where each theme will consist of different themed dialogs, icons, animations, audio cues and more. That is, Iron themes will be much more than just a skin and closer to a personality.

Stay tuned.