alited

What is this

The alited stands for "a lite editor".

The main features of alited are:

  • structured code
  • easy access to the code
  • born for Tcl/Tk development only

Edited by alited are Tcl/Tk files. The C/C++ code is another target of alited, still for Tcl/Tk development only all the same.

The alited facilitates the development and the maintenance of Tcl/Tk code, particularly because of the unit tree being a sort of documentation.

For a quick acquaintance of alited, a few of demo videos are available:

Below is a screenshot of alited:


... and its localized and themed variant:


Installation

The installation of alited is straightforward:

  • unpack alited.zip to some directory, say ~/PG/alited
  • to run the installed alited, use the command:
    wish ~/PG/alited/src/alited.tcl

In Linux, you can run tclsh instead of wish.

Being written in pure Tcl/Tk 8.6, alited needs only the core Tcl/Tk packages.

If you are a novice to Tcl/Tk 8.6, try and install it. Then try and install the alited and its dependencies, noticing the messages of CLI at running alited. Let the installations be a sort of exercise in Tcl/Tk.

Still in Windows, it's enough to install ActiveTcl or Magicsplat distribution.

In Linux, possibly you need to install the packages:

  • tcl8.6
  • tcllib
  • tk8.6
  • tklib
  • tcl-tls
  • tcl-vfs
  • tclx8.4

As noticed above, the alited is born for Tcl/Tk development only, so it requires a basic Tcl/Tk knowledge and the installed Tcl/Tk packages.

No need for a stand-alone alited executable. Also, the open sources of alited may be used for a further customization.


First start

At the very first start, alited offers some simple initial actions.

Namely: you are offered to choose a directory where alited will store its settings.

The default ~/.config is probably the best choice if you don't have several type of projects at your machine. When you use the default ~/.config, it needs not to be passed to alited as an argument.

On the other side, if you choose some other configuration directory, this directory's name should be passed to alited as an argument.

You can have several copies of your configuration directories, e.g. ~/.config1, ~/.config2 etc. each of them customized for its own type of projects: public/private, for work/fun and so on. For example, you might cunfigure fun projects to have "Florid" color scheme or a big funny font for editing.

I have two configuration directories of alited - one for developments, one for releases of alited to test.


Units

The alited is unit oriented which is its main feature.

This means making a unit tree of Tcl code, with branches and leaves.

The branches are created with special comments. The leaves are Tcl procedures and methods.

For example:

#! /usr/bin/env tclsh
#
# It's just an example.

# ________________ Packages used _____________ #
package require Tk

# ________________ "example" _________________ #
#
# Some words about...

namespace eval example {

  ## ___________ example's variables _________ ##

  variable var1 "value 1"
  variable var2 "value 2"

  ## __________ example's procedures _________ ##
  #
  # Below are procedure doing so and so.

  # this proc prints one
  proc one {} {puts "one"}

  # this proc prints two
  proc two {} {puts "two"}

  ## _________________ "my" __________________ ##
  #
  # Some words about...

  namespace eval my {

    ### ___________ my's variables ___________ ###
    variable var1 "val1"

    ### ___________ my's procedures __________ ###


    proc myone {} {puts "my one"}
    proc mytwo {} {puts "my two"}

    # this proc prints "my three"
    proc mythree {} {puts "my three"}

  ## ______________ end of "my" ______________ ##
  }

# _____________ end of "example" _____________ #
}
# _____________________  EOF _________________ #

This example will produce the following unit tree:

ROOT
  |__ Lines 1-4
  |__ Packages used
  |   "example"
  |     |__ example's variables
  |     |__ example's procedures
  |     |     |__ one
  |     |     |__ two
  |     |__ "my"
  |     |     |__ my's variables
  |     |     |__ my's procedures
  |     |           |__ myone
  |     |           |__ mytwo
  |     |           |__ mythree
  |     |__ end of "my"
  |__ end of "example"
  |__ EOF
This example is small and easy to observe. Its tree view doesn't differ greatly from the code view.

In a real life, a code isn't easily observed even with bird's eye view or with code folding.

And here alited comes to help.

The unit tree doesn't means anything like code folding or structured editing which refer to the Tcl structural commands like if, switch, foreach, proc and so on. The alited unit tree results from the hierarchical comments only.

The unit tree includes the unit comments as the branches and the procedures / methods as the leaves.

The unit comments are customized, e.g. #=== NAME === may be used instead.

The first # characters define the unit tree's level: # means 1, ## means 2, ### means 3 etc. It isn't reasonable to customize and use # NAME # and ## NAME ## and ### NAME ### etc. for the unit tree's levels, because any comment beginning with # would be treated as a unit.

Still, if you want to use # alone (without adding _ = - + ~ * . : etc.), you can customize alited so that ## will mean 1st level, ### 2nd level, #### 3rd level etc., using a branch regexp like this:

