# VTextFile

Esta clase representa a un fichero de texto y disponemos de funciones para consultar sus características, modificarlas así como crear, leer o escribir un fichero de texto en disco.

## Indice de funciones

### **Constructor**

[VTextFile](#vtextfile)( String szFileName )

### **Generales**

Boolean [atEnd](#atend)()

void [close](#close)()

void [codec](#codec)()

Number [error](#error)()

Boolean [exists](#exists)()

String [fileName](#filename)()

void [flush](#flush)()

Boolean [open](#open)( Number nMode )

Number [permissions](#permissions)()

Number [pos](#pos)()

String [readAll](#readall)()

String [readLine](#readline)( Number nMaxlen=0 )

Boolean [seek](#seek)( Number nOffset )

void [setCodec](#setcodec)( String szCodecName )

Boolean [setPermissions](#setpermissions)( Number nPermissions )

Number [size](#size)()

void [unsetError](#unseterror)()

void [write](#write)( String szText )

### **De operaciones sobre ficheros**

Boolean [copy](#copy)( String szNewName )

Boolean [remove](#remove)()

Boolean [rename](#rename)( String szNewName )

Boolean [resize](#resize)( Number nSize )

## Enumeraciones

**Nombres de códigos**

* "Apple Roman"
* "Big5"
* "Big5-HKSCS"
* "CP949"
* "EUC-JP"
* "EUC-KR"
* "GB18030-0"
* "IBM 850"
* "IBM 866"
* "IBM 874"
* "ISO 2022-JP"
* "ISO 8859-1 to 10"
* "ISO 8859-13 to 16"
* "Iscii-Bng, Dev, Gjr, Knd, Mlm, Ori, Pnj, Tlg, and Tml"
* "JIS X 0201"
* "JIS X 0208"
* "KOI8-R"
* "KOI8-U"
* "MuleLao-1"
* "ROMAN8"
* "Shift-JIS"
* "TIS-620"
* "TSCII"
* "UTF-8"
* "UTF-16"
* "UTF-16BE"
* "UTF-16LE"
* "UTF-32"
* "UTF-32BE"
* "UTF-32LE"
* "Windows-1250 to 1258"
* "WINSAMI2"

## Documentación de funciones

### Constructor

#### VTextFile( String szFileName ) <a href="#vtextfile" id="vtextfile"></a>

Crea una instancia de objeto de la clase VTextFile. Requiere importar previamente la clase: importClass( "VTextFile" ).

Parámetros:

* szFileName: string que establece la senda del fichero de texto

### Funciones generales

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

Devuelve true si el fin de fichero ha sido leído.

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

Cierra el fichero.

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

Devuelve el code del fichero.

{% hint style="info" %}
En Windows, el codec por defecto se basa en la configuración local. En sistemas Linux y Mac hará uso de la librería iconv si no hay configurado un codec local. En ambos casos, el nombre de codec que se devolvería la función codec de VTextFile sería "System".
{% endhint %}

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

Devuelve el código numérico del error.

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

Devuelve true si el fichero existe, false en caso contrario.

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

Devuelve el nombre del fichero.

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

Fuerza que se guarden todos los buffers a disco.

#### Boolean open( Number nMode ) <a href="#open" id="open"></a>

Abre el fichero. Devuelve true si ha podido abrirlo.

Abre el fichero con los modos especificados. Los modos de apertura son combinables. Se pueden especificar varios separados por "|".

Parámetros:

* nMode: número que indica el modo de apertura. Ver enum de flags de modos de apertura del fichero. Los valores con combinables mediante el uso del operador bitwise or booleano "|".

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

Devuelve el código numérico de los permisos. Ver enum de permisos del fichero.

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

Devuelve la posición actual en el fichero.

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

Devuelve el contenido completo del fichero.

#### String readLine( Number nMaxlen=0 ) <a href="#readline" id="readline"></a>

Devuelve el contenido de una línea.

Parámetros:

* nMaxlen: número que establece la longitud máxima a devolver, por defecto 0 = hasta fin de línea.

#### Boolean seek( Number nOffset ) <a href="#seek" id="seek"></a>

Establece la posición del fichero. Devuelve true si el posicionamiento finaliza correctamente.

Parámetros:

* nOffset: número que establece la posición.

#### void setCodec( String szCodecName ) <a href="#setcodec" id="setcodec"></a>

Establece el codec para codificar los datos que escriben. Debemos aplicar esta función sobre el objeto VTextFile creado antes de escribir.

Parámetros:

* szCodecName: cadena que indica el codec. Ver lista de nombres de códigos.

{% hint style="info" %}
En Windows, el codec por defecto se basa en la configuración local. En sistemas Linux y Mac hará uso de la librería iconv si no hay configurado un codec local. En ambos casos, el nombre de codec que se devolvería la función codec de VTextFile sería "System".
{% endhint %}

#### Boolean setPermissions( Number nPermissions ) <a href="#setpermissions" id="setpermissions"></a>

Establece los permisos del fichero.

Parámetros:

* nPermissions: número que define los permisos del fichero. Ver enum de permisos de un fichero.

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

Devuelve el tamaño en bytes del fichero.

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

Establece el error del fichero al valor del enum

[VFile](vfile)

::NoError.

#### void write( String szText ) <a href="#write" id="write"></a>

Graba una cadena de texto en la posición en curso.

Parámetros:

* szTexto: cadena que establece el texto a grabar.

### Funciones de operaciones sobre ficheros

#### Boolean copy( String szNewName ) <a href="#copy" id="copy"></a>

Hace una copia del fichero en curso con otro nombre o path.

Devuelve true si la copia ha podido realizarse con éxito.

Parámetros:

* szNewName: cadena que indica la senda donde se almacenará la copia del fichero

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

Elimina el fichero en curso.

Devuelve true si se ha eliminado correctamente.

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

Renombra el fichero en curso.

Devuelve true si ha podido renombrarse correctamente. Si el fichero con el nombre szNewName ya existe devuelve false.

Parámetros:

* szNewName: cadena que indica el nombre o senda nueva para el fichero.

#### Boolean resize( Number nSize ) <a href="#resize" id="resize"></a>

Cambia el tamaño del fichero.

Devuelve true si ha podido realizarse correctamente.

Parámetros:

* nSize: número que indica el número de bytes del nuevo tamaño del fichero

## Ejemplos

### 1. Ejemplos de creación de un fichero de texto

```javascript
////////////////////////////////////////////////////////////
// Ejemplo de creación de un fichero de texto

// Para usar las funciones de la clase VFile primero hay que importarla
importClass( "VTextFile" );
importClass( "VFile" );

// Se declara el objeto fichero
var fi = new VTextFile( "/TextFile.txt" );

// Se abre el fichero en modo escritura. Crea si no existe o limpia si existe
if ( fi.open( VFile.OpenModeWriteOnly | VFile.OpenModeTruncate) )
{
    // Se llena el buffer con las 26 letras del abecedario
    for( var x=0; x < 30; ++x )
    {
        fi.write( "Línea " + x + " de texto a grabar" + "\n" );
    }

    // Se cierra el fichero
    fi.close();
}
else
    // Si no ha sido posible abrir el fichero se muestra error
    alert( "No se pudo abrir el fichero " + fi.fileName() + ", error " + fi.error(), "Error" );
```

### 2. Ejemplos de lectura de un fichero de texto

```javascript
////////////////////////////////////////////////////////////
// Ejemplo de lectura de un fichero de texto

// Para usar las funciones de la clase VFile primero hay que importarla
importClass( "VTextFile" );
importClass( "VFile" );

// Se declara el objeto fichero
var fi = new VTextFile( "/TextFile.txt" );

// Se abre el fichero en modo de sólo lectura
if ( fi.open( VFile.OpenModeReadOnly ) )
{
    // Leer todo el fichero
    alert( "Tamaño del fichero = " + fi.size() + " bytes" );

    // Leer todo el fichero
    alert( fi.readAll() );

    // Como hemos leído todo el fichero estamos posicionados al final
    // Para volver a leer el fichero línea a línea nos posicionamos al principio
    fi.seek( 0 );

    // Recorremos el fichero línea a línea guardando su contenido
    var txt = "";

    while ( fi.atEnd() == false )
    {
        txt += fi.readLine();
    }   

    // Mostramos la variable con todo el contenido del fichero
    alert( txt );

    // Se cierra el fichero
    fi.close();
}
else {
    // Si no ha sido posible abrir el fichero se muestra error
    alert( "No se pudo abrir el fichero " + fi.fileName() + ", error " + fi.error(), "Error" );
}
```
