Biblioteca VHD

Biblioteca VHD

A biblioteca vhd provê funções para manipular o HD Virtual do plug-in, como ler um arquivo, excluir, etc...

Todas as funções estão contidas na table/variável "VHD" da unidade "vhd.lua".

 

Exemplo de uso:

-- Primeiro, é necessário usar a unidade "vhd.lua" require("vhd.lua");    -- Agora é possível acessar as funções da biblioteca VHD.FUNCAO_DA_BIBLIOTECA(Parametro1, Parametro2, ...);

 

 

Funções da biblioteca vhd

 

function VHD.copyFile(srcFileName, dstFileName)

 

Copy the file in the virtual HD

 

Arguments:

•  
• srcFileName - String containing the path to the existing source file
• dstFileName - String containing the path of the new file

 

Remarks:

•  
• The paths are expanded using “vhd.expandFileName” before copying.
• If the file “dstFileName” already exists, it will be replaced by the copied file.

 

 

function VHD.expandFileName(shortFileName)

 

Expande o nome curto de um arquivo a fim de ter sua localização em relação à raiz do HD virtual.

 

Parâmetros:

•  
• shortFileName – o caminho encurtado de um arquivo  a ser expandido.

    

Retorno:

    Uma cadeia de caracteres, onde:

•  
• Se a cadeia de caracteres passada pelo parâmetro shortFileName iniciar com o caractere “/”, a função simplesmente retorna o valor passado no parâmetro (pois o nome do arquivo já está expandido, isto é, já está em relação à raiz do HD virtual).
• Caso contrário, a função procura pelo arquivo dentro de cada um dos diretórios de pesquisa (SEARCH PATHs) que foram previamente registrados (ver descrição da função “vhd.addSearchPath”). 
  • Caso encontre dentro de algum dos diretórios de pesquisa, a função retorna o caminho completo (expandido, com relação à raiz do HD virtual) do arquivo. 
  • Caso não encontre o arquivo, a função retorna o mesmo valor passado pelo parâmetro shortFileName.
• Esta função leva em consideração os aliases registrados pela função VHD.registerAlias, traduzindo o apelido e retornando o nome real do arquivo.

 

 

function VHD.addSearchPath(directory)

 

Adiciona um diretório à lista de "diretórios de pesquisa" (SEARCH PATH) do HD Virtual.

 

Parâmetros:

•  
• directory - cadeia de caracteres contendo o caminho expandido (isto é, em relação à raiz do HD Virtual) do diretório.

 

A função "vhd.expandFileName" utiliza estes diretórios de pesquisas na hora de expandir o nome curto de um arquivo.

 

 

function VHD.removeSearchPath(directory)

 

Remove um diretório da lista de "diretórios de pesquisa" (SEARCH PATH) que havia sido previamente registrado através a função "vhd.addSearchPath".

 

Parâmetros:

•  
• directory - cadeia de caracteres contendo o caminho expandido (isto é, em relação à raiz do HD Virtual) do diretório.

 

function VHD.registerAlias(aliases)

 

Registra aliases/apelidos para arquivos no VHD.

 

Parâmetros:

•  
• aliases - uma tabela lua contendo os aliases, onde cada par de chave-valor da tabela representa:
  • chave - uma cadeia de caracteres representando o aliases/apelido a ser criado
  • valor - o nome do arquivo no VHD que o alias deve traduzir.

 

Observações:

•  
• O alias funciona com a função VHD.expandFileName e com a função require do Lua.
• O alias é case-sensitive, isto é, "myFile" é diferente de "MyFile".
• O alias não pode começar com o caracter "/". O nome traduzido pode começar com "/"

 

Exemplo:

local aliases = {}; aliases["mylua"] = "init.lua"; aliases["myFile2"] = "secondFile.lua";   VHD.registerAlias(aliases);  require("myFile2");

 

 

 

function VHD.fileExists(fileName)

 

Verifica se um arquivo existe no HD virtual.

 

Parâmetros:

•  
• fileName - cadeia de caracteres contendo o caminho  a verificar.

 

Retorno:

    Retorna true caso o arquivo exista ou false se não existir.

 

Observação:

    Esta função expande o nome do arquivo (através de "vhd.expandFileName") antes de realizar a verificação.

 

function VHD.directoryExists(path)

 

Verifica se um diretório existe no HD virtual.

 

Parâmetros:

•  
• path - cadeia de caracteres contendo o caminho  a verificar.

 

Retorno:

    Retorna true caso o diretório exista ou false se não existir.

 

Observação:

    Esta função expande o caminho (através de "vhd.expandFileName") antes de realizar a verificação.

 

 

function VHD.openFile(fileName [, mode])

 

Esta função abre um arquivo do HD virtual no modo especificado.

 

Parâmetros:

