=======
The Hub
=======

Plugin Oriented Programming is all about namespaces. Plugin interfaces are
dynamic, otherwise they would not be plugins. Therefore, if they need to be
shared with each other, they need to have a communication medium. Instead
of making a complicated API interface for the plugins to communicate, `pop`
allows all of the plugins on the system to be accessed via a shared
hierarchical namespace.

All of the plugins in the application can be reached by traversing the
namespace that is the `hub`. Plugin subsystems can exist on the hub and
plugin subsystems can contain more plugin subsystems and plugins.

The `hub` is not just for plugins. We need to be able to store data
associated with our functions. The data is stored on the `hub` in locations
in the namespace relative to where the functions that use that data reside.

Getting To Know the Hub
=======================

The `hub` is the root of a `pop` project. Before we can start working with
`pop` we must first create the `hub`. In the Getting Started chapter we ran
a command that ships with `pop` called `pop-create`. This created a file called
`run.py`. Typically this file does not need to be modified, it is the only part
of your code that is not a plugin because it creates the hub that all plugins
and plugin subsystems reside on.

Lets take a look at a `run.py` file created by `pop-create`:

.. code-block:: python

    #!/usr/bin/env python3

    import pop.hub

    def start():
        hub = pop.hub.Hub()
        hub.pop.sub.add(dyne_name="poppy")
        hub.poppy.init.cli()

    start()

Well, that was easy! Now we have a `hub`! When working on an existing codebase
it is easy to wonder, "Where did this hub come from?". The `hub` is created in
the `run.py` file and is the first function called.

Once the hub is created and the first function is called, the `hub` is passed
to each function as the first argument. This is similar to how functions in Python
classes receive the `self` variable as the first argument.

The First Subsystem - pop
=========================

When the `hub` is created, it comes pre-loaded with the first plugin subsystem. A
plugin subsystem is often referred to as just a `sub`. This first plugin subsystem
is called `pop`. It contains the tools needed to extend the `hub` and add additional
`subs`.

When calling a reference on the `hub`, the full path to the reference is called. This
allows for all code to always exist in a finite, traceable location.

.. code-block:: python

    #!/usr/bin/env python3

    import pop.hub

    def start():
        hub = pop.hub.Hub()
        hub.pop.sub.add(dyne_name="poppy")
        hub.poppy.init.cli()

    start()

The `pop` `sub` contains a plugin called `sub` which is used for managing `subs`.
Inside we find a simple function called `add`. This function allows for adding
new plugin subsystems onto the `hub`.

The `hub.pop.sub.add` function is very robust, allowing for new plugin subsystems
to be added to the hub in many ways. The most common way is to use *Dynamic Names*
which allows for *Vertical App Merging*. This is covered in much more depth in the
section on *Subs*.

Once the new `sub` has been added to the `hub` it can be referenced. The `hub` is
not a complicated object. Like everything in `pop` it is designed to be easily
understood and simple.

Now that you have a basic understanding of the `hub` we can move on to *Subs*.
After you have a good understanding of *Subs* we can come back to the `hub` and
go into more depth on how these critical components work together.