nginstack

Class: File

@nginstack/engine/lib/io/File~ File

new File(fileName [, mode] [, encoding])

Classe que permite a manipulação de arquivos.

Parameters:
Name Type Argument Description
fileName string

Nome do arquivo.
mode string <optional>

Modo como o arquivo deve ser aberto. Pode ser informado um modo da relação abaixo ou um conjunto de modos separado por vírgula. Caso não seja informado, será assumido o modo 'openAlwaysReadWrite'. Modos possíveis:

  • 'create': DEPRECATED. Alias para o modo createAlways.
  • 'createAlways': abre um arquivo para leitura e escrita, criando se necessário. Se o arquivo já existir, ele será truncado.
  • 'createNew': cria o arquivo caso não exista. Se o arquivo já existir uma exceção será lançada.
  • 'openRead': abre o arquivo apenas para leitura. Caso o arquivo não exista, será aberto o arquivo especial NULL e a leitura não retornará nada.
  • 'openReadOnly': abre o arquivo apenas para leitura, lançando uma exceção caso o arquivo não exista.
  • 'openWrite': DEPRECATED. Alias para openAlwaysReadWrite.
  • 'openReadWrite': DEPRECATED. Alias para openAlwaysReadWrite.
  • 'openAlwaysReadWrite': abre um arquivo para leitura e escrita, criando-o se necessário. Se o arquivo já existir, ele não será truncado.
  • 'openExistingReadWrite': abre um arquivo para leitura e escrita, lançando uma exceção caso o arquivo não exista.
  • 'unbuffered': indica que o acesso ao arquivo não deve ser otimizado por um buffer. Observe que desligar a bufferização prejudica a performance, sendo indicado apenas em situações onde se deseja realizar acesso concorrente ao arquivo.
encoding string <optional>

Tipo de codificação dos dados do arquivo. Esse parâmetro é case insensitive e aceita os valores "utf-8", "windows-1252", "iso-8859-1" ou "binary". Caso não seja informado será considerado o valor "binary", indicando que os dados do arquivo não serão interpretados como sendo de nenhum tipo de codificação.

Members

<static> pathSeparator :string

Separador de path utilizado pelo sistema operacional. Será "" no sistema operacional Windows e "/" no Linux.

Type:
  • string

eof :boolean

Indica se o final do arquivo foi atingido.

Type:
  • boolean
Example
const file = new File(path, 'openRead');
while (!file.eof) {
  const line = file.readln();
  processLine(line);
}

modified :Date

Data de modificação do arquivo.

Type:
  • Date

position :number

Posição atual no arquivo.

Quando o tipo de codificação é passado no construtor, o arquivo é lido como texto e a leitura é otimizada por um buffer. Isso faz com que consultar a posição possa requerer uma busca para reconstruir uma posição válida, tornando-a uma operação cara. Nestes casos, seu uso deve ser evitado em laços.

Para saber se o final do arquivo foi atingido, recomenda-se a utilização da propriedade eof.

Type:
  • number
See:

size :number

Tamanho do arquivo em bytes. Se for um arquivo de texto em UTF-8, a quantidade de bytes informada pode não ser igual à quantidade de caracteres lidos do arquivo, pois alguns caracteres utilizam mais de um byte em sua representação.

Type:
  • number

Methods

<static> changeFileExtension(fileName, extension)

Altera a extensão do nome de arquivo informado.

Parameters:
Name Type Description
fileName string

Nome do arquivo que deve ter a extensão alterada.
extension string

Nova extensão do arquivo. Deve ser informado com o ponto. A extensão será removida caso seja uma string vazia.
Returns:

Nome de arquivo com a extensão alterada.

Type
string
Example
var File = require('@nginstack/engine/lib/io/File');
var fileName = File.changeFileExtension( "teste.txt", ".out")

<static> copyDirectory(sourceDir, targetDir [, opt_replace])

Copia o conteúdo do diretório informado em sourceDir para o destino targetDir. O diretório targetDir será criado caso não exista.

