#!/usr/bin/env python
# -*- coding: utf-8 -*-

"""Example of a plugin managing a content type.

TODO: Explain"""

import songbook.content

class Example(songbook.content.Content):
    """Content item of type 'example'."""

    def __init__(self):
        """Initialization.

        No signature is imposed."""
        pass

    def render(self, TODO):
        """Render this content item.

        Returns a string, to be placed verbatim (? TODO) in the generated .tex
        file.
        """
        return ""

    # Block management

    def begin_new_block(self, previous):
        """Return a boolean stating if a new block is to be created.

        # Arguments

        - previous: the songbook.content.Content object of the previous item.

        # Return

        True if the renderer has to close previous block, and begin a new one,
        False otherwise.

        # Default

        The default behavior of this method (if not defined in this child
        class) is: begin a new block if the previous item is not an instance of
        the same class.
        """
        return False

    def begin_block(self, TODO):
        """Return the string to begin a block."""
        return ""

    def end_block(self, TODO):
        """Return the string to end a block."""


def parse(keyword, arguments):
    """Parse songbook .sb content item.

    Takes as argument the keyword triggerring this content, and the list of
    arguments, e.g. for a content item '["picture", "*.png", "*.jpg"]', the
    call of this function is:

    > parse('picture', ["*.png", "*.jpg"])

    Return a list of (subclasses of) songbook.content.Content objects.
    """
    return Example(keyword, arguments)

songbook.content.register('example', parse)