Class: File

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


new File(fileName [, opt_mode])

Classe que permite a manipulação de arquivos.

Parameters:
Name Type Argument Description
fileName string

Nome do arquivo.

opt_mode string <optional>

Modo como o arquivo deve ser aberto e nível de compartilhamento separados por vírgula. Modos: "openRead", "openWrite", "openReadWrite" ou "create". Compartilhamento: "denyAll", "denyWrite" ou "denyNone". Caso não seja informado, será assumido como "openReadWrite,denyNone".

Members


<static> pathSeparator :string

Separador de path utilizado pelo sistema operacional.

Type:
  • string

modified :Date

Data de modificação do arquivo.

Type:
  • Date

position :number

Posição atual no arquivo.

Type:
  • number

size :number

Tamanho do arquivo em bytes.

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 dirName. 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 dirName 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
var File = require('@nginstack/engine/lib/io/File');
var duplicated = File.moveFile( 'c:\\MyFile.txt', 'c:\\MyFile2.txt' )
if ( !duplicated ){
  throw new Error( 'Very strange error. Possible out of space disk.')
}

<static> createDirectory(dirName)

Método de classe que permite criar um diretório vazio. Este método é desaconselhado, 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
dirName string

Nome do diretório a ser criado.

See:
Returns:

True se conseguiu criar o arquivo

Type
boolean

<static> createTempDirName()

Obtém um nome de diretório único e temporário. Esse diretório será excluído quando o Engine for reiniciado. É recomendado que ele seja excluído pelo método File.deleteDirectory(dirName, true) logo após a sua utilização, agilizando assim, a limpeza dos recursos não mais utilizados.

Returns:

Nome do diretório temporário criado.

Type
string

<static> createTempFile()

Cria um objeto associado a um arquivo temporário. Método recomendado para manipulação de arquivos temporários, sendo uma alternativa ao getTempFileName.

See:
  • getTempFileName
Returns:

Instância de um arquivo temporário.

Type
File

<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 Default Description
dirName string

Nome do diretório que deve ser excluído.

recursive boolean <optional>
false

Indica se os diretórios e arquivos contidos em "dirName" devem ser excluídos. Caso o seu valor seja false, o diretório somente será excluído 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 poder 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)

Cria um arquivo com o conteúdo informado.

Parameters:
Name Type Description
fileName string

Nome do arquivo que deve ser criado

content string

Conteúdo que deve ser gravado no arquivo.


<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(server.applicationPath, "*.*");
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()

Método de classe que cria um nome único para um arquivo temporário. É responsabilidade do desenvolvedor excluir os arquivos criados com os nome originados por este método.

See:
  • createTempFile
Returns:

Nome de arquivo único

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

<static> listEntries(path [, opt_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.

opt_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.

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);
  }
});

<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 com compartilhamento que impede a escrita por outros processos. Ao contrário do "new File()", será gerado 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.

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)

Lê o conteúdo do arquivo informado.

Parameters:
Name Type Description
fileName string

Nome do arquivo a ser lido.

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 uma string no arquivo.

Parameters:
Name Type Description
data string | ArrayBuffer

Dado que será escrito.


writeln(data)

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

Parameters:
Name Type Description
data string

Dado a ser escrito.