def help() :
    """print 'clean' help"""
    log.info(log.YELLOW + 
            "fips clean\n" 
            "fips clean all\n"
            "fips clean [config]\n" + log.DEF + 
            "    clean generated build files for config")

def help() :
    """print config help"""
    log.info(log.YELLOW + 
            "fips config\n" 
            "fips config [config]\n" + log.DEF + 
            "   configure the current or named build config\n"
            "   (runs ccmake or cmake-gui)")

def check_imports(fips_dir, proj_dir) :
    """do various checks on the imports of a project

    :param fips_dir: absolute fips directory
    :param proj_dir: absolute project directory
    :returns:   True if checks were valid
    """

    # check whether any imported projects are in sync with the remote git repo
    success, imported_projects = get_all_imports_exports(fips_dir, proj_dir)
    num_imports = 0
    for imp_proj_name in imported_projects :
        imp_proj_dir = util.get_project_dir(fips_dir, imp_proj_name)

        # don't git-check the top-level project directory
        if imp_proj_dir != proj_dir :
            num_imports += 1
            log.info("git status of '{}':".format(imp_proj_name))
            if os.path.isdir(imp_proj_dir) :
                if git.check_out_of_sync(imp_proj_dir) :
                    log.warn("  '{}' is out of sync with remote git repo".format(imp_proj_dir))
                else :
                    log.colored(log.GREEN, '  uptodate')
            else :
                log.warn("  '{}' does not exist, please run 'fips fetch'".format(imp_proj_dir))
    if success and num_imports == 0 :
        log.info('  none')

    # gather imports, this will dump warnings
    gather_imports(fips_dir, proj_dir)

def help():
    """print 'make' help"""
    log.info(
        log.YELLOW + "fips make\n"
        "fips make [target]\n"
        "fips make [target] [config]\n" + log.DEF + "   build a single target in current or named config"
    )

def write_git_ignore(proj_dir, entries) :
    """modify or create the .gitignore file with fips-specific
    entries. fips entries will go into a special section marked with:
        #>fips
        #<fips

    :param entries: array of fips .gitignore strings
    """
    path = proj_dir + '/.gitignore'
    out_lines = []
    if os.path.isfile(path) :
        # .gitignore already exists, read into lines array,
        # but drop everything between #>fips and #<fips
        with open(path, 'r') as f :
            in_lines = f.readlines()
        copy_line = True
        for l in in_lines :
            if '#>fips' in l :
                copy_line = False
            if copy_line :
                out_lines.append(l)
            if '#<fips' in l :
                copy_line = True
    
    # append the fips .gitignore entries
    out_lines.append('#>fips\n')
    out_lines.append('# this area is managed by fips, do not edit\n')
    out_lines.extend('\n'.join(entries) + '\n')
    out_lines.append('#<fips\n')

    # write back .gitignore file
    with open(path, 'w') as f :
        f.writelines(out_lines)

    log.info("wrote '{}'".format(path))

def check_local_changes(fips_dir, proj_dir) :
    """this is a variation of check_imports which just checks for local
    (uncommitted or unpushed) changes.

    :param fips_dir: absolute fips directory
    :param proj_dir: absolute project directory
    :returns:   True if checks were valid
    """
    success, imported_projects = get_all_imports_exports(fips_dir, proj_dir)
    num_imports = 0
    for imp_proj_name in imported_projects :
        imp_proj_dir = imported_projects[imp_proj_name]['proj_dir']

        # don't git-check the top-level project directory
        if imp_proj_dir != proj_dir :
            num_imports += 1
            log.info("checking '{}':".format(imp_proj_name))
            if os.path.isdir(imp_proj_dir) :
                if git.has_local_changes(imp_proj_dir) :
                    log.warn("  '{}' has local changes (uncommitted and/or unpushed)".format(imp_proj_dir))
                else :
                    log.colored(log.GREEN, '  no local changes')
            else :
                log.warn("  '{}' does not exist, please run 'fips fetch'".format(imp_proj_dir))
    if success and num_imports == 0 :
        log.info('  none')

