==============================
 The magic commands subsystem
==============================

.. warning::

   These are *preliminary* notes and thoughts on the magic system, kept here
   for reference so we can come up with a good design now that the major core
   refactoring has made so much progress.  Do not consider yet any part of this
   document final.

Two entry points:

- m.line_eval(self,parameter_s): like today
- m.block_eval(self,code_block): for whole-block evaluation.

This would allow us to have magics that take input, and whose single line form
can even take input and call block_eval later (like %cpaste does, but with a
generalized interface).

Constructor
===========

Suggested syntax::

    class MyMagic(BaseMagic):
        requires_shell = True/False
        def __init__(self,shell=None):


Registering magics
==================

Today, ipapi provides an *expose_magic()* function for making simple magics.
We will probably extend this (in a backwards-compatible manner if possible) to
allow the simplest cases to work as today, while letting users register more
complex ones.

Use cases::

    def func(arg): pass  # note signature, no 'self'
    ip.expose_magic('name',func)
    
    def func_line(arg): pass
    def func_block(arg):pass
    ip.expose_magic('name',func_line,func_block)

    class mymagic(BaseMagic):
        """Magic docstring, used in help messages.
        """
        def line_eval(self,arg): pass
        def block_eval(self,arg): pass

    ip.register_magic(mymagic)


The BaseMagic class will offer common functionality to all, including things
like options handling (via argparse).


Call forms: line and block
==========================

Block-oriented environments will call line_eval() for the first line of input
(the call line starting with '%') and will then feed the rest of the block to
block_eval() if the magic in question has a block mode.

In line environments, by default %foo -> foo.line_eval(), but no block call is
made.  Specific implementations of line_eval can decide to then call block_eval
if they want to provide for whole-block input in line-oriented environments.

The api might be adapted for this decision to be made automatically by the
frontend...


Precompiled magics for rapid loading
====================================

For IPython itself, we'll have a module of 'core' magic functions that do not
require run-time registration.  These will be the ones contained today in
Magic.py, plus any others we deem worthy of being available by default.  This
is a trick to enable faster startup, since once we move to a model where each
magic can in principle be registered at runtime, creating a lot of them can
easily swamp startup time.

The trick is to make a module with a top-level class object that contains
explicit references to all the 'core' magics in its dict.  This way, the magic
table can be quickly updated at interpreter startup with a single call, by
doing something along the lines of::

    self.magic_table.update(static_magics.__dict__)

The point will be to be able to bypass the explicit calling of whatever
register_magic() API we end up making for users to declare their own magics.
So ultimately one should be able to do either::

    ip.register_magic(mymagic) # for one function

or::

    ip.load_magics(static_magics)  # for a bunch of them

I still need to clarify exactly how this should work though.