Renders a template text to a resolved text value using the mako template
    system.
    
    Provides a much more robust template option to the projex.text system.  
    While the projex.text method can handle many simple cases with no
    dependencies, the makotext module makes use of the powerful mako template
    language.  This module provides a simple wrapper to the mako code.
    
    To learn more about mako and its usage, see [[www.makotemplates.org]]
    
    :param      text        <str>
    :param      options     <dict> { <str> key: <variant> value, .. }
    
    :return     <str> formatted text
    
    :usage      |import projex.makotext
                |options = { 'key': 10, 'name': 'eric' }
                |template = '${name.lower()}_${key}_${date.today()}.txt'
                |projex.makotext.render( template, options )

def render(text,
           options=None,
           templatePaths=None,
           default=None,
           silent=False,
           raiseErrors=False):
    """
    Renders a template text to a resolved text value using the mako template
    system.
    
    Provides a much more robust template option to the projex.text system.  
    While the projex.text method can handle many simple cases with no
    dependencies, the makotext module makes use of the powerful mako template
    language.  This module provides a simple wrapper to the mako code.
    
    To learn more about mako and its usage, see [[www.makotemplates.org]]
    
    :param      text        <str>
    :param      options     <dict> { <str> key: <variant> value, .. }
    
    :return     <str> formatted text
    
    :usage      |import projex.makotext
                |options = { 'key': 10, 'name': 'eric' }
                |template = '${name.lower()}_${key}_${date.today()}.txt'
                |projex.makotext.render( template, options )
    """
    if not mako:
        logger.debug('mako is not installed.')
        return text if default is None else default

    if templatePaths is None:
        templatePaths = []

    # use the default mako templates
    basepath = os.environ.get('MAKO_TEMPLATEPATH', '')
    if basepath:
        basetempls = basepath.split(os.path.pathsep)
    else:
        basetempls = []

    templatePaths += basetempls

    # update the default options
    scope = dict(os.environ)

    scope['projex_text'] = projex.text
    scope['date'] = date
    scope['datetime'] = datetime
    scope.update(_macros)

    if options is not None:
        scope.update(options)

    if templatePaths:
        lookup = mako.lookup.TemplateLookup(directories=templatePaths)
        try:
            templ = mako.template.Template(text, lookup=lookup)
        except StandardError:
            output = text if default is None else default
            if not silent:
                logger.exception('Error compiling mako text')
            return output
    else:
        try:
            templ = mako.template.Template(text)
        except StandardError:
            output = text if default is None else default
            if not silent:
                logger.exception('Error compiling mako text')
            return output

    try:
        output = templ.render(**scope)
    except StandardError:
        if raiseErrors:
            raise
        output = text if default is None else default
        if not silent:
            logger.exception('Error rendering mako text')
        return output

    return output