def help() :
    """print 'gdb' help"""
    log.info(log.YELLOW +
            "fips gdb [-- args]\n"
            "fips gdb [target] [-- args]\n"
            "fips gdb [target] [config] [-- args]\n" + log.DEF +
            "   debug a single target in current or named config")

def help() :
    """print help text for init verb"""
    log.info(log.YELLOW +
             "fips setup emscripten\n"
             "fips setup android\n"
             + log.DEF +
             "    setup cross-platform SDK") 

def copy_template_file(fips_dir, proj_dir, filename, values, silent=False) :
    """copy a template file from fips/templates to the project 
    directory and replace template values (e.g. the project name),
    ask for user permission if files exist

    :param fips_dir:    absolute fips directory
    :param proj_dir:    absolute project directory
    :param filename:    filename to copy from fips/templates
    :param values:      template key/value dictionary
    :param silent:      if True, overwrite existing file and don't print status
    :returns:           True file overwritten, False on not overwritten
    """
    
    src_path = fips_dir + '/templates/' + filename
    dst_path = proj_dir + '/' + filename

    if not os.path.isfile(src_path) :
        log.error("template src file '{}' doesn't exist".format(src_path))
    
    if not silent :
        if os.path.isfile(dst_path) :
            if not util.confirm("overwrite '{}'?".format(dst_path)) :
                log.info("skipping '{}'".format(dst_path))
                return False

    content = None
    with open(src_path, 'r') as f :
        content = f.read()
    content = Template(content).substitute(values)
    with open(dst_path, 'w') as f :
        f.write(content)

    if not silent :
        log.info("wrote '{}'".format(dst_path))
    return True

def help():
    """print run help"""
    log.info(
        log.YELLOW + "fips run [-- args]\n"
        "fips run [target] [-- args]\n"
        "fips run [target] [config] [-- args]\n" + log.DEF + "   run a build target for current or named config"
    )

def list_configs(fips_dir, proj_dir) :
    """list available configs"""
    log.colored(log.YELLOW, '=== configs:')
    configs = config.list(fips_dir, proj_dir, '*')
    for folder in configs :
        log.colored(log.BLUE, 'from {}:'.format(folder))
        for cfg in configs[folder] :
            log.info('  {}'.format(cfg))

def help():
    log.info(log.YELLOW +
        "fips markdeep build [proj]\n"
        "fips markdeep view [proj]\n"+log.DEF+
        "    Generate or view Markdeep documentation webpage.\n"
        "    Parses all *.h files in a project, searches for special\n"
        "    /*# #*/ comment blocks, and extracts them into Markdeep\n"
        "    HTML files.")

def write_workspace_settings(fips_dir, proj_dir, cfg):
    '''write the CLion *.xml files required to open the project
    '''
    log.info("=== writing JetBrains CLion config files...")
    clion_dir = proj_dir + '/.idea'
    if not os.path.isdir(clion_dir):
        os.makedirs(clion_dir)
    write_clion_module_files(fips_dir, proj_dir, cfg)
    write_clion_workspace_file(fips_dir, proj_dir, cfg)

def help() :
    """print 'set' help"""
    log.info(log.YELLOW + 
            "fips set config [config-name]\n"
            "fips set target [target-name]\n" 
            "fips set jobs [num-build-jobs]\n"
            "fips set ccache [on|off]\n"+ log.DEF +
            "    config: set active build config\n"
            "    target: set active run target\n"
            "    jobs:   set number of parallel build jobs\n"
            "    ccache: enable/disable using ccache")

def help() :
    """print help for diag verb"""
    log.info(log.YELLOW +
             "fips diag\n"
             "fips diag all\n"
             "fips diag fips\n"
             "fips diag tools\n"
             "fips diag configs\n"
             "fips diag imports\n"
             + log.DEF +
             "    run diagnostics and check for errors")

