Get string version from installed package information.

    It will return :attr:`default` value when the named package is not
    installed.

    Parameters
    -----------
    name : string
        An application name used to install via setuptools.
    default : string
        A default returning value used when the named application is not
        installed yet
    allow_ambiguous : boolean
        ``True`` for allowing ambiguous version information.
        Turn this argument to ``False`` if ``get_string_version`` report wrong
        version.

    Returns
    --------
    string
        A version string or not found message (:attr:`default`)

    Examples
    --------
    >>> import re
    >>> v = get_string_version('app_version', allow_ambiguous=True)
    >>> re.match('^\d+.\d+\.\d+', v) is not None
    True
    >>> get_string_version('distribution_which_is_not_installed')
    'Please install this application with setup.py'

def get_string_version(name,
                       default=DEFAULT_STRING_NOT_FOUND,
                       allow_ambiguous=True):
    """
    Get string version from installed package information.

    It will return :attr:`default` value when the named package is not
    installed.

    Parameters
    -----------
    name : string
        An application name used to install via setuptools.
    default : string
        A default returning value used when the named application is not
        installed yet
    allow_ambiguous : boolean
        ``True`` for allowing ambiguous version information.
        Turn this argument to ``False`` if ``get_string_version`` report wrong
        version.

    Returns
    --------
    string
        A version string or not found message (:attr:`default`)

    Examples
    --------
    >>> import re
    >>> v = get_string_version('app_version', allow_ambiguous=True)
    >>> re.match('^\d+.\d+\.\d+', v) is not None
    True
    >>> get_string_version('distribution_which_is_not_installed')
    'Please install this application with setup.py'
    """
    # get filename of callar
    callar = inspect.getouterframes(inspect.currentframe())[1][1]
    if callar.startswith('<doctest'):
        # called from doctest, find written script file
        callar = inspect.getouterframes(inspect.currentframe())[-1][1]
    # get version info from distribution
    try:
        di = get_distribution(name)
        installed_directory = os.path.join(di.location, name)
        if not callar.startswith(installed_directory) and not allow_ambiguous:
            # not installed, but there is another version that *is*
            raise DistributionNotFound
    except DistributionNotFound:
        return default
    else:
        return di.version