Customizing

Iron Resource Files

 

 

Iron Resource Files are text files that are compiled and used by Iron to define key bindings, menus, scopes (colors and eventually themes) and macros. Iron’s resource files use Iron’s internal computer language format and compiler called “Zinc”.

Note:  “Iron resource files” and “Zinc files” are synonymous and are used interchangeably throughout this documentation.

This document describes how to compile (and debug) the Iron resource files so you can customize your key bindings, colors and menu options.

Here are links to detailed information about each of Iron’s resource file formats:

Iron Resource Files: Keymaps
Iron Resource Files: Macros
Iron Resource Files: Menus
Iron Resource Files: Scopes

 

We are stuck with technology when what we really want is just stuff that works.

Douglas Adams

English author, essayist, humorist, and satirist; author of The Hitchhiker's Guide to the Galaxy.

Why Customize?

Every editor is slightly different whether you’re writing email, instant messaging, authoring a Word or Google document, sending text messages, making Slack or Facebook posts, filling out web-based entries, adding to your blog or working with source code.

Between different editors, key bindings vary, function keys don’t map the same, text selection works differently, cut-and-paste might have quirks, fonts look different, double- and triple-clicks of the mouse do different things, colors imply information unique to the tool, response speeds differ and more.

As a programmer, it is important that your text editor is one with you, an extension of you, your habits and preferences, anticipating your moves and never a hindrance.

Experienced software developers will use a variety of editors that match the project or the task-of-the-day. They’ll also spend time customizing their editors so they can be as proficient as possible. Iron is built to answer the needs of experienced professionals and still be accessible to beginners and novice programmers who require ease-of-use (and power) right out-of-the-box.

As  programmers, we spend many, many hours working with and staring at our text editors. It is our primary, daily, minutely used tool. If it doesn’t look good, function properly, is boring,  not engaging or having you smile from time to time — are you at your creative best? If key bindings aren’t second nature, text editing becomes a fatiguing chore.

That’s why we recommend that you customize Iron so it works the way you work best.

Iron offers default key bindings that work well for the features Iron has — many of which aren’t available in other editors. Iron’s key mappings tend to emphasize the power of Multi-Selection and are weighted in favor of working in Virtual Space Editing mode.

Eventually, Iron will offer emulation of other popular text editors…as best as possible.

Iron’s Key Binding & UI Design

Iron’s user-interface and editing capabilities are evolving and hence it’s default set of key bindings are evolving.

We’ve evaluated and used many different text editors over decades of programming and one thing is for certain, programmers get emotionally attached to their editors and how they look, feel and function. Clearly there is no one best text editor and no best set of key bindings.

Rather, each text editor has its strengths and weaknesses. Each editor’s UI and key bindings are, at best, a workable compromise leveraging tradition with new functionality and novel mechanics. Having customizable UI elements allows any editor to better meet the specific needs of the user, providing a higher level of familiarity and an easier learning curve.

Iron with its unique set of features and its strengths also attempts to leverage old and new.  We’ve worked  to balance Iron’s default key bindings so Iron empowers a broad range of programmers while remaining similar to traditional bindings. At the same time, we hope to offer new editing efficiencies via new key bindings and editing modes. This is a challenging  equation to balance and one that we will continue to evolve and improve.

Again, use the default key bindings as a starting point to get comfortable with Iron. We encourage you to consider the defaults as soft recommendations to develop efficient habits, then customize Iron so it works well for you.

Here are some of the design elements, along with our philosophies, that we hope to have incorporated into Iron:

  • Addressing and balancing novice and experienced programmer needs.
  • Expose users to Iron’s unique editing and graphical feature sets.
  • Emulate  commonly used and expected mappings where logical.
  • Depart from traditional (or nonsensical) mappings if there’s a clear gain.
  • Emphasize and encourage use of the Multi-Selection power-feature.
  • Emphasize the advantage and efficiency  of Virtual Space Editing. We believe it is better for working with source code.
  • Recognize that exact emulation of other editors is not possible.
  • Tradition vs efficiency? Neither one is always the best answer.
  • Every editor is different, unavoidably and that’s good. Choose the right tool for the job.
  • Keep the learning curve as low as possible.
  • Reduce fatigue, enhance productivity, inspire.
  • Source code editing is different than writing prose.
  • Though subjective, be as consistent and predictable as possible.
  • Navigation is power & knowledge.
  • More keyboarding, less mousing around.
  • Keep the caret on-screen, no text changes unseen by the user.
  • Be responsive using speed and assertive interaction, no hidden actions.
  • Save the work and reuse previous effort (undo/redo selections, not just edited text).
  • Seek wildly new efficiencies in editing e.g. Iron Professional Mode and Sticky Selections.