^\s*#(#+)\s+([^_]+[^[:blank:]]*)
thus allowing the tree comments as follows:
## Initialize GUI
  ...some code
  ### This widget group
    ... this code
  ### That widget group
    ... that code
The alited recognizes the units by these comments and presents them as a tree.

To insert a tree branch into your code, use the key combinations:

  • Shift+F1 for 1st level
  • Shift+F2 for 2nd level
  • Shift+F3 for 3rd level

You can add 4th, 5th... branches' levels, as well as change the default keys to use.

To add a procedure / method, use:

  • Alt+P to add a procedure
  • Alt+M to add a method

The unit tree has its own toolbar allowing to arrange the tree.

The Up / Down buttons allow to move unit(s) through the tree.

In fact, they are moved through a code, so that you can arrange your code without cut/copy/paste. Only moving units.

To move a group of units, select them with Ctrl+click.

Also, you can drag-and-drop a unit before a target location of the unit tree.

When you navigate through the unit tree, the cursor positions are saved/restored in visited units. You can continue with units in the same positions you left them.

Any unit of any file of a project can be marked/unmarked as favorite. The "Favorites" list allows quick opening a favorite unit.

Each project has its own list of favorites.

If some favorites' list is valuable, you can save it by its own name to return to these favorites afterwards. For this, use "Favorites' Lists" button of the toolbar or the appropriate item of menu.

These saved favorites' lists can be considered as subprojects inside a project.

The Last Visited list is a comrade of the favorites. It allows fast access to the last visited units. The last visits are registered at clicking units in the unit tree or at clicking found lines in the info listbox.

In a session, the visited units are highlighted in the unit tree, so that you can see which of them were visited. The more observed, the more navigated.

Two search modes might be very useful while you are dealing with the units:

  • Search Units
  • Go to Line

After pressing Ctrl+Shift+F you get "Search Units" bar where you can search units by their case insensitive glob patterns. Very useful.

After searching just click an info listbox to enter a found unit.

You can also set "Don't focus a text" mode in order to scan the found units with keys.

Once called, "Search Units" bar might remain.

After pressing Ctrl+G you get "Go to Line" dialogue where you can go inside a unit by its relative number of line.

It's useful when you get a Tcl error message with a proc / method name and a line number.

The alited provides a tool to check Tcl code for consistencies of brackets. In fact, it allows to find "problem" units.

It's useful when you get a peculiar error message.

At checking Tcl code, please, pay attention to a whole content of a unit, i.e. all lines between its start and a next unit's. Some "errors" are natural and eliminated by "END of namespace" or similar branches. See the above example.

The unit tree and the file tree are switched to / from by appropriate buttons of the tree toolbar.


Projects

The alited is a project oriented editor, not a general purpose one.

The alited provides nearly all the necessary to develop Tcl/Tk projects without ever quiting it till a machine's shutdown.

The projects seen by alited are stored in ~/.config directory chosen at the very first start of alited.

You can pass a config directory's name as an argument to alited. This allows you to have various types of projects at one machine: public/private, for work/fun... configuring them properly.

The projects are listed in "Setup / Projects" menu item. Also, you can click "Projects" icon of the tool bar.

The default project refers to alited's installation directory, just for a start.

At creating a new project, you must fill the appropriate data fields - most importantly a project directory.

After filling the new project's fields you should press "Add" button to create it.

To open a project, just select it in the project list, then hit "Select" button.

To open existing file(s) of your project you can switch to the project file tree. Then, with double-clicking a file, you open it.

To open all Tcl files of a directory, use the tree's context menu.

The open files are highlighted in the file tree. When a file is closed it's unhighlighted.

A newly open file is placed in the very beginning of the tab bar. This is true even when you select a tab bar file which isn't among the visible tabs.

Press Ctrl+Tab keys to switch between last two edited files. "Last visited is most needed."

If your currently edited file doesn't belong to the current project directory, you can move this file to it. For this, use "Move File" buttons. The buttons allow to move files in the project subdirectories.

There are also "Create File/Directory" options of the file tree available through the tree's context menu.

When projects are switched, alited saves and restores:

  • a list of open files
  • cursor positions in the files
  • a currently open file
  • a list of favorites
  • a list of favorites' lists
So, when you switch to another project, alited closes all files of the old project and open all files of the new project.

If you want some files of the old project to remain open in the new project, select them in the tab bar by Ctrl+click, then switch to the new project.

Few words about an interesting project option.

The "Unit lines per 1 red bar" option means that each N lines of a unit would add a red bar to its icon at the unit tree, up to 7th bar.

When the icon becomes fully red, this is like sending you "a bit too long unit" message, i.e. the unit probably needs a sort of reforming.

