<?php
/**
 * Lazy file iterator. Pulls directory listings when required.
 */
class Loco_fs_FileFinder implements Iterator, Countable, Loco_fs_FileListInterface {

    /**
     * Top-level search directories
     * @var Loco_fs_FileList
     */
    private $roots;

    /**
     * Directories to search, including those descended into
     * @var Loco_fs_FileList|null
     */
    private $subdir;
    
    /**
     * Whether directories all read into memory
     * @var bool
     */
    private $cached = false;

    /**
     * File listing already matched
     * @var Loco_fs_FileList|null
     */
    private $cache;
    
    /**
     * Internal array pointer for whole list of paths
     * @var int
     */
    private $i;
    
    /**
     * Internal pointer for directory being read
     * @var int|null
     */
    private $d;
    
    /**
     * Current directory being read
     * @var resource|null
     */
    private $dir;

    /**
     * Path of current directory being read
     * @var string
     */
    private $cwd;

    /**
     * Whether directories added to search will be recursive by default
     * @var bool
     */
    private $recursive = false;

    /**
     * Whether currently recursing into subdirectories
     * This is switched on and off as each directory is opened
     * @var bool|null
     */
    private $recursing;

    /**
     * Whether to follow symlinks when recursing into subdirectories
     * Root-level symlinks are always resolved when possible
     * @var bool
     */
    private $symlinks = true;

    /**
     * Registry of followed links by their original path
     * @var Loco_fs_FileList
     */
    private $linked;

    /**
     * List of file extensions to filter on and group by
     * @var null|Loco_fs_FileList[]
     */
    private $exts = null;

    /**
     * List of directory names to exclude from recursion
     * @var array
     */
    private $excluded = [];


    /**
     * Create initial list of directories to search
     * @param string $root default root to start
     */
    public function __construct( string $root = '' ){
        $this->roots = new Loco_fs_FileList;
        $this->linked = new Loco_fs_FileList;
        if( $root ){
            $this->addRoot( $root );
        }
    } 


    /**
     * Set recursive state of all defined roots
     */
    public function setRecursive( bool $bool ):self {
        $this->invalidate();
        $this->recursive = $bool;
        /* @var $dir Loco_fs_Directory */
        foreach( $this->roots as $dir ){
            $dir->setRecursive( $bool );
        }
        return $this;
    }


    /**
     * Whether to follow symlinks
     */
    public function followLinks( bool $bool ):self {
        $this->invalidate();
        $this->symlinks = $bool;
        return $this;
    }


    /**
     * Get the original symlink that was followed for a given file
     */
    public function getFollowed( string $path ):?Loco_fs_Link {
        /* @var Loco_fs_Link $link */
        foreach( $this->linked as $link ){
            $file = $link->resolve();
            $orig = $file->getPath();
            // exact match on followed path
            if( $orig === $path ){
                return $link;
            }
            // match further up the directory tree
            if( $file instanceof Loco_fs_Directory ){
                $orig = trailingslashit($orig);
                $snip = strlen($orig);
                if( $orig === substr($path,0,$snip) ){
                    return new Loco_fs_Link( $link->getPath().'/'.substr($path,$snip) );
                }
            }
        }
        return null;
    }


    private function invalidate():void {
        $this->cached = false;
        $this->cache = null;
        $this->subdir = null;
    }
    
    
    /**
     * Get all files found as a list object
     * @return Loco_fs_FileList <int,Loco_fs_File> 
     */    
    public function export():Loco_fs_FileList{
        if( ! $this->cached ){
            $this->rewind();
            while( $this->valid() ){
                $this->next();
            }
        }
        return $this->cache;
    }


    /**
     * @return Loco_fs_FileList[]
     */
    public function exportGroups():array {
        $this->cached || $this->export();
        return $this->exts;
    }