•  
• fileName - cadeia de caracteres contendo o nome do arquivo a abrir.
• (OPCIONAL) mode - cadeia de caracteres definindo o modo em que o arquivo será aberto.Pode ser um dos seguintes valores:
  • "r" - modo somente leitura (padrão se omitido). A função falhará se o arquivo não existir.
  • "w" - modo escrita/leitura preservando o contendo do arquivo (se existir). Se o arquivo não existir, a função cria o arquivo.
  • "a" - modo append. Equivalente ao modo "w", porém o objeto stream retornado é posicionado no fim do arquivo.
  • "w+" - modo escrita/leitura, o conteúdo do arquivo é apagado se ele existir. Se o arquivo não existir, a função cria o arquivo.

 

Retorno:

•  
• Caso a função obtenha êxito, retorna um Objeto Stream representando o conteúdo do arquivo. Qualquer alteração feita no objeto stream é refletida no arquivo.
• Caso a função falhe, retorna nil e a mensagem de erro.

 

Observações:

•  
• Esta função expande o nome do arquivo (através de "vhd.expandFileName") antes de realizar a abertura.
• Para fechar o arquivo que foi aberto, você deve invocar o método close do objeto stream retornado. Se o objeto stream for coletado pelo coletor de lixo, o arquivo também é fechado automaticamente.
• Exceto para o modo "a", o objeto stream retornado aponta para o inicio do arquivo.
• Apenas o modo "r" é aceito para abrir arquivos que originalmente vieram no plug-in. Não é possível alterar o conteúdo destes arquivos

 

 

function VHD.forceDirectory(directoryPath)

 

Esta função cria, se necessário, um ou mais diretórios especificado por directoryPath no HD virtual.

 

Parâmetros:

•  
• directoryPath - cadeia de caracteres contendo o caminho do diretório a ser "forçado".

 

Retorno:

•  
• Caso o diretório já exista e não foi preciso fazer nada, a função retorna false.
• Caso o diretório não existia e a função conseguiu criá-lo, retorna true.
• Caso o diretório não exista mas a função também não consiga criá-lo, um erro é levantado.

 

Observações:

•  
• O valor de "directoryPath" deve ser um caminho absoluto no VHD (isto é, deve começar com o caracter "/")
• A criação de diretório ocorre de forma recursiva. Isto é, ao especificar "/diretorioNaoExistente1/diretorioA/diretorioB", a função irá criar "/diretorioNaoExistente1" primeiro, depois "diretorioA" dentro de "/diretorioNaoExistente1/", e, por fim, "diretorioB" dentro de "/diretorioNaoExistente1/diretorioA/".

 

 

function VHD.deleteFile(fileName)

 

Esta função remove um arquivo do HD virtual.

 

Parâmetros:

•  
• fileName - cadeia de caracteres contendo o caminho do arquivo a ser excluído.

 

Observações:

•  
• Esta função expande o nome do arquivo (através de "vhd.expandFileName") antes de realizar a remoção.
• Esta função não pode ser usada para remover diretórios.
• Não é possível apagar um arquivo que originalmente veio no plug-in. Não é possível alterar o conteúdo destes arquivos

 

 

function VHD.deleteDirectory(directoryPath)

 

Esta função remove um diretório e todo seu conteúdo do HD virtual.

 

Parâmetros:

•  
• directoryPath - cadeia de caracteres contendo o caminho do diretório que será excluído.

 

Observações:

•  
• Esta função expande o caminho do diretório (através de "vhd.expandFileName") antes de realizar a remoção.
• Não é possível apagar um arquivo que originalmente veio no plug-in. Não é possível alterar o conteúdo destes arquivos.
• Esta função apaga o diretório e todo seu conteúdo recursivamente.

 

 

 

function VHD.enumerateContent(directoryPath)

 

Esta função retorna quais arquivos e diretórios estão dentro de um diretório no HD Virtual.

 

Parâmetros:

•  
• directoryPath - cadeia de caracteres contendo o caminho do diretório que terá seu conteúdo enumerado.

 

Retorno:

•  
• Se "directoryPath" não conter um caminho válido de diretório, um erro será lançado.
• Senão, um array de strings será retornado, onde cada posição do arranjo contém o nome do diretório/arquivo.

 

Observações:

•  
• Esta função expande o caminho de directoryPath (através de "vhd.expandFileName") antes de realizar a enumeração..
• Esta função não enumera o conteúdo de forma recursiva. Isto é, se existirem sub-diretórios, seus conteúdos não serão enumerados neste retorno, apenas os itens que estão diretamente dentro de "directoryPath".
• O texto retornado no arranjo contém o nome do arquivo/diretório sem incluir "barras" ou outra forma de expressar o diretório que se encontra.
  • Exemplo: Se existirem dois arquivos (a.txt e b.txt) e um subdiretório ("/textos/histórias/") na pasta "/textos/", o retorno será:
  • {'a.txt', 'b.txt', 'histórias'}
• Para saber se um item do arranjo retornado é diretório ou é arquivo, utilize as funções VHD.fileExists e VHD.directoryExists

---

Created with the Personal Edition of HelpNDoc: Maximize Your Productivity with HelpNDoc's Efficient User Interface