There are 8 grades of redness: 0, 1*N, 2*N, 3*N ... 7*N. So, if N=20, then 141 lines would mean "a too long unit". Just look at the unit tree to detect those horrible reds, candidates for reforming.

For example, look at bar::FillBar of the above screenshot: its row range is 27..80, total 54 which gives two red bars.


Along with the unit facilities, alited provides other tools for a navigation throughout a project. One of them is "Find / Replace" tool, called with:

  • Ctrl+F keys
  • "Edit / Find/Replace" in menu
  • "Find / Replace" in toolbar

The "Find / Replace" dialogue contains two sections:

  • Find
  • Replace
Both contain 3 buttons:
  • do it once
  • do it in text
  • do it in session

The alited has the find and replace functions united in this dialogue.

The dialogue provides standard options of such type. Probably, except for one of them.

The "Replace by blank" option means that you can replace the found strings by the blank string which means just deleting the found strings!

As the blank replacements are rarely required, the "Replace by blank" option allows to avoid mistakes. Use it accordingly.

All of the found instances in text / session are presented in the info listbox.

The info listbox allows to go to a found instance's line, with just clicking it. At that, the "Find / Replace" dialogue may or may not be closed.

While the "Find / Replace" dialogue is open, the found strings are highlighted. When you close the dialogue, the highlighting disappears.

The info listbox has a context menu allowing to navigate through its items just with keys (Up / Down / Ctrl+Home / Ctrl+End).

If you select some tabs of the tab bar with Ctrl+click, the "Find / Replace" dialogue will offer Find/Replace "In selected files" (including a current one) instead of "In all files of session".

The "Find / Replace" dialogue allows to replace the found strings with a new one. At single replacements, next found strings are presented one by one.

Other search facilities of alited are:

  • Find a unit
  • Find a declaration
  • Find a word
  • Find in a directory

Press Ctrl+Shift+F or hit "Edit / Find Unit" menu item to find unit(s) by case insensitive glob patterns. It's very helpful when you remember a part of a unit's name, so just enter this part to find the unit. The part to find can include glob's characters: *, ?, [abc]

To look for a proc/method declaration, you can try:

  • Ctrl+click on its name
  • press Ctrl+L, when the cursor is on its name
  • hit "Edit / Look for Declaration" menu item

To complete a command, press Tab key while the cursor is on initial characters of a command - this will offer you to select from a list of commands available in alited session's files. The Tab key of this option is changeable (like many other keys) in "Setup / Preferences / Keys".

At the completion, the commands offered to choose are:

  • not qualified for a current file
  • qualified for others

For a quick search of a word (or a selected text), there is a nice Ctrl+Shift+click applied to the word. It means a search throughout alited session and is very helpful in some cases. Though, the very first Ctrl+Shift+click can take 1-2 seconds of your day. Excuse me.

To find a word or a selection in a directory hit the appropriate button of the toolbar. The search will be performed by "grep" command with options:

  • recursively in a chosen directory
  • case insensible

Other "grep" facilities are available in "e_menu" run with F4 key. For example, you can search in selected files of current alited session. The selection is set by Ctrl+clicking the tabs.


Tools

The tools of alited are presented by its tool bar and menu. Thus, they are called "bar/menu" tools.

Some of tools are provided by alited staticly i.e. they cannot be removed:

  • Run
  • e_menu
  • tkcon
  • Check of Tcl
  • Color Picker
  • Screen Loupe
  • Tcl/Tk help (in "Help" menu)

Other tools are collected in "Tools / bar/menu" submenu. These are provided by e_menu application. All of them (even installed by default) can be removed or substituted with other tools.

In fact, "Run" and "Tcl/Tk help" are both provided by e_menu application. Namely:

  • "Run" is "Run me..." item of menu.mnu
  • "Tcl/Tk help" is one of e_menu's "ornamental items"

The "Run" tool tries to run an application chosen as default for the currently edited file. For Tcl files, it is "tclsh".

But e_menu recognizes special comments like:

#RUNF1: file.tcl args
which mean running "tclsh file.tcl args".

So, it's possible to run a main Tcl script at editing any Tcl script of an application.

The "Setup / Before Run" menu item allows to set command(s) to be executed before "Run" tool, sort of preparatory steps. You can enter several commands, one command per a line.

The "Tcl/Tk help" tool shows Tcl/Tk man page for a word the cursor is on. Or for a selected text.

Still, this context help is available only if Tcl/Tk help pages are downloaded and copied to ~/DOC/www.tcl.tk/man/tcl8.6 directory
... or when Internet is accessible. In such case, e_menu tries to get a help page from https://www.tcl.tk/man/tcl8.6/ which might be not what you want.