    /**
     * Add a directory root to search.
     */
    public function addRoot( string $root, ?bool $recursive = null ):self {
        $this->invalidate();
        $dir = new Loco_fs_Directory($root);
        $this->roots->add( $dir );
        // new directory inherits current global setting unless set explicitly
        $dir->setRecursive( is_bool($recursive) ? $recursive : $this->recursive );
        return $this;
    }


    /**
     * Get all root directories to be searched
     */
    public function getRootDirectories():Loco_fs_FileList {
        return $this->roots;
    }


    /**
     * Filter results by given file extensions
     */
    public function group( ...$exts ):self {
        return $this->filterExtensions($exts);
    }


    /**
     * Filter results by file extensions given in array
     * @param string[] $exts File extension strings
     */
    public function filterExtensions( array $exts ):self {
        $this->invalidate();
        $this->exts = [];
        foreach( $exts as $ext ){
            $this->exts[ ltrim($ext,'*.') ] = new Loco_fs_FileList;
        }
        return $this;
    }


    /**
     * Add one or more paths to exclude from listing
     */
    public function exclude( ...$paths ):self {
        $this->invalidate();
        foreach( $paths as $path ){
            $file = new Loco_fs_File($path);
            // if path is absolute, add straight onto list
            if( $file->isAbsolute() ){
                $file->normalize();
                $this->excluded[] = $file;
            }
            // else append to all defined roots
            else {
                foreach( $this->roots as $dir ) {
                    $file = new Loco_fs_File( $dir.'/'.$path );
                    $file->normalize();
                    $this->excluded[] = $file;
                }
            }
        }
        return $this;
    }


    /**
     * Export excluded paths as file objects
     * @return Loco_fs_File[]
     */
    public function getExcluded():array {
        return $this->excluded;
    }

    
    /**
     * @param Loco_fs_Directory $dir
     * @return void
     */    
    private function open( Loco_fs_Directory $dir ){
        $path = $dir->getPath();
        $recursive = $dir->isRecursive();
        if( is_link($path) ){
            $link = new Loco_fs_Link($path);
            if( $link->isDirectory() ){
                $path = $link->resolve()->getPath();
                $this->linked->add($link);
            }
        }
        $this->cwd = $path;
        $this->recursing = $recursive;
        $this->dir = opendir($path);
    }


    /**
     * @return void
     */
    private function close(){
        closedir( $this->dir );
        $this->dir = null;
        $this->recursing = null;
    }


    /**
     * Test if given path is matched by one of our exclude rules
     */
    public function isExcluded( string $path ):bool {
        /* @var Loco_fs_File $excl */
        foreach( $this->excluded as $excl ){
            if( $excl->equal($path) ){
                return true;
            }
        }
        return false;
    }


    /**
     * Read next valid file path from root directories
     */
    private function read():?Loco_fs_File {
        while( is_resource($this->dir) ){
            while( $f = readdir($this->dir) ){
                // dot-files always excluded
                if( '.' === substr($f,0,1) ){
                    continue;
                }
                $path = $this->cwd.'/'.$f;
                // early path exclusion check
                if( $this->isExcluded($path) ){
                    continue;
                }
                // early filter on file extension when grouping
                if( is_array($this->exts) ){
                    $ext = pathinfo($f,PATHINFO_EXTENSION);
                    // missing file extension only relevant for directories
                    if( '' === $ext ){
                        if( ! $this->recursing || ! is_dir($path) ){
                            continue;
                        }
                    }
                    // any other extension can be skipped
                    else if( ! array_key_exists($ext,$this->exts) ){
                        continue;
                    }
                }
                // follow symlinks (subdir hash ensures against loops)
                if( is_link($path) ){
                    if( ! $this->symlinks ){
                        continue;
                    }
                    $link = new Loco_fs_Link($path);
                    if( $file = $link->resolve() ){
                        $path = $file->getPath();
                        if( $this->isExcluded($path) ){
                            continue;
                        }
                        $this->linked->add($link);
                    }
                    else {
                        continue;
                    }
                }
                // add subdirectory to recursion list, or skip
                if( is_dir($path) ){
                    if( $this->recursing ){
                        $subdir = new Loco_fs_Directory($path);
                        $subdir->setRecursive(true);
                        $this->subdir->add( $subdir );
                    }
                    continue;
                }
                // file represented as object containing original path
                $file = new Loco_fs_File($path);
                $this->add($file);
                return $file;
            }
            $this->close();
            // Advance directory and continue outer loop
            $d = $this->d + 1;
            if( $this->subdir->offsetExists($d) ){
                $this->d = $d;
                $this->open( $this->subdir->offsetGet($d) );
            }
            // else no directories left to search
            else {
                break;
            }
        }
        // at end of all available files
        $this->cached = true;
        return null;
    }