One important choice we’ve made in the key bindings is to reserve the Ctrl+Shift modifier pair for use with Multi-Selection. We feel that Multi-Selection, once learned, is a power tool that warrants this emphasis. Unfortunately, this also means that some common or traditional key mappings may be in conflict and must be supported with different key combos.

Iron Resource Files

There are four types of Iron resource files installed into your Documents directory. They can be found in these resource directories:

\Documents\DarkViking Software\Iron v00.xx\resources\keymaps
\Documents\DarkViking Software\Iron v00.xx\resources\macros
\Documents\DarkViking Software\Iron v00.xx\resources\menus
\Documents\DarkViking Software\Iron v00.xx\resources\scopes

Other documentation will detail the format, content and purpose of each type of resource files. At present, Iron supports only one file per format:

iron.keymap  —  keymap bindings (shortcuts)
iron.menu      —  defines the menus
iron.macro     —  macros used by key bindings and the menu system
iron.scope     —  defines colors used for graphical and syntax elements

They can be loaded using the Tools menu or via the Command Palette (F8).

Warning:  The Zinc grammar used by all of the Iron’s resource files is in flux and will evolve. Before uninstalling or updating Iron, be sure to manually save any changes you have made to the original files. In the future, Iron will preserve or upgrade customizations.

The Command Palette, too, will evolve and additional interactive customization via the menu system will be provided in the future.

Compiling Zinc Files (Build/Committing)

To compile an Iron resource file (also called a Zinc file), it must first be loaded.

As an example, we’ll change the background color for text panes. Compiling the other resource files works exactly the same.

Let’s load the Iron’s scope file. Either use the Tools|Scopes|Load Scope File menu item or open the Command Palette (press F8) and type iron.scope and Enter.

Zinc formatted files typically have a header comment, a namespace and then user-customizable components. In the case of a scope file, only scope_sets are defined which amounts to defining colors with more CSS-like capabilities coming in the future. The scope format will be described in greater detail in other documentation.

Scroll down to this line in the scope_molokai() section:

scope_add( “pane.text”, color( 0.152941, 0.156862, 0.133333, 1.0 ) );

Change the first number to 0.3 and then press F7 to compile (build) your change:

scope_add( “pane.text”, color( 0.3, 0.156862, 0.133333, 1.0 ) );

This will increase the red component of the text pane’s background color so it looks more brown than gray. Iron will issue a “fling” (a 3D notification) that says “Build Successful!”

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

Note:  Support for hexadecimal colors and RGBA integer values from 0 to 255 will be coming.

Comments:  Side comments start with double-backslashes \\. Use of \* and *\ designates a block comment similar to that used in C or C++. Blank lines and whitespace are ignored.

Continuous Compilation

By default, Iron is continuously compiling Zinc formatted resource files as-you-type.

Change the spelling of any of the keywords or remove some of the punctuation and you can see that Iron alters the syntax highlighting to red (error) or other warning colors.

Continuous compilation can be turned off using the Command Palette (press F8):

continuous_compile_toggle = false

With continuous compilation active, Iron is not only compiling the Zinc file as it is being edited, it is also verifying that references to functions (built-in actions) and macros that might be located in other Zinc files are all properly resolved and that parameters are of the correct type.

Pressing F7 to compile a Zinc file is actually just committing to changes that have already been compiled as-you-type. Assuming there are no errors, changes to an Iron resource file are effective immediately upon committing to them with F7.

When Iron commits to a Zinc file change, the menu system is automatically unloaded and then reloaded to reflect any changes that may affect menu items.

Debugging Iron Resource Files

When Iron compiles and resolves Zinc files (which is normally as-you-type), it may encounter warnings or errors.