Parameters:
Name Type Argument Description
sourceDir string

Diretório que será copiado.
targetDir string

Local onde será gravada a cópia do conteúdo de sourceDir.
opt_replace boolean <optional>

Indica se deve substituir os arquivos existentes em targetDir. Quando ativo, o conteúdo de targetDir será excluído antes da cópia com o objetivo de garantir que não haverá arquivos em targetDir que não existam em sourceDir. Por padrão será false.

<static> copyFile(existingFileName, newFileName)

Método de classe que permite copiar um arquivo. O diretório do arquivo de destino será criado caso não exista.

Parameters:
Name Type Description
existingFileName string

Nome do arquivo de origem.
newFileName string

Nome do arquivo de destino.
See:
Returns:

True se conseguiu mover o arquivo

Type
boolean
Example
const File = require('@nginstack/engine/lib/io/File');
const duplicated = File.copyFile('c:\\MyFile.txt', 'c:\\MyFile2.txt');
if (!duplicated){
  throw new Error('Very strange error. Possible out of space disk.');
}

<static> createDirectory(path)

Método de classe que permite criar um diretório vazio. Este método criará os subdiretórios do caminho informado recursivamente caso eles não existam.

O uso deste método em geral é desnecessário, pois o construtor new File() e os métodos File.copyFile() e File.moveFile() já garantem a existência do diretório dos arquivos criados.

Parameters:
Name Type Description
path string

Caminho do diretório a ser criado.
See:
  • module:@nginstack/engine/lib/io/File~File.createFile
Returns:

True se conseguiu criar o diretório.

Type
boolean

<static> createTempDirName()

Obtém um nome de diretório único e temporário.

É responsabilidade do desenvolvedor excluir o diretório temporário criado e os arquivos contidos nele, sendo recomendado o uso da função File.deleteDirectory(tempDirName, true) logo após o seu uso. Caso isso não seja feito, o diretório será removido automaticamente pelo Engine apenas na próxima inicialização do sistema. Em servidores, esse descarte automático pode levar dias, portanto é importante que os diretórios e arquivos temporários criados sejam removidos antes, evitando o desperdício de espaço em disco do servidor.

Returns:

Nome do diretório temporário criado.

Type
string

<static> createTempFile()

Cria um objeto associado a um arquivo temporário.

O arquivo criado por esta função é removido automaticamente pelo sistema quando ele é fechado via close ou quando ele é destruído pelo Garbage Collector. Por esse motivo, é preferível o uso desta função em vez de getTempFileName sempre que o nome do arquivo temporário for irrelevante para a aplicação.

See:
Returns:

Instância de um arquivo temporário.

Type
File
Example
const File = require('@nginstack/engine/lib/io/File.js');
const file = File.createTempFile();
try {
  // use temp file ...
} finally {
  file.close();
}

<static> deleteDirectory(dirName [, recursive])

Exclui o diretório informado.

Windows: os arquivos e diretórios serão excluídos definitivamente, não podendo ser recuperados da lixeira.

Parameters:
Name Type Argument Description
dirName string

Nome do diretório que deve ser excluído.
recursive boolean <optional>

Indica se os diretórios e arquivos contidos em "dirName" serão excluídos. Caso o seu valor seja falso ou não seja informado, o diretório somente será excluído se estiver vazio.
See:
Returns:

Indica se a exclusão do diretório foi bem sucedida. Caso "recursive" seja true, este método poderá retornar false mesmo tendo excluído arquivos e subdiretórios. Este caso ocorrerá se algum arquivo dentro do diretório estiver em uso ou se o usuário não tiver permissão de apagar o arquivo ou diretório.

Type
boolean
Example
var File = require('@nginstack/engine/lib/io/File');
if (!File.deleteDirectory('c:\\my-temp-dir')) {
  throw new Error("Não foi possível remover o diretório.");
}

<static> deleteFile(fileName)

Exclui o arquivo informado.

Windows: os arquivos serão excluídos definitivamente, não podendo ser recuperados da lixeira.

