.. @+leo-ver=5-thin
.. @+node:ekr.20100808120531.4283: * @file nutshell.txt
.. @@language rest
.. @@tabwidth -4

.. @+at @rst-options
..  call_docutils=False
..  code_mode=False
..  generate_rst=True
..  http_server_support = False
..  show_organizer_nodes=True
..  show_headlines=True
..  show_leo_directives=True
..  stylesheet_path=..\doc
..  write_intermediate_file = True
..  verbose=True
.. @@c

.. @+all
.. @+node:ekr.20100808120531.4284: ** @rst html/nutshell.html
#################
Leo in a Nutshell
#################

This page introduces Leo's features and shows why Leo is a unique tool for
understanding and manipulating data.

**Outlines and organization**: Leo's outlines are more flexible and powerful
than any other outline, for at least three reasons:

1. Unlike class browsers, you are in complete control of the outline's
   structure. You can organize it however you like, and Leo will *remember* what
   you have done and will show it to you just that way when come back next time.
   This seems like a minor feature. After you use Leo, you will see that it is
   not.

2. Leo outlines may *look* like other outlines, but in fact Leo outlines are
   views of a more general underlying data (graph) structure. Nodes in Leo's
   outlines may appear in many places in the same outline. We call such nodes
   **clones**. Using clones, it is easy to create as many **views** of the data
   in the outline as you like. In effect, Leo becomes a supremely flexible
   filing cabinet: any outline node may be filed any place in this cabinet.

3. Leo outlines are intimately connected to both external files and Python
   scripting, as explained next.

.. index::
    pair: External file; Nutshell

**External files**: Any outline node (and its descendants) can be "connected" to
any file on your file system. Three common kinds of connection are:

1. @edit: Leo reads the entire external file into the @edit node's body text.

2. @auto: Leo parses the external file and automatically creates an outline that
   shows the structure of the external file, just as in typical class browsers.

3. @file: Leo makes a two-way connection between the @file tree (the @file node
   and its descendants) and the external file. You can update the external file
   by writing the Leo outline connected to it, or you can update the outline by
   changing the external file. To do this Leo uses comments in the external file
   called **sentinels** that represent the outline structure *in the external
   file itself*.

\@edit, \@auto and \@file allow you to share external files with others in a
collaborative environment. With \@file, you also **share outline structure**.

A single Leo outline can connect to dozens or even hundreds of external files.
Using Leo, you never have to open these files by hand, Leo does so automatically
when it opens the Leo outline. Outlines connected to external files make Leo a
new kind of IDE (Integrated Development Environment).

**Scripting**: Every outline node can contain Python scripts. Moreover, each
node in a Leo outline is a programmable object. All nodes are *easily* available
to any Leo script. The structure of the outline is *also* easily available to
any script.  Scripts can *easily* determine the parents and children of any node.
Finally, Leo makes it easy for scripts to visit any or all nodes of an outline.

.. index::
    pair: @kind convention; Nutshell
    pair: User-defined types; Nutshell

Leo's headlines provide a natural place to indicate the **type** of data
contained in nodes. By *convention*, @test in a headline denotes a unit test,
\@command creates a new Leo command. The \@kind convention creates 
**user-defined types** that turn any outline Node into a true programming
object.

.. index::
    pair: Leonine; Nutshell

Unifying scripting, data and outline structure creates a new world. We use the
term **Leonine** to denote the Leo-centric (outline-centric) view of
programming, data and scripting. Here are some of the implications of this
new world:

**Data organization**: Leo's clones allow unprecedented flexibility in
organizing data. Leo outlines have been used as an entirely new kind of
database. It is easily scriptable. As my brother has shown, it is possible to
design Leo outlines so that parts of the outline *are* SQL queries!

**Design**: With Leo, you always see the big picture, and as many of the details
as you like. But this makes outlines ideal for representing designs. In fact,
Leo outlines don't just represent designs, they *are* the designs. For example,
all of Leo's source code reside in just a few Leo outlines. And Leo outlines can
represent input data to other design tools.

**Programming/Coding**: It's much easier to program when the design is always
easily visible. Nodes provide the perfect way to organize large modules, classes
and functions. Nodes also provide unlimited room to save as many details as you
like, *without* cluttering your overall view of the task, or rather tasks, at
hand.

**Testing**: Leo is a supremely powerful unit-testing framework:

1. You can make a node a unit test simply by putting @test at the start of its
   headline. Leo will then automatically generate all the blah-blah-blah needed
   to turn the node's script into a fully-functional unit test. Oh yes,
   the headline becomes the name of the unit test.

2. Unit tests can use data in children of @test nodes. Typical tests put input
   data in one child node, and the expected results of running the test in another
   child node. The test simply compares the actual and expected results.

3. You can easily run tests in the entire outline or just in the selected
   outline. Because tests reside in nodes, you can use clones to organize tests
   in as many ways as you like. For example, it is trivial to run only those
   tests that are failing.

**Maintenance and support**: Leo's ability to contain multiple views of data is
*precisely* what is needed while maintaining any large project. For every new
support task and every new bug, a new (plain) **task node** will contain all the
data needed for that task, notes, test data, whatever. Furthermore, when fixing
bugs, the task node can contain clones of all classes, methods or functions
related to the bug. Fixing a node in the task node fixes the node in the
external file! And as always, you can use all of Leo's outlining features
(including clones) to organize your task nodes.

**Organization everywhere**: Have you noticed that Leo's organizational prowess
applies to *everything*? Indeed, you can use outlines and clones in new ways to
organize files, projects, data, design, programs, testing, and tasks. Leo
doesn't need lots of features--outlines, clones and scripts suffice.  The more
complex your data, designs, program and tasks, the better Leo is suited to them.

It's time to mention one of Leo's most unique features.  Simple, *optional*
markup makes it possible to synthesize (build) scripts and entire computer programs
from outlines. Leo is more than a filing cabinet for scripts and programs, Leo
is a build tool for scripts and outlines!

**Scripting everything**: Let's step back a moment. A single outline can contain
databases, designs, actual computer code, unit tests, test scripts and task
nodes. But Leo scripts will work on any kind of node. Thus, it is *easy* to run
scripts on *anything*! Examples:

- Scripting itself: @button nodes creates a **script button**, a Python script
  that can be applied to any node in an outline! Script buttons have been
  written (in Python) that will execute Leo scripts in other languages.

- Data: The @kind convention for headlines tells scripts what a node contains
  without having to parse the node's contents.  The possibilities are endless.

- Design: scripts can verify properties of design based on either the contents
  of design nodes or their outline structure.

- Coding: scripts routinely make massive changes to outlines. Scripts and unit
  tests can (and do!) verify arbitrarily complex properties of outlines.

- Scientific programming: Leo scripts can run experiments many times using
  different starting points. Nodes are the perfect place to store results and
  notes. Many scientists use the IPython shell-- Using Leo's **IPython bridge**,
  Leo can execute IPython scripts, and scripts in IPython have full access to
  all nodes in Leo outlines.

- Testing: scripts can (and do!) create @test nodes themselves.

- Maintenance: scripts could gather statistics about tasks using simple @kind
  conventions.

The Leo Aha is just this: Leo outlines are far more than eye candy. Leo outlines
revolutionize your view of data--Leo outlines can organize *anything*. Leo
outlines create a new kind of programming environment, one in which outline
structure and user-defined data types create totally new opportunities.
.. @-all
.. @-leo
