.. meta::
   :description: Unicon development tools
   :keywords: unicon, icon, development, tools

=================
Development Tools
=================

.. Modified: 2019-10-27/04:44-0400 btiffin
.. Copyright 2016 Brian Tiffin
.. GPL 3.0+ :ref:`license`
.. This file is part of the Unicon Programming documentation.

.. image:: images/unicon.png
   :align: center

.. only:: html

    :ref:`genindex`
    :floatright:`<a href="http://unicon.sourceforge.net/">Unicon</a>`

.. index:: tools

.. _tools:

Unicon tools
============
The main Unicon command set is made up of:

- unicon
- icont
- iconx
- iconc

.. todo:: complete the list of core tools

After a source build with Unicon 13, the :file:`bin/` directory includes:

.. command-output:: ls -gGF --time-style=+
   :cwd: ../../../unicon/bin/

--------
   
.. index:: !unicon

.. _unicon:

The unicon command
------------------
:command:`unicon` is the main command line tool for programming with Unicon.

.. blockdiag::

    blockdiag {
        Source.icn [shape = note];
        Source.icn -> unicon -> Translate;
    
        Link [stacked];
        Executable [shape = note];
        group {
            shape = line;
            style = dashed;
            orientation = portrait
    
            Translate -> Link -> Executable;
        }
    }

Options include:

.. command-output:: unicon --help
   :returncode: 1

:command:`unicon` is a wrapper around other tools, mainly the :ref:`icont
<icont>` command. Many of the command lines options are similar, but
:command:`unicon` does a better job of explaining the options in the brief
help.

Compiled unicon
...............
``C`` compiled Unicon, to be more specific, seeing as Unicon already compiles.

:command:`unicon -C` translates Unicon to C intermediates and then compiles
the C code (usually via native assembler source) to native executable for the
system in use. Some Unicon features are not available when using
:command:`unicon -C`, such as native concurrency at this point in time.  


Quiet unicon
............
Yeah, this :strike:`is` was a little tricky.

*Update: as of revision* `[r4497] <https://sourceforge.net/p/unicon/code/4497/>`_
*this entire sequence has been simplified*. Just use :command:`unicon -s`. 

Left in for anyone running pre `[r4497] <https://sourceforge.net/p/unicon/code/4497/>`_
Unicon.

.. command-output:: unicon version.icn
   :cwd: examples

Let's try ``-quiet`` (it's undocumented in ``-help``)

.. command-output:: unicon -quiet version.icn
   :cwd: examples

Umm, not quite, how about ``-s``, *work silently*. 

.. command-output:: unicon -quiet -s version.icn
   :cwd: examples

So close. Now to set verbosity to 0.

.. command-output:: unicon -quiet -s -v0 version.icn
   :cwd: examples

Ahh, that'd be the ticket.  Quiet, silent, not verbose.  

::

    -quiet -s -v0
 
.. command-output:: unicon -quiet -s -v0 version.icn -x
   :cwd: examples

*Update as above:* Just use :command:`unicon -s`.

The flip side is pretty easy; maximum verbosity.

.. command-output:: unicon -v3 version.icn -x
   :cwd: examples


--------

.. index:: !icont

.. _icont:

The icont command
-----------------
:command:`icont` is the translator portion of the Unicon tool chain.

Options include:

.. command-output:: icont
   :returncode: 1

:command:`icont` is a relatively sophisticated compiler, most error messages
are quite comprehensive, detailing what it wrong with the source code.

.. literalinclude:: examples/compiletime-error.icn
   :language: unicon
   :start-after: ##+

.. command-output:: icont compiletime-error.icn
   :cwd: examples
   :returncode: 1

``::=`` is not valid assignment syntax.

Like most high level compilers, sometimes the error messages are, *less
helpful*:

.. todo::  ADD SAMPLE

And sometimes, you need to wait until execution time, and triggering an error at run-time.

.. literalinclude:: examples/runtime-error.icn
   :language: unicon
   :start-after: ##+

Sample run, with error:

.. command-output:: unicon runtime-error.icn -x
   :cwd: examples
   :returncode: 1

:ref:`integer` can't be added to a :ref:`list` datatype, *in this case, an
integer coerced from a string*.

See :ref:`testing` for some details on testing ``Unicon`` programs.


--------

.. index:: !iconx

.. _iconx:

The iconx command
-----------------
:command:`iconx` is the Executor portion of the Unicon tool chain.

:command:`iconx` takes the filename to execute.

The Icon Virtual machine, and :command:`iconx`, report any runtime errors, in
a relatively comprehensive manner.
 
.. literalinclude:: examples/runtime-error.icn
   :language: unicon
   :start-after: ##+

.. command-output:: unicon -c runtime-error.icn
   :cwd: examples

:command:`iconx` processes :ref:`icode` files, which are binary executable
forms created during the link phase from :ref:`ucode` files.

.. command-output:: iconx runtime-error
   :cwd: examples
   :returncode: 1

A segue into :file:`.u` files, :ref:`ucode`, and the Icon Virtual Machine.

:file:`.u` files are Icon cross platform machine instructions, as human readable
source (this feature helped with the design and debugging of the virtual
machine).

For example, the above buggy :file:`runtime-error.icn` was translated to
:file:`runtime-error.u`,  and is a human readable form of the Icon Virtual
Machine language.

.. literalinclude:: examples/runtime-error-ucode.u
   :language: ucode

If you look at the first few lines of a :command:`unicon` compiled program, it
is actually a script that starts :command:`iconx` with the :ref:`ucode`
embedded in it.

.. command-output:: unicon runtime-error.icn
   :cwd: examples

.. command-output:: cat -v runtime-error | par
   :cwd: examples
   :shell:

--------


.. index:: conventions, style

.. _conventions:

Coding conventions and style
----------------------------
Unicon has a long history, and :ref:`ralph` tried to keep a consistent look
and feel to both the compiler internal C/rtt sources and the high level Icon
programs submitted to the :ref:`ipl`.  That effort was not 100% successful,
and the many hands that have touched on the C code each brought a slightly
different style preference.  One of the most startling format issue may be the
mixing of tab characters and spaces for code indentation.  The convention
guide (https://www2.cs.arizona.edu/icon/docs/ipd072.htm) requests spaces, but
there are tabs in the sources and over time, various text editors have made
the code look a little sloppy in terms of nested indentations.  Keep to the
request, and use spaces, as it avoids this long term churn issue with source
code and text editor treatment of tabs.

:ref:`ipl` entries seem to have fared better over the years in terms of
consistent look.  That is likely due to the more public nature and numbers of
interested readers, when compared to the internal source files.

In summary:

- Indentation: Three spaces per level, with no tabs for indentation.

- Line length: Not to exceed 80 characters with tabs expanded.

- Inter-line spacing: At most one empty line as needed for visual clarity.
  Formfeed (^L) between function declarations (except where there are many
  short, similar functions). Generally one empty line prior to boxed comments.

- Function declarations: storage/type class on line with function name. No
  indentation on argument declarations. Function body, including braces and
  local declarations indented three spaces. Braces enclosing functions on
  lines by themselves.

- Braces: Beginning brace at end of line for construction involved (except for
  function declarations as noted above). Ending brace on separate line
  indented three spaces beyond position of opening construction.

- ``if`` statements: statement below conditional expression, indented three
  spaces. If ``else`` is present, on separate line aligned with corresponding
  ``if``.

- Binary operators: one space on either side.

- Argument lists: one space after each comma.

- Return statements: no parentheses around argument of ``return``.

- Casts: no space between right parenthesis surrounding cast and the
  expression to which it applies.

- ``typedef``\ s: generally all lowercase (a deliberate departure from usual C
  conventions; typedefs in the Icon source code are viewed as an extension
  of the C language).

- Comments: Boxed-style per numerous examples. Second and subsequent lines
  indented one character. "On-line" comments tabbed out as is most readable.
  No "cute" or illiterate comments. No personal identifications (they cease
  to be useful with time and produce cumulative clutter).

- Conditional compilation: One empty line before and after ``#ifdef/endif``
  groups. Identifying C-style comment five tabs out on ``#else`` and
  ``#endif`` directives. (*I think by 5 tabs out, Ralph meant column 40*).

- Manifest (defined) constants and macros: For the most part, names should
  be in mixed upper- and lowercase (a deliberate departure from usual C
  conventions). Specifically, an uppercase letter identifies a name that has
  been defined as opposed to a C variable. Mixed case is used for readability. 

This convention guide carries over to Unicon sources and :ref:`ipl` entries,
where appropriate. In particular, IPL entries all start with a consistent
comment block, formatted to allow the indexing tool to properly do its job.
See the ``ipl-skeleton.icn`` listed below for this formatting standard. 

.. note::

    The examples in this docset all break rule one.  I prefer 4 space indents.
    The bracing rule is also broken, preferring to not indent the closing
    brace, but to keep it at the same indentation as the starting
    construct.

    Apologies, but that is the way it is.

    With that said, reasonable effort is expended to maintain an internal
    consistency.

The convention guide calls for code formatting ala:

.. sourcecode:: unicon

    while line := read(f) do {
       result := stuff(line)
       morestuff(result)
       }
    continuing()

This document uses a style of the form:

.. sourcecode:: unicon

    while line := read(f) do {
        result := stuff(line)
        morestuff(result)
    }
    continuing()

Blame age and long ingrained personal preference for the breach of project
preferred convention.

It behooves any Unicon programmer to get used to many forms and coding styles,
as for the most part, due to many hands in the pot, you may encounter
different formatting in any one particular source file. A key issue is to
strive for consistency and to attempt some level of source formatting
discipline.

--------


.. index:: tools

.. _externaltools:

Supporting tools
================

Unicon works very well with most of the common software development tools
available for various operating systems.  This docset focuses on GNU/Linux,
but other systems also offer a wide range of useful development aids.

Unicon also ships with a fair number of support tools, custom built for Unicon
development.

.. image:: images/xkcd-1739-fixing-problems.*
   :align: center
   :alt: XKCD Fixing Problems

::

    "'What was the original problem you were trying to fix?' 'Well, I noticed one
    of the tools I was using had an inefficiency that was wasting my time'"

.. only:: html

    .. rst-class:: rightalign

        *XKCD* http://xkcd.com/1739/ by Randall Munroe :ref:`CC BY-NC 2.5 <CC BY-NC 2.5>`

.. only:: not html

    *XKCD* http://xkcd.com/1739/ by Randall Munroe :ref:`CC BY-NC 2.5 <CC BY-NC 2.5>`

--------


.. index:: make

.. _make:

make
----

:program:`make` is not a Unicon specific program, but works very well with
Unicon development. :command:`make` is also used when building Unicon from
source.

See https://www.gnu.org/software/make/manual/make.html for details of the
ubiquitous GNU implementation of make.

:command:`make` normally uses a non visible Tab character (ASCII 9) to prefix
action lines.  GNU make includes an extension to specify a different prefix
character.  The example below, and other examples throughout this
documentation use a more visible ``>`` action statement prefix. This is not
supported in all versions of :command:`make`, but it makes copy and paste from
web pages a little safer, as it removes any chance of a Tab character being
mistaken for spaces.

Some sample recipes:

.. literalinclude:: examples/Makefile
   :language: make
   :start-after: ##+

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/Makefile`

:command:`make program` will compile :file:`program.icn` if the source is more recent
than the target executable, :command:`make run` will run the program (and ensure it
is up to date before execution, if sources have changed).  :makevar:`$<` is an
automatic :command:`make` variable, set to match the first prerequisite.  For the
``program:`` target, the first (and only) prerequisite is :file:`program.icn`. For
the sample ``run:`` target, the prerequisite is ``program``, and :makevar:`$<` is
substituted in to execute :command:`./program`.

:command:`make` is a fairly powerful tool.  There are quite a few features that may
not be apparent at first glance.  See the GNU make manual referenced above for
more details.

A special note on the trick ``%: %.icn`` and ``%.u: %.icn`` targets. Those are
:command:`make` patterns that match any named Unicon source file,
:file:`name.icn`, and compiles and/or runs the program. It is a convenience
feature for non-project related make. It allows any Unicon file to be compiled
and run by simply typing :command:`make name`. If the source has already been
compiled (date of executable is later than the date time of last edit), just
use :command:`./name`, or use :command:`make -B name` to force a new compile
and run. To compile a source file for use with :ref:`link`, the same trick
allows :command:`make name.u`, to match the :file:`name.icn` file, and then
run :command:`unicon -c` on the given name.

Again, those are convenience features, normally a Makefile is specific to a
project and the targets will include specific instructions for clean up,
packaging, installation, etcetera, and will list all prerequisite source
files, not singletons as used with the trick filename matching rules.

--------


.. index:: ui

.. _ui:

ui
---
The Unicon IDE. :command:`ui` ships with Unicon, under the :file:`uni/ide`
subdirectory, and is built along with :command:`unicon` and the other command
line tools, ready to use with any Unicon installation that supports the 2D
graphics facilities.  A graphical front end for Unicon development, detailed
in Technical Report UTR12a, http://unicon.org/utr/utr12.html

The :program:`Ui` source code provides lots of examples for extending and customizing
a graphical user interface generated using :ref:`IVIB`, the interface building
tool.

:program:`Ui` supports project management, file management, a contextual help based
source code editor, a class browser, along with Compile, Run and Debug layers.

*I'll be honest, I develop on the command line, with* :ref:`Vim` *and
associated tools*.  If you prefer Integrated Development Environments, be
sure to fire up :command:`ui`.

*Might have to pester Clinton about opening up the font selection list; the
four X11 fonts that ship with Unicon are not as beautiful as some that are
now available for GNU/Linux.*


--------
 
.. index:: udb, debugger

UDB
---

The Unicon debugger.  A very comprehensive Unicon support tool.

Modelled on ``GNU gdb``, :command:`udb` allows breakpoints, Unicon source
view, structure display, and many other high and low level debugging features
using a command prompt interface.

UDB, by Ziad Al-Sharif, is documented in Unicon Technical Report 10.

http://unicon.org/utr/utr10.html

See :doc:`debugging` for more details.


--------

.. index:: IVIB, vib

.. _IVIB:

.. _vib:

IVIB
....
A visual, graphical user interface building tool.  Drag and drop user
interface elements to generate Unicon code.

--------

.. index:: VM

.. _VM:

The Icon Virtual Machine
========================

.. _ucode:

ucode
-----
ucode is source form virtual machine instructions, transportable between all
platforms.  The translator generates ucode as an intermediate form ready for
the link stage. ``ucode`` was named before Unicon, as part of the Icon
project.

Starting small, smaller than Hello in this case.

.. literalinclude:: examples/onestatement.icn
   :language: unicon
   :start-after: ##+

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/onestatement.icn`

Producing :t:`ucode` from this source gives a close to minimum set of VM
instructions required for the Unicon VM.

Processed via :command:`unicon -c`

.. command-output:: unicon -c onestatement.icn ; sed -i 's/\x0C//' onestatement.u
   :cwd: examples
   :shell:

Generates a link ready :t:`ucode` file, :file:`onestatement.u`. [#u2]_

.. literalinclude:: examples/onestatement.u
   :language: ucode

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/onestatement.u`

This assigns the value ``1`` to the local variable, ``u``.  

The :t:`ucode` file also includes some identification, some procedure
paperwork, the statement trace info, and the statement bounding markers, along
with the actual low level instructions to assign a ``1`` to ``u``.

The Unicon virtual machine is stack based. An operational stack is used very
much like a Forth data stack.  Pushing and popping values (which can be
encoded or literal) while performing virtual machine level operations that
functionally match the high level Unicon source instructions. 

The action opcodes here being

.. sourcecode:: ucode

    pnull
    var 0
    int 0
    asgn

Push a null descriptor (a place holder for the expression result). Push the id
of variable 0 from the declarations (the ``u``). Push an integer with id 0
from the constant declarations (a ``1`` in this case). Then assign; ``asgn``
pops the value and destination while performing the assignment operation and
replaces the initial null descriptor with the result (which in more complex
programs would be chained to other parts of an expression).

:t:`ucode` is the human friendly version of :t:`icode`, the actual byte-code
used by the virtual machine.  During initial development of Icon, starting
back in 1978ish, it was deemed important to have a human readable version of
the VM instruction sequencing.  This helped (and still helps) verify and debug
the Icon source code translator.  A nice touch, not really necessary for the
virtual machine itself, but of great importance to the people implementing the
engine and the translator. And a bonus to developers that can peruse the
machine instructions.

As is, this :t:`ucode` requires one more step before being executable code.
The :t:`rt` runtime translator at the heart of the Unicon VM always starts
with :t:`main`.  It gives the engine a starting point, a place to call home
that ensures everything is properly initialized. The translation from
:t:`ucode` to :t:`icode` happens during the linking phase of the Unicon tool
chain.  All :ref:`link` references are included, and :t:`ucode` files merged
and resolved down to :t:`icode`.

Many Unicon programs are singletons, no :ref:`link` statements to worry about,
but every final step :t:`icode` generation requires a :t:`main`.  In this
case, the single statement procedure is compiled separately and included in
the file listed below via the :ref:`link` reserved word.

.. literalinclude:: examples/mainstatement.icn
   :language: unicon
   :start-after: ##+

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/mainstatement.icn`

That piece of code will link to :file:`onestatement.u` and produce an
executable VM image, :file:`mainstatement`.  :file:`mainstatement` sits ready
to be invoked by the operating system to run the program.  A program that
invokes :t:`main` (implicitly), which invokes :t:`onestatement`, which sets
``u`` to ``1``, then runs down, giving control back to the operating system.

For now, we are more interested in looking at the :t:`ucode`, so
:command:`unicon -c` comes into play again.

.. command-output:: unicon -c mainstatement.icn ; sed -i 's/\x0C//' mainstatement.u
   :cwd: examples
   :shell:

.. literalinclude:: examples/mainstatement.u
   :language: ucode

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/mainstatement.u`

We don't really have an executable yet, the Unicon tool chain stopped after
producing the :t:`mainstatement` :t:`ucode` and did not combine the sources
with the runtime engine, nor generate :t:`icode`.

:: 

    prompt$ unicon mainstatement.icn

    Parsing mainstatement.icn: ..
    /home/btiffin/unicon/bin/icont -c   -O mainstatement.icn /tmp/uni18898220
    Translating:
    mainstatement.icn:
      main
    No errors
    /home/btiffin/unicon/bin/icont  mainstatement.u
    Linking:

Without ``-c``, Unicon does the complete pass, including the VM link phase,
and creates a new program, ready to run.

:: 

    ./mainstatement

That pass does nothing visible, but did all kinds of nifty things in the
background.

Hello
.....
Now making it a little more complicated is the Hello, world of :t:`ucode`.

.. literalinclude:: examples/hellostatement.icn
   :language: unicon
   :start-after: ##+

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/hellostatement.icn`

Producing :t:`ucode` from this source gives just enough VM
instructions for Unicon to create a procedure that displays
evidence that a proper installation of Unicon is functional.

Processed via :command:`unicon -c`:

.. command-output:: unicon -c hellostatement.icn ; sed -i 's/\x0C//' hellostatement.u
   :cwd: examples
   :shell:

Generates a link ready :t:`ucode` file, :file:`hellostatement.u`.

.. literalinclude:: examples/hellostatement.u
   :language: ucode

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/hellostatement.u`

Linking that with a ``main`` that calls the small procedure and we have a
Unicon virtual machine program to tell the world that Unicon is functioning
properly (and in this case, doubly so; the translator works and the linker
works, along with the runtime engine).

.. literalinclude:: examples/hellomain.icn
   :language: unicon
   :start-after: ##+

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/hellomain.icn`

Drum roll...

.. command-output:: unicon -c hellostatement.icn ; unicon hellomain.icn -x ; sed -i 's/\x0C//' hellostatement.u
   :cwd: examples
   :shell:

From Unicon source files, through :t:`ucode`, to linked :t:`icode` and final
creation of an executable file. Then automatically invoked (via ``-x``) to
demonstrate a functional Unicon installation by way of a friendly greeting.


.. [#u2]

    Unicon merged :t:`ucode` into a single file.  Icon, separates some of the
    paperwork from the instructions, giving ``.u1`` and ``.u2`` files.  Having
    a single ``.u`` file makes things a little cleaner and more easily
    transportable.

--------


.. _icode:

icode
-----
:t:`icode` is binary form virtual machine instructions, and have an almost one
to one correspondence with :t:`ucode` source.  Some differences will occur
during linkage, the final phase of Unicon translation before executable.  The
executor, :t:`rt`, is the runtime engine invoked by :ref:`iconx` that
evaluates :t:`icode`.  When using GNU/Linux, Unicon create an executable shell
script, that assists with search path settings, and then runs the included
binary :t:`icode` machine instructions.

The :t:`hellomain` file (reformatted for document capture): 

.. command-output:: ./show-icode hellomain
   :cwd: examples


icode support files
...................
:t:`icode` is based on single byte operation codes.

.. literalinclude:: examples/opdefs.h
   :language: c

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/opdefs.h`

Which is manually paired with

.. literalinclude:: examples/odefs.h
   :language: c

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/odefs.h`

There is also a set of Unicon application programmer support files, mainly
used with Execution Monitoring and lower level debugging programs, available
in the :ref:`ipl`.

- :file:`ipl/incl/opdefs.icn`, an include file with all opcode numbers
- :file:`ipl/incl/invkdefs.icn`, with definitions for visualizing the symbols
- :file:`ipl/mprocs/opname.icn`, string names for opcodes
- and a few others peppered throughout the IPL.

In the end, Unicon creates an executable shell program that embeds the
:t:`icode` byte codes for use by the Unicon executor, :t:`iconx` when
producing a virtual machine program image.

The program used above to display the :t:`hellomain` executable is a small
Unicon program, :t:`show-icode.icn`. It relies on the fact that the shell
scripting is separated from the :t:`ucode` by a form feed character. The
shell script lines are displayed by line, and the rest as a hex dump. 

.. literalinclude:: examples/show-icode.icn
   :language: unicon
   :start-after: ##+

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/show-icode.icn`


The Implementation of Icon and Unicon
-------------------------------------

As part of the Unicon release 13 pass, there has been updates occurring to
:t:`The Implementation of Icon and Unicon` book, probably the best place for
details on the design of the Unicon virtual machine.  Sources for :t:`ib.pdf`
ships with the Unicon source kit under :file:`doc/ib`.  Plus it's an excellent
book regarding how to go about building a programming language and the deep
issues that designers face when embarking on the task.
 
--------


.. index:: editors

.. _editors:

Editors
=======
Unicon source code is assumed to be ASCII.  UFT-8 encoding will work, as long
as the characters used stay as single byte code points, in the range 0 to 127.

*This means word processor default formats are not suitable for Unicon
source.*  If you like to use a word processor, make sure the source is saved
as ``Text``.

Literals and data can assume an 8bit range, 0 to 255, but anything beyond
value 127 is at the whim of operating environment settings and default
handling.  Sometimes you will get block looking characters or upside down
question marks, sometimes you will get an extended encoding value like line
drawing characters.  Those non ASCII features are not standard nor cross
platform. 

There are quite a few editors that support Icon in terms of highlighting,
smart indenting and other productivity enhancers; less so with Unicon features
added in.  Listed below is an updated Vim syntax highlighter.

--------


.. index:: Vim

.. _vim:

Vim
---
The world's best text editor. A text processing tool.

Here is a Vim syntax file, customized for Unicon, building on the
:file:`icon.vim` that ships with Vim.

.. literalinclude:: programs/unicon.vim
   :language: vim

.. only:: html

    .. rst-class:: rightalign

        :download:`programs/unicon.vim`

Place that file in :file:`$HOME/.vim/syntax/unicon.vim`.  Then add

.. sourcecode:: vim

    " Unicon - see ~/.vim/ftdetect/unicon.vim
    autocmd BufRead,BufNewFile *.icn     set filetype=unicon

to your :file:`~/.vimrc` Vim startup file.

Or copy this short file type detection file

.. literalinclude:: programs/unicon-ftdetect.vim
   :language: vim

.. only:: html

    .. rst-class:: rightalign

        :download:`programs/unicon-ftdetect.vim`

to :file:`$HOME/.vim/ftdetect/unicon.vim`

*Please note the filename is also* :file:`unicon.vim` *but in the*
:file:`~/.vim/ftdetect/` *directory.  It is renamed here as*
:file:`unicon-ftdetect.vim` *to avoid a name conflict within the documentation
directory structure.*

After saving the syntax file and changes to the file type auto detect system,
whenever you open or edit a file with a :file:`.icn` extension, it will be
highlighted for Unicon syntax.  *As well as working with older Icon sources*.

Once you add the syntax file, you can choose Unicon highlighting for any
Vim buffer by typing the ``ex`` colon command, ``set filetype=unicon``.

As hinted at in :doc:`documentation`, you can also add automatic templates for
new Unicon source files by adding the following to your :file:`~./vimrc`
startup file.

.. sourcecode:: vim

    autocmd BufNewFile  *.icn      0r ~/lang/unicon/header.icn
    autocmd BufNewFile  *.opt      0r ~/lang/unicon/header-options.icn
        \ |0file|file <afile>:s?\.opt?\.icn?|filetype detect 

Change the :file:`~/lang/unicon/header` part to a local site installation
filename.  It will pre-populate new :file:`.icn` files with text from the
template header.

The second Vim ``autocmd`` listed above allows for a more sophisticated
skeleton for programs what will have command line option handling. Use with
:command:`vim filename.opt`.  It loads a more extensive template
(header-options), then renames the buffer to :file:`filename.icn`.  The
:file:`.opt` shortcut relies on having the :file:`unicon.vim` file type
detection code properly installed in :file:`~/.vim/ftdetect`.

At time of writing, my custom templates look like:

:file:`header.icn`

.. literalinclude:: examples/header.icn
   :language: unicon

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/header.icn`

I use :file:`header.icn` quite often, and keep the ``Date:`` line up to date
with the current month.

:file:`header-options.icn`

.. literalinclude:: examples/header-options.icn
   :language: unicon

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/header-options.icn`

Personalize to taste, and save a little typing when you start new Unicon
files.  Plus the added benefit of a consistent look to all of your programs
(which are, by their very nature, the world's best programs).

There is also the Icon Programming Library skeleton, developed by :ref:`ralph`
a long time ago, which is not a bad choice for consistent Unicon programming.

.. index:: skeleton; ipl

.. literalinclude:: examples/ipl-skeleton.icn
   :language: unicon

.. only:: html

    .. rst-class:: rightalign

        :download:`examples/ipl-skeleton.icn`

A well supported, de-facto standard in the Icon world.

--------


.. index:: emacs

.. _emacs:

Emacs
-----
The world's other best text editor.  An operating system that handles text.

Robert Parlett created a Unicon major more for Emacs:

http://www.zenadsl6357.zen.co.uk/unicon/


.. index:: emacs; vim emulation

Evil
----
The Extensible Vi Layer for Emacs, Evil adds features of the world's best text
editor to the world's other best text editor.

https://www.emacswiki.org/emacs/Evil

This is *thee* editor combination.  Emacs (including OrgMode) with Vim key
bindings and modal editing.  Sweet. ``Evil`` is a very complete, robust and
well done Vim emulator, augmenting the powers inherent in Emacs.


.. only:: html
   
    ..

    --------

    :ref:`genindex` | Previous: :doc:`threading` | Next: :doc:`documentation`

    |