<?php
/**
*   Class with all functionality needed to create the index for the
*   php-gtk2-doc search class.
*
*
*   Index explanation:
*   - Only full words are found. If you search by "wind", "window" will *not* be found.
*   - up to 2 with "_" connected full words are found, e.g. when searching for "this_is",
*       the file "this_is_a_long_name" will be found, but searching for "this_is_a" will not
*       bring the former result, as only 2 directly connected words are indexed.
*       Note that full method names are indexed, too: "this_is_a_long_name" will be found
*       by searching for "this_is_a_long_name"
*   - The index is prioritized. This means that results are sorted by priority:
*       (Example search: "window")
*       - class names will be first
*           found: gtk.gtkwindow.php, gdk.gdkwindow.php
*       - methods which contain the search word in method name are second
*           found: gdk.gdkdragcontext.property.dest_window.php
*       - methods with the search word not in the direct method name are third
*           found: gdk.gdkwindow.method.lower.php
*
*   @author Christian Weiske <cweiske@php.net>
*/
class PhpGtkDoc_Search2_Index
{
    protected static $arReserved = array(
        'atk', 'gtk', 'gdk', 'scn', 'pango', 'method',
        'property', 'prop', 'field', 'enum', 'signal', 'constructor'
    );
    protected static $arReservedMethods = array(
        'get', 'set'
    );



    /**
    *   Creates the search index.
    *   Required parameters are the documentation directory
    *   and the index file, as which the index shall be stored.
    */
    public static function createIndex($strDocumentationDirectory, $strIndexFile)
    {
        if (!file_exists($strDocumentationDirectory) || !is_dir($strDocumentationDirectory)) {
            throw new Exception('Documentation directory does not exist: ' . $strDocumentationDirectory);
        }
        if ((file_exists($strIndexFile) && !is_writable($strIndexFile))
             || (!file_exists($strIndexFile) && !is_writable(dirname($strIndexFile)))) {
            throw new Exception('Index file is not writable: ' . $strIndexFile);
        }

        file_put_contents($strIndexFile,
            serialize(
                self::buildIndexFromFiles(
                    self::getFiles($strDocumentationDirectory),
                    $strDocumentationDirectory
                )
            )
        );
    }//public static function createIndex($strDocumentationDirectory, $strIndexFile)



    /**
    *   Creates an index array from the given files.
    *   The filenames are meant to be relative to the doc directory,
    *   so that e.g. "gdk/gdk.functions.html" or
    *   "gdk/gdk.gdkcolormap.method.get_screen.html" are in it.
    *
    *   The index array has the following structure:
    *   [keyword]
    *       - [1] priority level
    *           - [doc file 1]
    *           - [doc file 2]
    *       - [2] priority level
    *           - [doc file 1]
    *           - [doc file 2]
    *       - [3] priority level
    *           - [doc file 1]
    *           - [doc file 2]
    *
    *   Priorities:
    *   1   class names, tutorial names, ...
    *   2   methods, signals, enums
    *   3   methods which have the keyword in the class name
    *
    *   @param array    $arFiles    Array with all the files
    *   @param string   $strDocumentationDirectory  The directory which the file names are relative to
    *
    *   @return array   The index array, can be used with PhpGtkDoc_Search2
    */
    protected static function buildIndexFromFiles($arFiles, $strDocumentationDirectory)
    {
        $arIndex = array();

        $arCamelCaseWords = self::getCamelCaseWords(
            self::getTitles(
                self::getTitleFiles(
                    $arFiles
                ),
                $strDocumentationDirectory
            )
        );

        foreach ($arFiles as $strFile) {
            $strBaseFile = basename($strFile);
            $strBaseFile = substr($strBaseFile, 0, strrpos($strBaseFile, '.'));
            $arPieces    = explode('.', $strBaseFile);
            //remove reserved words so that they are not indexed
            //$arPieces   = array_diff($arPieces, self::$arReserved);
            //when uncommenting the last line, change all "$nCountWords > 2" to "$nCountWords > 1"

            $arNewPieces    = array();
            $nCountWords    = count($arPieces);
            $nWordPos       = -1;
            foreach ($arPieces as $strWord) {
                $nWordPos++;//the indices do not have constant values (array_diff)
                if ($nWordPos == $nCountWords - 1 && $nCountWords > 2) {
                    //last word in the filename
                    $nPriority = 2;
                } else {
                    //not the last word in the filename
                    $nPriority = 1;
                }
                $arNewPieces[$nPriority][] = $strWord;//the word itself
                if (isset($arCamelCaseWords[$strWord])) {
                    $arNewPieces[$nPriority] = array_merge($arNewPieces[$nPriority], $arCamelCaseWords[$strWord]);
                }
/*
                $strPrefix      = substr($strWord, 0, 3);
                if ($strPrefix == 'gtk' || $strPrefix == 'gdk' || $strPrefix == 'atk' || $strPrefix == 'pan') {
                    //pango is 5 chars, all others are 3
                    $nCutPos = $strPrefix == 'pan' ? 5 : 3;

                    //classes have gtk or gdk at the beginning, e.g. gtkfixed or gtkoptionmenu
                    $arNewPieces[$nPriority][] = substr($strWord, $nCutPos);
                    if (isset($arCamelCaseWords[$strWord])) {
                        $arNewPieces[$nPriority] = array_merge($arNewPieces[$nPriority], $arCamelCaseWords[$strWord]);
                    }
                }
*/
                $arMethodPieces = explode( '_', $strWord);
                if (count($arMethodPieces) > 1) {
                    //if you want to remove "get" and "set" from the index, uncomment the following line
                    //$arMethodPieces = array_diff( $arMethodPieces, self::$arReservedMethods);
                    $arNewPieces[2] = array_merge($arNewPieces[2], $arMethodPieces);
                    if (count( $arMethodPieces) > 2) {
                        //that we have some partly connections like do_this from do_this_thing
                        foreach ($arMethodPieces as $nId => $strPiece) {
                            if ($nId < count($arMethodPieces) - 1) {
                                $arNewPieces[2][]   = $strPiece . '_' . $arMethodPieces[$nId + 1];
                            }
                        }
                    }
                }
            }//foreach piece

            //append the search words to the index array
            foreach ($arNewPieces as $nPriority => $arPriorityPieces) {
                foreach ($arPriorityPieces as $strPiece) {
                    $arIndex[$strPiece][$nPriority][]   = $strFile;
                }
            }
        }

        //sort the index | should speed up searching and is nice for debugging
        ksort($arIndex);

        return $arIndex;
    }//protected static function buildIndexFromFiles($arFiles)