Parameters:
Name Type Description
fileName string

Nome do arquivo que deve ser excluído.
See:
Returns:

True, se foi possível excluir o arquivo.

Type
boolean
Example
var File = require('@nginstack/engine/lib/io/File');
var deleted = File.deleteFile('MyFile.txt')
if (!deleted) {
  throw new Error( 'It''s not possible delete the file. It's probably in use.')
}

<static> directoryExists(dirName)

Verifica se o diretório informado existe.

Parameters:
Name Type Description
dirName string

Nome do diretório
Returns:

Retorna true se o diretório existir.

Type
boolean

<static> extractFileName(fileName)

Extrai o nome do arquivo de um nome com "path".

Parameters:
Name Type Description
fileName string

Path e nome do arquivo.
See:
Returns:

O nome do arquivo informado em fileName.

Type
string

<static> extractFilePath(fileName)

Extrai o path do arquivo de um nome com "path".

Parameters:
Name Type Description
fileName string

Path e nome do arquivo.
See:
Returns:

O path do arquivo informado em fileName.

Type
string

<static> fileExists(fileName)

Verifica se o arquivo informado existe.

Parameters:
Name Type Description
fileName string

Nome do arquivo.
Returns:

Retorna true se o arquivo existir.

Type
boolean

<static> fileFromString(fileName, content [, opt_encoding])

Cria um arquivo com o conteúdo informado.

Parameters:
Name Type Argument Description
fileName string

Nome do arquivo que deve ser criado
content string

Conteúdo que deve ser gravado no arquivo.
opt_encoding string <optional>

Tipo de codificação dos dados do arquivo. Esse parâmetro é case insensitive e aceita os valores "utf-8", "windows-1252", "iso-8859-1" ou "binary". Caso não seja informado será considerado o valor "binary", indicando que a string será tratada como "Binary String", não possuindo qualquer tipo de codificação de texto.

<static> findClose(searchRecord)

Esta função libera imediatamente os recursos alocados pela função #findFirst. Caso não seja executado, os recursos serão desalocados de forma não determinística pelo Garbage Collector do ambiente JavaScript.

Parameters:
Name Type Description
searchRecord SearchRecord

Informações do último arquivo localizado.
See:

<static> findFirst(fileName [, opt_attributes])

FindFirst pesquisa no diretório especificado pelo parâmetro "path" o primeiro arquivo que satisfaça o nome do arquivo de "path", cujos atributos estejam na lista informada pelo parâmetro "attributes".

Caso exista um arquivo que satisfaça a pesquisa, será retornado um objeto da classe SearchRecord, com as informações do arquivo. Caso contrário, será retornado null.

Parameters:
Name Type Argument Description
fileName string

Diretório e máscara do arquivo buscado. É permitido o uso de coringas. Exemplo: ".\test\." localiza todos os arquivos no diretório teste.
opt_attributes string <optional>

Atributos dos arquivos que devem ser localizados. Deve ser informada uma lista separada por "," dos valores abaixo: "readOnly","hidden", "sysFile", "volumeID", "directory", "archive" ou "anyFile". Se não for informado, será considerado "anyFile".
See:
Returns:

Uma instância de SearchRecord caso localize um arquivo ou null se não encontrar ocorrência.

Type
SearchRecord
Example
var File = require('@nginstack/engine/lib/io/File');
var fileNames = [];
var path = File.pathAppend(engine.dataDir, "*.*");
var sr = File.findFirst(path, "archive");
try {
  var found = sr != null;
  while (found){
    fileNames.push(sr.name);
    found = File.findNext(sr);
  }
} finally {
  File.findClose(sr);
}

<static> findNext(searchRecord)

FindNext localiza a próxima ocorrência de uma pesquisa iniciada pelo método File.findFirst. O parâmetro "searchRecord" será atualizado com as informações do próximo arquivo localizado.

Parameters:
Name Type Description
searchRecord SearchRecord

Informações do último arquivo localizado.
See:
Returns:

true se existir mais uma ocorrência.

Type
boolean

<static> getSize(fileName)

Obtém o tamanho em bytes do arquivo informado.

Parameters:
Name Type Description
fileName string

Nome do arquivo do qual se deseja obter o tamanho.
Returns:

Tamanho em bytes do arquivo informado. Será retornado 0 caso seja informado um arquivo que não existe.

Type
number

<static> getTempFileName()

Cria um nome único para um arquivo temporário.

É responsabilidade do desenvolvedor excluir os arquivos criados com os nomes retornados por esta função. Os arquivos que não forem removidos após o seu uso, serão removidos automaticamente pelo Engine apenas na próxima inicialização do sistema. Em servidores, esse descarte automático pode levar dias, portanto é importante que os arquivos sejam removidos antes, evitando o desperdício de espaço em disco do servidor.

See:
Returns:

Nome de arquivo único

Type
string
Example
const File = require('@nginstack/engine/lib/io/File.js');
const tmpFileName = File.getTempFileName();
const file = new File(tmpFileName);
try {
  // use temp file ...
} finally {
  file.close();
  File.deleteFile(tmpFileName);
}

<static> listEntries(path [, options])

Retorna informações dos arquivos e diretórios contidos no diretório informado em path.

Esta função não retorna os subdiretórios especiais "." e ".." existentes em cada diretório.

Parameters:
Name Type Argument Description
path string

Diretório que terá as informações dos subdiretórios e arquivos retornadas.
options Object <optional>
Properties
Name Type Argument Description
recursive boolean <optional>

Indica se serão analisados os arquivos dos subdiretórios de path, recursivamente. Por padrão é considerado false.
onlyFiles boolean <optional>

Indica que devem ser retornadas apenas as informações dos arquivos normais contidos no diretório informado em path. Não serão retornadas informações de diretórios ou de arquivos especiais do sistema operacional.
filter function <optional>

Função de filtro que permite indicar se um arquivo ou diretório deve ser adicionado no resultado. Ela deve retornar true para indicar que uma entrada é válida e deve tratar adequadamente entradas do tipo diretório caso o parâmetro recursive seja true. Ao retornar false para um diretório, serão ignorados todos os arquivos e subdiretórios desse diretório.
Returns:

Um array de objetos contendo as propriedades indicadas pelo tipo FileListEntry.

Type
Array.<FileListEntry>
Examples
var File = require('@nginstack/engine/lib/io/File');
var dirCount = 0;
var fileCount = 0;
var files = File.listEntries(".");
files.forEach(function (file){
  if (file.isDirectory) {
    dirCount++;
  } else {
    fileCount++;
  }
});

var result = 'Engine directory has ' + dirCount + ' directories and ' +
  fileCount + ' regular files.';
var File = require('@nginstack/engine/lib/io/File');
var files = File.listEntries("dbCache", {onlyFiles: true});
var size = files.reduce(function (r, v){ return r + v.size }, 0);
var sizeMB = size / 1024 / 1024;
const File = require('@nginstack/engine/lib/io/File');
const replaceAll = require('@nginstack/engine/lib/string/replaceAll');
// Importa o conteúdo do diretório dirName no diretório targetDirKey da VFS
const files = File.listEntries(dirName, {onlyFiles: true});
files.forEach(function (file){
  const content = File.stringFromFile(file.path);
  const relativePath = replaceAll(file.relativePath, File.pathSeparator, "/");
  const fileKey = virtualFS.fileExists(relativePath, targetDirKey);
  if (fileKey){
    virtualFS.setFileContent(fileKey, content);
  } else {
    fileKey = virtualFS.createFile(relativePath, content, targetDirKey);
  }
});
const File = require('@nginstack/engine/lib/io/File.js');
// Este exemplo incluirá apenas arquivos com a extensão ".js" e ignorará os
// arquivos do diretório "node_modules".
File.listEntries(dirName, {
  recursive: true,
  filter: function (info) {
    if (info.isDirectory) {
      return info.name !== 'node_modules';
    } else {
      return info.name.endsWith('.js');
    }
  }
});

<static> moveFile(existingFileName, newFileName)

Método de classe que permite mover um arquivo. O diretório do arquivo de destino será criado caso não exista.

Parameters:
Name Type Description
existingFileName string

Nome do arquivo de origem.
newFileName string

Nome do arquivo de destino.
See:
Returns:

True se conseguiu mover o arquivo

Type
boolean
Example
var File = require('@nginstack/engine/lib/io/File');
var renamed = File.moveFile( 'c:\\MyFile.txt', 'c:\\MyFile2.txt' )
if ( !renamed ){
  throw new Error( 'Erro estranho. Possivelmente não há espaço em disco.')
}

<static> openForRead(path)

Abre o arquivo informado para leitura, gerando um erro caso o arquivo não exista.

Parameters:
Name Type Description
path string
Returns:
Type
File

<static> pathAppend(path, append)

Concatena dois ou mais paths, separando-os por um "File.pathSeparator". O método suporta tanto receber o segundo argumento sendo um array que contém todos os paths a serem concatenados como também uma quantidade qualquer de strings, os paths a serem concatenados ao path base. Se for informado um path contendo separadores incompatíveis com "File.pathSeparator", eles serão ajustados para o separador correto, de acordo com o sistema operacional.

Parameters:
Name Type Argument Description
path string

A base que receberá o path a ser adicionado. Opcionalmente, pode terminar com a string File.pathSeparator.
append Array.<string> | string <repeatable>

O path que será adicionado. Este pode ser uma sequência, de uma ou mais strings, ou ainda um array de strings. Opcionalmente, este parâmetro pode iniciar com a string File.pathSeparator.
Returns:

A concatenação dos dois paths.

Type
string
Examples
var File = require('@nginstack/engine/lib/io/File');
var paths = ['teste1', '\\teste2', '\\teste3\\', 'teste4'];
var finalPath = File.pathAppend('C:\\MyDirectory\\', paths);
var File = require('@nginstack/engine/lib/io/File');
var finalPath = File.pathAppend('C:\\MyDirectory\\', 'teste1\\', '\\teste2', 'teste3');

<static> stringFromFile(fileName [, opt_encoding])

Lê o conteúdo do arquivo informado.

Parameters:
Name Type Argument Description
fileName string

Nome do arquivo a ser lido.
opt_encoding string <optional>

Tipo de codificação dos dados do arquivo. Esse parâmetro é case insensitive e aceita os valores "utf-8", "windows-1252", "iso-8859-1" ou "binary". Caso não seja informado será considerado o valor "binary", indicando que os dados do arquivo não serão interpretados como sendo de nenhum tipo de codificação.
Returns:

Conteúdo do arquivo.

Type
string

clear()

Esvazia o arquivo, deixando-o com zero bytes.

close()

Fecha o arquivo imediatamente, permitindo que um outro processo possa ler o arquivo sem depender da execução do Garbage Collector do JavaScript.

flush()

Força a atualização física do arquivo, garantindo que os dados não estão carregados no buffer da memória. Este método deve ser evitado, pois gera perda de performance.

read( [opt_count])

Lê uma string do arquivo a partir da posição atual.

Parameters:
Name Type Argument Description
opt_count number <optional>

Quantidade de bytes que a serem lidos. Caso não seja informado, será retornado o conteúdo do arquivo a partir da posição atual.
Returns:

Dados lidos do arquivo

Type
string

readln()

Lê uma linha do arquivo a partir da posição atual.

Returns:

Linha lida do arquivo.

Type
string

write(data)

Escreve o conteúdo informado no arquivo.

Parameters:
Name Type Description
data string | Uint8Array | ArrayBuffer

Dado que será escrito.

writeln(data)

Escreve uma string acrescida de um salto de linha ("\r\n" no Windows, "\n" no Linux) no arquivo.

Parameters:
Name Type Description
data string

Dado a ser escrito.