In alited, tkcon tool is customizable a little. To do this, open from alited's menu "Setup / Preferences / Tools / tkcon". There is a Test button allowing to preview your settings.

Some tools, though default, can be changed or removed. These tools are listed in "Tools / bar/menu" submenu and are customized in "Setup / Preferences / Tools".

This settings are also available through a popup menu called by right click on the toolbar.

In this dialogue, we can:

  • add new actions and separators
  • change actions or their icons
  • remove actions and separators

New items are added by [+] button. Or you can use empty rows at the bottom.

Items are removed by [x] button.

Empty items are ignored. The list of items is scrollable.

To choose a tool, click its button at the right. Any non-menu items can be chosen directly while navigating through menus. If you want to choose a whole submenu, right click on this submenu and choose "Select" from a popup menu. Note: the main menu is run by e_menu tool.

To change a tool's icon, click its drop-down list. There are available icon-pictures and icon-characters. Highly likely, there is an icon expressing the tool's action.


Editing

There are several sources of editing features provided by alited.


1. Context menu

With right-clicking a text, you get a context menu containing:

  • Cut / Copy / Paste commands

  • Undo / Redo commands

  • Line processing commands:

    • Double Selection (Ctrl+D keys customized in "Setup / Preferences / Keys")
      if there is no selected text, a current line is duplicated

    • Delete Line (Ctrl+Y keys customized in "Setup / Preferences / Keys")

    • Line(s) Up (Alt+Up keys)
      if several lines are selected, all of them are moved up

    • Line(s) Down (Alt+Down keys)
      if several lines are selected, all of them are moved down

  • Highlight processing commands:

    • Highlight First (Alt+Q keys customized in "Setup / Preferences / Keys")

    • Highlight Last (Alt+W keys customized in "Setup / Preferences / Keys")

    • Highlight Previous (Alt+Left keys)

    • Highlight Next (Alt+Right keys)

    • Highlight All (double click on a word)
      if there is a selected text, this menu item highlight all its instances

  • Select All (Ctrl+A keys)


2. Edit menu

The menu bar of alited provides Edit menu containing:

  • Move Unit Up command (F11 key customized in "Setup / Preferences / Keys") applied to a current unit, moves it up

  • Move Unit Down command (F12 key customized in "Setup / Preferences / Keys") applied to a current unit, moves it down

  • Indent command (Ctrl+I keys customized in "Setup / Preferences / Keys")

  • Unindent command (Ctrl+U keys customized in "Setup / Preferences / Keys")

  • Correct Indentation
    applied to a Tcl file (a whole of it)

  • Comment command (Ctrl+[ keys customized in "Setup / Preferences / Keys")

  • Uncomment command (Ctrl+] keys customized in "Setup / Preferences / Keys")

  • Put New Line command (Ctrl+P keys customized in "Setup / Preferences / Keys")

  • Find / Replace command (Ctrl+F keys)
    when Ctrl+F pressed twice, performs a search in a last mode (once, in text, in all)

  • Find Next command (F3 key customized in "Setup / Preferences / Keys")

  • Find Declaration command (Ctrl+L keys customized in "Setup / Preferences / Keys")

  • Find Word command (Ctrl+Shift+L keys customized in "Setup / Preferences / Keys")

  • Find Unit command (Ctrl+Shift+F keys)
    when Ctrl+Shift+F pressed twice, performs a search

  • Go to Line command (Ctrl+G keys customized in "Setup / Preferences / Keys")

Note again: when Ctrl+F (or Ctrl+Shift+F) keys are pressed twice, a search is performed immediately.


3. Templates

The templates are available in "Setup" menu and through "Add Unit" button of the tree toolbar.


4. Keys setup

A few of keys are customized in "Setup / Preferences / Keys" menu.


5. Miscellaneous keys

The alited provides also some keys that aren't presented in menus. These are:

  • Ctrl+Tab switches between last two edited files

  • Alt+Backspace switches between last two visited units

  • Ctrl+Enter (Shift+Enter) adds a new line without indentation

  • Ctrl+Up moves the cursor to a previous paragraph

  • Ctrl+Down moves the cursor to a next paragraph


Options

The alited's "Setup" menu provides "Project", "Templates", "Favorites' Lists" and "Preferences" dialogues.

All of the dialogues contain "Help" button, at their bottom left corners. Use it at need.

The alited's "Setup" menu provides some options outside of the dialogues:

Tint

This option allows to change a tint of a current color scheme. It's per a session only.
When all of sudden you get a feeling that too much of light / darkness is around, this option might help.

Tip File Info

This option allows to view an information of file attributes displayed in tips of the tab bar and the file tree.

Before Run

This option allows to set command(s) that would be executed before "Tools / Run". It's per a project.
You can set as many commands as you like, one command per a line.
These commands are sort of initialization depending on a project.