# VDir

La clase VDir proporciona acceso a las estructuras de directorios y sus contenidos.

Un VDir se utiliza para manipular los nombres de sendas, acceso a la información sobre las sendas y los ficheros y manipular el sistema de archivos subyacente.

VDir usa "/" como un separador universal de directorios de la misma manera que "/" se utiliza como un separador de ruta en URLs. Si siempre utiliza “/” como separador de directorio, VDir traducirá las sendas para cumplir con el sistema operativo subyacente.

Un VDir puede apuntar a un directorio utilizando una ruta absoluta o relativa. Las rutas absolutas comienzan con el separador de directorio (opcionalmente precedido por una especificación de unidad en Windows). Los nombres relativos de archivo comienzan con un nombre de directorio o un nombre de archivo.

## Funciones

**Constructor**

| Función                      |
| ---------------------------- |
| [VDir](#vdir)( String Path ) |

**Generales**

| Retorno | Función                     |
| ------- | --------------------------- |
| String  | [dirName](#dirname)()       |
| Boolean | [exists](#exists)()         |
| Boolean | [isAbsolute](#isabsolute)() |
| Boolean | [isReadable](#isreadable)() |
| Boolean | [isRelative](#isrelative)() |
| Boolean | [isRoot](#isroot)()         |

**De path**

| Retorno | Función                                                    |
| ------- | ---------------------------------------------------------- |
| String  | [absoluteFilePath](#absolutefilepath)( String szFileName ) |
| String  | [absolutePath](#absolutepath)()                            |
| String  | [canonicalPath](#canonicalpath)()                          |
| Boolean | [cd](#cd)( String szDirName )                              |
| Boolean | [cdUp](#cdup)()                                            |
| String  | [filePath](#filepath)( String szFileName )                 |
| Boolean | [makeAbsolute](#makeabsolute)()                            |
| String  | [path](#path)()                                            |
| String  | [relativeFilePath](#relativefilepath)( String szFileName ) |

**De operaciones con directorios**

| Retorno | Función                               |
| ------- | ------------------------------------- |
| Boolean | [mkdir](#mkdir)( String szDirName )   |
| Boolean | [mkpath](#mkpath)( String szDirPath ) |
| Boolean | [rmdir](#rmdir)( String szDirName )   |
| Boolean | [rmpath](#rmpath)( String szDirPath ) |

**De ficheros del directorio**

| Retorno                                                                                              | Función                                                                                                                                                                                                        |
| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Number                                                                                               | [count](#count)()                                                                                                                                                                                              |
| [VFileInfo](https://doc.velneo.com/24/velneo-vdevelop/scripts/lenguajes/javascript/clases/vfileinfo) | [entryAt](#entryat)( Number nIndex )                                                                                                                                                                           |
| Boolean                                                                                              | [exists](#boolean-exists-string-path-)( String Path )                                                                                                                                                          |
| Boolean                                                                                              | [load](#load)( Number nFilters = QDir::NoFilter, Number nSortFlags = QDir::NoSort )                                                                                                                            |
| Boolean                                                                                              | [load](#boolean-load-stringlist-asznamefilters-number-nfilters--qdirnofilter-number-nsortflags--qdirnosort-)( StringList& aszNameFilters, Number nFilters = QDir::NoFilter, Number nSortFlags = QDir::NoSort ) |
| void                                                                                                 | [refresh](#refresh)()                                                                                                                                                                                          |
| Boolean                                                                                              | [remove](#remove)( String Path )                                                                                                                                                                               |
| Boolean                                                                                              | [rename](#rename)( String szOldName, String szNewName )                                                                                                                                                        |

## Enumeraciones

**Flags de filtros**

* FilterDirs = 0x001 Sólo directorios que cumplan el filtro
* FilterFiles = 0x002 Solo ficheros
* FilterDrives = 0x004 Lista de dispositivos (se ignora en Linux)
* FilterNoSymLinks = 0x008 No incluir en la lista los enlaces simbólicos (accesos directos)
* FilterAllEntries = FilterDirs | FilterFiles | FilterDrives Incluye en la lista directorios, ficheros, dispositivos
* FilterReadable = 0x010 Incluye los directorios o ficheros que tienen acceso de lectura
* FilterWritable = 0x020 Incluye los directorios o ficheros que tienen acceso de escritura
* FilterExecutable = 0x040 Incluye los ficheros que tienen acceso de ejecución
* FilterModified = 0x080 Incluye sólo los ficheros que han sido modificados (ignorado en Unix)
* FilterHidden = 0x100 Incluye los ficheros ocultos
* FilterSystem = 0x200 Incluye los ficheros del sistema
* FilterAllDirs = 0x400 Todos los directorios, sin aplicar filtros
* FilterCaseSensitive = 0x800 El filtro es sensible a mayúsculas y minúsculas
* FilterNoDotAndDotDot = 0x1000 No incluye en la lista las entradas "." y "..", directorios en curso y padre
* FilterNoDot = 0x2000 No incluye en la lista la entrada ".", el directorio en curso
* FilterNoDotDot = 0x4000 No incluye en la lista la entrada "..", el directorio padre
* FilterNone = -1 Sin filtro

**Flags de ordenación**

* SortName = 0x00 Ordenado por nombre
* SortTime = 0x01 Ordenado por fecha de última modificación
* SortSize = 0x02 Ordenado por tamaño
* SortUnsorted = 0x03 No ordenado
* SortDirsFirst = 0x04 Los directorios al principio, después los ficheros
* SortReversed = 0x08 Orden inverso
* SortIgnoreCase = 0x10 Ignorar mayúsculas
* SortDirsLast = 0x20 Los ficheros al principio, después los directorios
* SortLocaleAware = 0x40 Ordenado según la configuración local
* SortType = 0x80 Ordenado por extensión
* SortNone = -1 No ordenado por defecto

## Documentación de funciones

### Constructor <a href="#cons" id="cons"></a>

#### VDir( String Path ) <a href="#vdir" id="vdir"></a>

Crea una instancia de objeto de la clase VDir.

Parámetros:

* szFileName: nombre o path del fichero.

### Funciones generales

#### String dirName() <a href="#dirname" id="dirname"></a>

Devuelve el nombre del directorio, por ejemplo "vbase" . No se debe confundir con el path "/instancias/vbase". Si el directorio no tiene nombre, por ejemplo el raíz devuelve "".

#### Boolean exists() <a href="#exists" id="exists"></a>

Devuelve true si el directorio existe y false si no existe.

#### Boolean isAbsolute() <a href="#isabsolute" id="isabsolute"></a>

Devuelve true si el path es absoluto.

#### Boolean isReadable() <a href="#isreadable" id="isreadable"></a>

Devuelve true si el directorio es legible. Un valor false no garantiza que los ficheros no sean accesibles.

#### Boolean isRelative() <a href="#isrelative" id="isrelative"></a>

Devuelve true si el path es relativo. En Linux y Mac es relativo si el path no comienza por "/".

#### Boolean isRoot() <a href="#isroot" id="isroot"></a>

Devuelve true si es el directorio raíz. Si es un enlace simbólico del directorio raíz devolverá false. Para enlaces simbólicos usar la función canonicalPath().

### Funciones de path

#### String absoluteFilePath( String szFileName ) <a href="#absolutefilepath" id="absolutefilepath"></a>

Devuelve el path absoluto de un fichero en un directo. No se verifica si el fichero existe en el directorio. No se elimina del path los separadores múltiples o "." o ".." redundantes.

Parámetros:

* szFileName = Nombre o path del fichero.

#### String absolutePath() <a href="#absolutepath" id="absolutepath"></a>

Devuelve el path absoluto (empieza con "/" o con la letra del dispositivo). Puede contener enlaces simbólicos pero no "." o ".." redundates o múltiples separadores.

#### String canonicalPath() <a href="#canonicalpath" id="canonicalpath"></a>

Devuelve el path canonica, sin enlaces simbólicos ni "." o ".." redundantes. Si el sistema no tiene enlaces simbólicos la función equivale a absolutePath(). Si el canonical path no existe la función no devuelve nada.

#### Boolean cd( String szDirName ) <a href="#cd" id="cd"></a>

Cambia el directorio del objeto VDir. Devuelve true si el directorio existe y es legible, en caso contrario false. El cambio de directorio no se produce si devuelve false. Usar cd("..") es equivalente a usar la función cdUp().

Parámetros:

* szDirName: nombre o path del directorio.

#### Boolean cdUp() <a href="#cdup" id="cdup"></a>

Cambia el directorio del objeto VDir al directorio padre. Devuelve true si el directorio existe y es legible, en caso contrario false. El cambio de directorio no se produce si devuelve false. Usar cdUp() es equivalente a usar la función cd("..").

#### String filePath( String szFileName ) <a href="#filepath" id="filepath"></a>

Devuelve el path de un fichero.

Parámetros:

* szFileName: nombre o path del fichero.

#### Boolean makeAbsolute() <a href="#makeabsolute" id="makeabsolute"></a>

Convierte el path del directorio en un path absoluto. Si ya es absoluto no hace nada. Devuelve true si la conversión se ha realizado.

#### String path() <a href="#path" id="path"></a>

Devuelve el path del directorio.

#### String relativeFilePath( String szFileName ) <a href="#relativefilepath" id="relativefilepath"></a>

Devuelve el path de un fichero relativo al directorio.

Parámetros:

* szFileName: nombre o path del fichero.

### Funciones de operaciones con directorios <a href="#fun-ope-dir" id="fun-ope-dir"></a>

#### Boolean mkdir( String szDirName ) <a href="#mkdir" id="mkdir"></a>

Crear un directorio. Devuelve true si se ha podido crear el nuevo directorio.

Parámetros:

* szDirName: nombre o path del directorio.

#### Boolean mkpath( String szDirPath ) <a href="#mkpath" id="mkpath"></a>

Crear los directorios inexistentes de un path. Devuelve true si ha podido crear todo el path del directorio. Se crean todos los subdirectorios necesario para crear el directorio.

Parámetros:

* szDirPath: path del directorio.

#### Boolean rmdir( String szDirName ) <a href="#rmdir" id="rmdir"></a>

Elimina un directorio. El directorio debe estar vacío para poder eliminarlo. Devuelve true sin finaliza correctamente.

Parámetros:

* szDirName: nombre o path del directorio.

#### Boolean rmpath( String szDirPath ) <a href="#rmpath" id="rmpath"></a>

Elimina un path (directorio y subdirectorios). Devuelve true si finaliza correctamente.

Parámetros:

* szDirPath: path del directorio.

### Funciones de ficheros del directorio

#### Number count() <a href="#count" id="count"></a>

Devuelve del nº de ficheros y directorios cargados con load().

#### VFileInfo entryAt( Number nIndex ) <a href="#entryat" id="entryat"></a>

Devuelve un objeto [VFileInfo](https://doc.velneo.com/24/velneo-vdevelop/scripts/lenguajes/javascript/clases/vfileinfo) correspondiente al nº de elemento de la lista.

Parámetros:

* nIndex: número de orden del fichero en la lista cargada de ficheros del directorio.

#### Boolean exists( String Path )

Devuelve true si el fichero existe.

Parámetros:

* szFilename: nombre o path del fichero.

#### Boolean load( Number nFilters = QDir::NoFilter, Number nSortFlags = QDir::NoSort ) <a href="#load" id="load"></a>

Carga en el objeto la lista de ficheros y subdirectorio del directorio en curso.

Parámetros:

* nFilters: ver enum de flags de tipos de filtros. Los valores con combinables mediante el uso del operador bitwise or booleano "|".
* nSortFlags: ver enum de flags de tipos de ordenación. Los valores con combinables mediante el uso del operador bitwise or booleano "|".

#### Boolean load( StringList& aszNameFilters, Number nFilters = QDir::NoFilter, Number nSortFlags = QDir::NoSort )

Carga en el objeto la lista de ficheros y subdirectorio del directorio en curso.

Parámetros:

* szNameFilter: nombre del filtro.
* nFilters: ver enum de flags de tipos de filtros. Los valores con combinables mediante el uso del operador bitwise or booleano "|".
* nSortFlags: ver enum de flags de ordenación. Los valores con combinables mediante el uso del operador bitwise or booleano "|".

#### void refresh() <a href="#refresh" id="refresh"></a>

Refresca en el objeto directorio la lista de ficheros y subdirectorios.

#### Boolean remove( String Path ) <a href="#remove" id="remove"></a>

Elimina un fichero o directorio. Devuelve true si finaliza correctamente.

Parámetros:

* szFilename: nombre o path del fichero.

#### Boolean rename( String szOldName, String szNewName ) <a href="#rename" id="rename"></a>

Renombra un fichero o directorio. Devuelve true si finaliza correctamente.

Parámetros:

* szOldname: nombre o path del del fichero a cambiar.
* szNename: nombre o path del nuevo para el fichero.

## Ejemplos

### 1. Ejemplo de uso de las funciones de la clase VDir

```javascript
////////////////////////////////////////////////////////////
// Ejemplo de las funciones de la clase VDir

// Para poder usar la clase VDir y sus funciones hay que importarla primero
importClass( "VDir" );

// Lo primero que hay que hacer es crear un objeto VDir con un directorio o vacío
var dir = new VDir();

// En caso de crear el objeto VDir sin un directorio es necesario asignar un path
dir.cd( "/Instancias/001" );
alert( "Se ha cambiado la senda del objeto directorio a " + dir.path() )

// Convertir el path del directorio en path absoluto
if ( dir.makeAbsolute() )
    alert( dir.path() + " ya era un path absoluto" );

// Cargar la lista de ficheros y directorios
dir.load();

alert( "¿Existe el directorio " + dir.path() + "? " + dir.exists() + "\n" + 
        "¿El directorio es el raíz? " + dir.isRoot() + "\n" + 
        "¿El directorio es legible? " + dir.isReadable() + "\n" + 
        "¿El directorio es absoluto? " + dir.isAbsolute() + "\n" + 
        "¿El directorio es relativo? " + dir.isRelative() + "\n" + 
        "Este directorio tiene " + dir.count() + " ficheros y directorios.");

// Se crea un directorio
bOk = dir.mkdir( "/" + "new" );

if ( bOk )
    // Se elimina el directorio
    dir.rmdir( "/" + "new" );

// Se crean los directorios y subdirectorios necesarios
bOk = dir.mkpath( "/backup/files/txt" );

if ( bOk )
    // Se elimina el path completo
    dir.rmpath( "/backup/files/txt" );
```

### 2. Lee y devuelve los ficheros contenidos en un directorio

```javascript
// --------------------------------------------------------------------------------
// Lee el directorio y devuelve los ficheros contenidos
// -----------------------------------------------------------

importClass("VDir");

// Recibimos la senda en una variable local al proceso
var senda = theRoot.varToString( "SENDA" );
var ficheros = "";

// Creamos el nuevo directorio
var dir = new VDir();

// Nos posicionamos en el directorio
if ( dir.cd( senda ) )
{
    // Preparamos el array de filtros a aplicar
    var filtros = [];
    filtros.push( "*.csv" );

    // Cargamos los ficheros del directorio
    if ( dir.load( filtros, VDir.FilterFiles, VDir.SortName ) )
    {
        // Recorremos la lista de ficheros y los concatenamos separados por "|"
        for ( var numFichero = 0; numFichero < dir.count(); numFichero++ )
        {
            ficheros += dir.entryAt( numFichero ).filePath() + "|";
        };
    };
};

// Devolvemos la lista de ficheros del directorio en una variable local
theRoot.setVar( "FICHEROS", ficheros );
```