    /**
    *   Returns an array of file names from the documentation directory.
    *   The file names are relative to the doc directory
    *
    *   @param string $strDocumentationDirectory    The directory of the compiled manual
    *   @return array   All the files in there
    */
    protected static function getFiles($strDocumentationDirectory)
    {
        $strDir = getcwd();
        chdir($strDocumentationDirectory);
        //php-gtk-web specific
        #$arFiles = glob('*/*.{html,php}', GLOB_BRACE);
        $arFiles = glob('*.php');
        chdir($strDir);

        if (count($arFiles) == 0) {
            throw new Exception('No files found in ' . $strDocumentationDirectory);
        }

        return $arFiles;
    }//protected static function getFiles($strDocumentationDirectory)



    /**
    *   Returns an array of filenames that should contain title tags
    *   needed for the camelCase title splitter
    *
    *   @param  array   $arFiles    Array with files that (@see getFiles())
    *   @return array   Array with files that should have needed titles
    */
    protected static function getTitleFiles($arFiles)
    {
        $nFiles = count($arFiles);
        for ($nA = 0; $nA < $nFiles; $nA++) {
            //class files (gtk.gtktreeview.html) or enums (gtk.enum.selectionmode.html)
            if (!preg_match('/^[a-z0-9]+\\.(enum\\.)?[a-z0-9]+\\.[a-z]+$/', basename($arFiles[$nA]))) {
                unset($arFiles[$nA]);
            }
        }
        return $arFiles;
    }//protected static function getTitleFiles($arFiles)



    /**
    *   Returns an array with the contents of the html title tags
    *   in the given files
    *
    *   @param array $arFiles   The files to check
    *   @param string $strDocumentationDirectory    The directory the file names are relative to
    *
    *   @return array   Array of titles.
    */
    protected static function getTitles($arFiles, $strDocumentationDirectory)
    {
        $arTitles = array();
        foreach ($arFiles as $strFile) {
            if (substr($strFile, -4) === '.php') {
                //.php files (make phpweb) don't have a title header
                if (preg_match('/manualHeader\\(\"(.+)\"\\,/', file_get_contents($strDocumentationDirectory . '/' . $strFile), $arMatches)) {
                    $arTitles[] = $arMatches[1];
                }
            } else {
                if (preg_match('/<title>(.+)<\\/title>/', file_get_contents($strDocumentationDirectory . '/' . $strFile), $arMatches)) {
                    $arTitles[] = $arMatches[1];
                }
            }
        }
        return $arTitles;
    }//protected static function getTitles($arFiles, $strDocumentationDirectory)



    /**
    *   Splits all the titles from camelCase into several
    *   words (camel and case).
    *
    *   @param array    $arTitles   The titles from the files
    *   @return array   Array with strtolower(word) => split words array
    */
    protected static function getCamelCaseWords($arTitles)
    {
        $arSplit = array();

        foreach ($arTitles as $strTitle) {
            if (strpos($strTitle, ' ') !== false) {
                //will be tutorial title or "Gtk functions"
                //we don't want this now.
                continue;
            }
            $arSplit[strtolower($strTitle)] = self::varyWords(self::splitCamelCaseWord($strTitle));
        }

        return $arSplit;
    }//protected static function getCamelCaseWords($arTitles)



    /**
    *   Splits a camelCaseWord into words (camel, case, word)
    *
    *   @param string   $strWord    The word to split
    *   @return array   Array with lowercase words
    */
    protected static function splitCamelCaseWord($strWord)
    {
        $strWords = preg_replace('/([A-Z])/', ' \\1', $strWord);
        return explode(' ', strtolower($strWords));
    }//protected static function splitCamelCaseWord($strWord)



    /**
    *   Makes variations of an array of words.
    *   E.g. array(Gtk, Tree, View, Column) will get the variations
    *   gtktree, gtktreeview, treeview, treeviewcolumn, viewcolumn
    *   added to the word list
    *
    *   @param string   $arWords    Array with words
    *   @return array   Array with words and their variations
    */
    protected static function varyWords($arWords)
    {
        $arVariations = $arWords;
        for ($nA = 0; $nA < count($arWords); $nA++) {
            $strVariation = '';
            for ($nB = $nA; $nB < count($arWords); $nB++) {
                $strVariation .= $arWords[$nB];
                $arVariations[] = $strVariation;
            }
        }

        return array_unique($arVariations);
    }//protected static function varyWords($arWords)

}//class PhpGtkDoc_Search2_Index
?>