Whenever there are warnings or errors, Iron will use alternate syntax highlighting colors to indicate where the issue is. It will also drop a fling (a 3D notification) saying either “Build warning” or “Build error”.

The Status pane will list all the warnings and errors and their file:line:character positions. Use View|More Layouts|Double Vert Status menu item or Ctrl+Shift+Alt+F2 to change to a pane layout that includes the Status pane.

Note:  Iron’s window/pane docking system will offer more options and flexibility in the future e.g. it will allow resizing, organizing panes into custom layouts and use of the Status pane in any layout.

Use F4 to move the caret to the next Zinc warning or error (Shift+F4 for the previous issue). Iron will issue a 3D fling indicating what the problem is. If the issue occurs in another file, Iron will load it and go to the problem in that file.

Since Iron is compiling as-you-type, you can make piecemeal changes to a Zinc file then press F4 to go quickly to where a problem exists. If there are no warnings or errors, Iron issues a 3D fling saying “Uncommitted changes: No warnings or errors.” Changes won’t be applied until you press F7 to commit to them.

Note:  In some case, Iron cannot determine the exact location of the error and may move the caret to the top of the file or may load another Zinc file and move to the top of that file. This is a rare situation which generally indicates an external reference problem (e.g. unknown macro). As a workaround, make a change to the file, recompile all Zinc files with Shift+F7, undo the change, then recompile all again.

When committing to changes with F7 and there are errors, Iron will not use the invalid Zinc file and continue to use that last good set of Iron resource files.

If there are only warnings, Iron will commit to the changes but may ignore invalid key bindings or fail to resolve macro references used by the menu system. It’s best to fix all warnings so the full set of Iron resource files work as expected.

Re-Building All Resource Files

Though there is really no need, all of the Iron resource files can be re-compiled and built from scratch by typing Shift+F7.

Behind-the-Scenes Zinc File Info

When Iron executes for the first time after installation, it compiles all of Iron’s resource files and preserves binary versions in the user’s session directory. It also maintains the compilation results (errors and warnings) in binary logbook files as bookmarks. They are located in the Documents directory:

\Documents\DarkViking Software\Iron v00.xx\user\sessions\iron

Generally, you won’t need to be concerned with the binary files at all. However, being beta software, you might find a need to delete any or all of them and Iron will re-generate them as needed.

Iron uses the binary files for speed at startup. The Zinc text files will be re-compiled only if their file dates differ from when they were last compiled.

Lexers

Lexers (language syntaxes) are defined using the Zinc file format and will be available for user-defined custom lexers in the near future. This will allow you to create and customize syntax highlighting for computer languages of your choice using the same Zinc compiling and debugging commands described above.

Until that time, Iron has two built-in lexer options: Plain Text and Slang.

You can chose between the two using the Tools|Syntax Highlighting drop-down menu.

Note: Choosing the Slang syntax turns on syntax highlighting but is only used for Iron Resource Files and files using the file name extensions listed below:

.keymap
.macro
.menu
.scope
.slang
.cpp
.c
.hpp
.h
.y

This is a limitation that will be removed once Zinc lexer files are supported allowing any syntax to be assigned per file regardless of file name extension.

Of Interest:  Iron is written using DarkViking Software’s proprietary computer language Slang. Hence, the Slang language syntax highlighting is the only one available at this time. It works moderately well for C and C++. Better support for all languages is coming soon.

Key Binding and Command Palette Summary

Shortcut/hotkey combos used for working with Iron resource files:

F7                                             —  Compile (Build/Commit) a Zinc file
Shift+F7                               —  Re-compile all the Iron resource files
F4                                             —  Goto the next Zinc compilation warning or error
Shift+F4                               —  Goto the previous Zinc  warning or error
F8                                             —  Command Palette
Ctrl+Shift+Alt+F2         —  Change the pane layout to show the Status pane
Ctrl+Shift+F1                   —  Change to a single pane layout

Command Palette commands used for working with Iron resource files:

iron.keymap                      —  To load Zinc files…press Enter
iron.macro
iron.menu
iron.scope
continuous_compile_toggle = false    —  To turn off continuous compilation