def list_settings(proj_dir) :
    """list settings file content"""
    log.colored(log.YELLOW, '=== settings:')
    if util.is_valid_project_dir(proj_dir) :
        for key in ['config', 'target', 'jobs', 'ccache'] :
            value = settings.get(proj_dir, key)
            if type(value) is bool :
                value = 'on' if value else 'off'
            default = ' (default value)' if value == settings.get_default(key) else ''
            log.info('  {}{}:{} {}{}'.format(log.BLUE, key, log.DEF, value, default))
    else :
        log.info('  currently not in a valid project directory')

def check_configs(fips_dir, proj_dir) :
    """find configs and check if they are valid"""
    log.colored(log.YELLOW, '=== configs:')
    dirs = [ fips_dir ]
    configs = config.load(fips_dir, proj_dir, '*')
    for cfg in configs :
        log.colored(log.BLUE, cfg['name'])
        valid, errors = config.check_config_valid(fips_dir, cfg)
        if valid :
            log.colored(log.GREEN, '  ok')
        else :
            for error in errors :
                log.info('  {}'.format(error))

def _rec_fetch_imports(fips_dir, proj_dir, handled) :
    """internal recursive function to fetch project imports,
    keeps an array of already handled dirs to break cyclic dependencies

    :param proj_dir:    current project directory
    :param handled:     array of already handled dirs
    :returns:           updated array of handled dirs
    """
    ws_dir = util.get_workspace_dir(fips_dir)
    proj_name = util.get_project_name_from_dir(proj_dir)
    if proj_name not in handled :
        handled.append(proj_name)

        imports = get_imports(fips_dir, proj_dir)
        for dep in imports:
            dep_proj_name = dep
            if dep not in handled:
                dep_proj_dir = util.get_project_dir(fips_dir, dep_proj_name)
                log.colored(log.YELLOW, "=== dependency: '{}':".format(dep_proj_name))
                dep_ok = False
                if not os.path.isdir(dep_proj_dir) :
                    # directory did not exist, do a fresh git clone
                    dep = imports[dep_proj_name]
                    git_commit = None if 'rev' not in dep else dep['rev']
                    if git_commit :
                        if 'depth' in dep :
                            # when using rev, we may not want depth because the revision may not be reachable
                            log.colored(log.YELLOW, "=== 'depth' was ignored because parameter 'rev' is specified.")
                        dep['depth'] = None
                    git_depth = git.clone_depth if not git_commit and 'depth' not in dep else dep['depth']
                    git_url = dep['git']
                    git_branch = dep['branch']
                    if git.clone(git_url, git_branch, git_depth, dep_proj_name, ws_dir) :
                        if git_commit :
                            log.colored(log.YELLOW, "=== revision: '{}':".format(git_commit))
                            dep_ok = git.checkout(dep_proj_dir, git_commit)
                        else :
                            dep_ok = True
                    else :
                        log.error('failed to git clone {} into {}'.format(git_url, dep_proj_dir))
                else :
                    # directory already exists
                    log.info("dir '{}' exists".format(dep_proj_dir))
                    dep_ok = True

                # recuse
                if dep_ok :
                    handled = _rec_fetch_imports(fips_dir, dep_proj_dir, handled)

    # done, return the new handled array
    return handled

def confirm(question):
    """ask user to confirm (y/N)

    :param question:    the question to confirm
    :return:            True: user pressed 'y', False: user pressed 'n'
    """
    validAnswers = {"": False, "yes": True, "ye": True, "y": True, "no": False, "n": False}
    while True:
        sys.stdout.write(question + " [y/N]: ")
        choice = raw_input().lower()
        if choice in validAnswers:
            return validAnswers[choice]
        else:
            log.info("please respond with 'y', 'yes', 'n' or 'no'")

def help() :
    """print help text for list verb"""
    log.info(log.YELLOW +
             "fips list\n"
             "fips list all\n"
             "fips list configs\n"
             "fips list build-tools\n"
             "fips list build-types\n"
             "fips list generators\n"
             "fips list registry\n"
             "fips list settings\n"
             "fips list targets [config]\n"
             + log.DEF +
             "    list available configs, build-tools, etc...")