    /**
     * {@inheritDoc}
     */
    public function add( Loco_fs_File $file ):bool {
        if( is_array($this->exts) ){
            $ext = $file->extension();
            if( array_key_exists($ext,$this->exts) ){
                $this->exts[$ext]->add($file);
            }
            // edge case where symlink has correct extension, but resolved path does not.
            else if( $this->symlinks && $this->linked->has($file) ){
                Loco_error_Debug::trace('Symbolic link resolves to a file excluded by filter (%s)',$file->basename());
            }
            else {
                $glob = implode(',',array_keys($this->exts));
                Loco_error_Debug::trace('Should have filtered out %s when grouping by *.{%s}', $file->basename(), $glob );
            }
        }
        if( $this->cache->add($file) ){
            $this->i++;
            return true;
        }
        return false;
    }


    /**
     * @return int
     */
    #[ReturnTypeWillChange]
    public function count():int {
        return count( $this->export() );
    }


    /**
     * @return Loco_fs_File|null
     */
    #[ReturnTypeWillChange]
    public function current(){
        $i = $this->i;
        if( is_int($i) && isset($this->cache[$i]) ){
            return $this->cache[$i];
        }
        return null;
    }


    /**
     * @return Loco_fs_File|null
     */
    #[ReturnTypeWillChange]
    public function next(){
        if( $this->cached ){
            $i = $this->i + 1;
            if( isset($this->cache[$i]) ){
                $this->i = $i;
                return $this->cache[$i];
            }
        }
        else {
            $file = $this->read();
            if( $file instanceof Loco_fs_File ) {
                return $file;
            }
        }
        // else at end of all directory listings
        $this->i = null;
        return null;
    }


    /**
     * @return int
     */
    #[ReturnTypeWillChange]
    public function key(){
        return $this->i;
    }


    /**
     * @return bool
     */
    #[ReturnTypeWillChange]
    public function valid(){
        // may be in lazy state after rewind
        // must do initial read now in case list is empty
        return is_int($this->i);
    }


    /**
     * @return void
     */
    #[ReturnTypeWillChange]
    public function rewind(){
        if( $this->cached ){
            $this->cache->rewind();
            $this->i = $this->cache->key();
        }
        else {
            $this->d = 0;
            $this->dir = null;
            $this->cache = new Loco_fs_FileList;
            // add only root directories that exist
            $this->subdir = new Loco_fs_FileList;
            /* @var Loco_fs_Directory $root */
            foreach( $this->roots as $root ){
                if( $root instanceof Loco_fs_Directory && $root->readable() && ! $this->isExcluded( $root->getPath() ) ){
                    $this->subdir->add($root);
                }
            }
            if( $this->subdir->offsetExists(0) ){
                $this->i = -1;
                $this->open( $this->subdir->offsetGet(0) );
                $this->next();
            }
            else {
                $this->i = null;
                $this->subdir = null;
                $this->cached = true;
            }
        }
    }


    /**
     * Test whether internal list has been fully cached in memory
     */
    public function isCached():bool {
        return $this->cached;
    }

}