Aprenda Programação: Arquivos e Serialização (Marshalling)

Pré-Requisitos

Na introdução sobre ambientes de desenvolvimento, indiquei Python, Lua e JavaScript como boas escolhas de linguagens de programação para iniciantes. Posteriormente, comentei sobre GDScript como opção para pessoas que tenham interesse em programar jogos digitais ou simulações. Para as atividades de introdução a programação, você precisará de, no mínimo, um ambiente de desenvolvimento configurado em uma das linguagens anteriores.

Caso queira experimentar programação sem configurar um ambiente, você pode usar um dos editores online que criei:

• JavaScript;
• Python;
• Lua.

Contudo, eles não possuem todos os recursos dos interpretadores para as linguagens. Assim, cedo ou tarde, você precisará configurar um ambiente de desenvolvimento. Caso precise configurar um, confira os recursos a seguir.

• JavaScript;
• Python;
• Lua;
• GDScript (Godot Engine).

Assim, se você tem um Ambiente Integrado de Desenvolvimento (em inglês, Integrated Development Environment ou IDE) ou a combinação de editor de texto com interpretador, você está pronto para começar. Os exemplos assumem que você saiba executar código em sua linguagem escolhida, como apresentado nas páginas de configuração.

Caso queira usar outra linguagem, a introdução provê links para configuração de ambientes para as linguagens C, C++, Java, LISP, Prolog e SQL (com SQLite). Em muitas linguagens, basta seguir os modelos da seção de experimentação para adaptar sintaxe, comandos e funções dos trechos de código. C e C++ são exceções, por requerem o uso de ponteiros para acesso à memória.

Memória Secundária, Sistemas de Arquivos e Arquivos

Alguns dos primeiros tópicos deste material definiram sistemas de arquivos. O primeiro dos tópicos sobre sistemas de arquivos definiu arquivos, diretórios (pastas) e caminhos (caminhos podem ser relativos ou absolutos). Para o uso de arquivos em programação, é importante entender sobre os conceitos de caminhos, caminhos relativos e caminhos absolutos. Em programação, normalmente é preferível usar arquivos com caminhos relativos, pois eles facilitam usar arquivos com uma mesma estrutura de diretórios em diferentes máquinas. Assim, caso você não sabia o que são caminhos ou um diretório de trabalho (work directory ou work dir), a leitura do tópico mencionado é recomendada para entender este tópico.

O segundo tópico sobre sistemas de arquivos descreveu gerenciadores de arquivos, programas que permitem realizar operações comuns para criação, organização e manipulação de arquivos e diretórios. Em particular, um gerenciador de arquivos será necessário neste tópico, para que você possa acessar o conteúdo que criar.

Linguagens de programação também fornecem recursos e abstrações para manipular arquivos. Arquivos são abstrações da memória secundária (persistente) de uma máquina. Pode-se criar um novo arquivo (vazio), escrever dados neles e salvá-lo no disco. Um arquivo salvo pode ser carregado e lido. Ele também pode ser modificado, realizando-se novas operações de escrita. Com as operações anteriores, é possível salvar dados em uma sessão do programa para carregá-los em qualquer momento futuro no qual os dados armazenados sejam necessários.

Contudo, nem todo arquivo é manipulado da mesma forma. Linguagens de programação costumam fornecer dois tipos de arquivos:

1. Arquivos texto (ou arquivos de texto ou text files);
2. Arquivos binário (ou binary files).

Arquivos texto são arquivos que armazenam dados codificados como texto. Por exemplo, todos os arquivos de código-fonte criados para JavaScript, Lua, Python e GDScript são arquivos texto. Você pode criar, abrir e modificar arquivos texto usando um editor de texto. Arquivos texto são convenientes para uso e leitura por seres humanos, mas requerem mais bytes para armazenamento (por exemplo, o número inteiro 01234 é salvo como o texto "01234", que requer, por exemplo, 5 bytes para a escrita em ASCII ou UTF-8), tempo para processamento e permitem acesso seqüencial (isto é, a leitura é feita byte a byte).

Arquivos binários são arquivos que armazenam dados codificados pelos tipos os quais representam. Por exemplo, o número inteiro 01234 seria salvo como a seqüencia de bytes 00000100 11010010 (que pode ser escrita em 2 bytes). Para ler e editar um arquivo binário, usa-se um editor hexadecimal (hexadecimal editor ou hex editor) ao invés de um editor de texto. Arquivos binários tendem a ser menores (tamanho em bytes) que arquivos texto, mais rápidos para escrita e leitura, e permitem acesso aleatório (isto é, a leitura de uma posição específica do arquivo), porém não são acessíveis para seres humanos. A maioria dos arquivos de imagens, vídeos e áudio são exemplos típicos de arquivos binários. Embora seja possível abri-los em um editor de texto, o resultado não será o esperado. De fato, a manipulação e o uso eficiente de arquivos binários costumam requerer programas especializados. Por exemplo, um visualizador ou editor de imagens, ou um reprodutor (player) ou editor de áudio ou vídeo.

Qualquer que seja o caso, todo programa que retém informações entre usos utiliza arquivos. Mesmo implementações de sistemas gerenciadores de bancos de dados (SGDBs) utilizam arquivos internamente. Assim, convém aprender a usar arquivos.

Antes, contudo, um aviso é necessário.

O aviso pode ser assustador, mas é importante. Como arquivos utilizam memória secundária, os resultados de operações são persistentes. Assim, é importante tomar os devidos cuidados para se evitar perda indesejada de dados.

Para minimizar chances de conflitos de nomes, todos os arquivos criados terão o prefixo franco-garcia-. Por exemplo, franco-garcia-meu_arquivo.txt ao invés de meu_arquivo.txt ou meu arquivo.txt. Todos os arquivos serão criados no diretório de trabalho, que provavelmente será o mesmo no qual o arquivo com o código-fonte for salvo e/ou o código for interpretado. Exceto caso você também chame Franco Garcia e/ou crie arquivos usando o mesmo prefixo e convenção, as chances de ter arquivos com o mesmo nome serão baixas. Entretanto, elas existem e requerem cuidados de sua parte. Caso você precise modificar os nomes, o caminho (nome e diretório) do arquivo a ser utilizado estará definido variável no início do código de cada programa (mas que pode estar após definições de subrotinas, constantes e registros), chamada caminho_arquivo (no caso do exemplo para cópia, também existirá uma variável chada caminho_copia). Preferencialmente, escolha um nome único, para não correr o risco de sobrescrever um arquivo existente.

Uma boa prática para atividades introdutórias é criar um novo diretório em seu computador para usar como diretório de trabalho para os programas. Todos os arquivos que você criar ou ler devem pertencer a este diretório. Outro benefício da criação de um diretório é que você terá certeza que o local escolhido permite operações de escrita. Sistemas operacionais podem restringir o acesso a arquivos e diretórios, assim como operações de leitura e escrita, para certas combinações de conta de usuário e diretório. Isso é chamado de permissões de acesso. Sempre que se trabalhar com arquivos, é necessário que a conta atual tenha permissão de leitura para o diretório e arquivo (caso se deseje ler um arquivo), e/ou permissão de escrita para o diretório e arquivo (caso se queira criar um novo arquivo, escrever nele ou modificar um arquivo existente). Erros de permissão são comuns, especialmente em máquinas compartilhadas. Assim, se seu código estiver correto, mas um programa não funcionar, verifique se você possui permissões suficientes para o caminho definido para o arquivo.

Arquivos Texto (Text Files)

Arquivos texto tendem a ser mais simples de operar que arquivos binários. Isso ocorre por alguns motivos:

1. Pode-se inspecionar o conteúdo de um arquivo texto usando-se um editor de textos;
2. Pode-se modificar o conteúdo de um arquivo texto usando um editor de texto;
3. Existem diversas ferramentas de linha de comando para manipulação de arquivos texto. De fato, sistemas baseados em Unix (como Linux) utilizam primariamente arquivos texto para configuração e troca de dados em programas de linha de comando;
4. Em programação, operar com arquivos textos é similar a usar subrotinas ou comandos como print() e input().

O último motivo pode parecer estranho, mas é aplicável a muitas linguagens de programação. Muitas linguagens abstraem operações em consoles (terminais) usando arquivos. Em linguagens assim, existem três arquivos com nomes e propósitos especiais:

1. Saída padrão (standard output), mais conhecida como stdout;
2. Entrada padrão (standard input), mais conhecida como stdin;
3. Saída de erro padrão (standard error), mais conhecida como stderr.

O uso de print() ou console.log() redireciona a mensagem escrita para stdout, que, então, é escrito em um terminal. O uso de input() ou io.read() e similares usa stdin como um buffer (memória) de entrada, usado para armazenar temporariamente valores lidos do teclado. É por isso que algumas subrotinas ou comandos de leitura (como io.read() em Lua) fornecem valores incorretos após a leitura de certos tipos de dados -- restos de dados lidos podem ficar armazenados no arquivo stdin, sendo fornecidos para a próxima leitura. Embora, no caso de Lua, a razão seja o uso de uma subrotina C usada para a leitura pela linguagem.

A saída de erro padrão não foi abordada em tópicos anteriores, mas, a partir deste momento, você pode começar a usá-la em seus programas. Por exemplo:

console.error("Mensagem de erro")
// JavaScript também possui uma mensagem de aviso:
console.warn("Mensagem de aviso")

import sys

print("Mensagem de erro", file=sys.stderr)

# Python também possui uma mensagem de aviso:
import warnings
warnings.warn("Mensagem de aviso")

io.stderr:write("Mensagem de erro")
error("Mensagem de erro")

extends Node

func _ready():
    printerr("Mensagem de erro")
    # JavaScript também possui uma mensagem de aviso:
    push_warning("Mensagem de aviso")

Documentações (as versões para aviso podem usar outro arquivo de saída -- por exemplo, stdout ou algum outro):

• JavaScript: console.error() (documentação) e console.warn() (documentação). O suporte para console.error() e console.warn() tende a variar entre navegadores. Assim, deve-se usá-lo apenas durante desenvolvimento (ou seja, não para sistemas para produção ou para uso de usuárias ou usuários finais);
• Python: sys.stderr (documentação) e módulo warnings (documentação);
• Lua: io.stderr (documentação) ou error() (documentação);
• GDScript: printerr() (documentação) e push_warning() (documentação).

Os exemplos anteriores ilustram o que fazer para escrever em outro arquivo: deve-se designá-lo de alguma forma para indicar em qual arquivo a saída deverá ocorrer. O mesmo princípio vale para arquivos criados pela programadora ou pelo programador. A diferença é que, neste caso, a pessoa deverá realizar, no mínimo, duas tarefas adicionais: abrir (ou criar um arquivo) antes do uso e fechar o arquivo aberto quando ele não for mais necessário.

Operações Básicas Usando Arquivos Texto

Existem três formas principais de usar um arquivo:

1. Usar um arquivo para escrita de dados;
2. Usar um arquivo para leitura de dados;
3. Usar um arquivo para leitura e escrita de dados.

Nos exemplos a seguir, a primeira subseção criará um arquivo de texto com cinco linhas.

Olá, meu nome é Franco.
Olá, meu nome é Franco.
1 2 3
-1.23

As duas primeiras linhas são frases. A terceira linha contém três números inteiros (que serão armazenados como texto). A quarta linha contém um número real, que será armazenado como texto. A quinta linha é uma linha vazia. Infelizmente, ela não aparece no código formatado em HTML.

Em seguida, criar-se-á um programa para ler o conteúdo escrito.

Toda operação de arquivo segue um mesmo modelo (padrão):

1. Abertura ou criação de um arquivo;
2. Operações usando o arquivo;
3. Fechamento do arquivo.

Um arquivo pode ser fechado quando não for mais necessário. Isso pode ser feito imediatamente após o término de todas as operações de leitura e/ou escrita, ou antes do final do programa. Contudo, não se deve usar um arquivo após fechá-lo; isso é um erro. Para usar um arquivo fechado, deve-se abri-lo novamente, repetindo-se o processo.

Além disso, é importante fechar o arquivo. Algumas implementações podem fazer isso automaticamente; pessoalmente, eu prefiro sempre fazê-lo. O fechamento do arquivo é importante para garantir que todos os dados sejam salvos. Por questões de desempenho, algumas implementações agrupam operações de escrita antes de salvá-las no arquivo. O fechamento força um despejo de memória (flush). Existem subrotinas para realizar um flush no momento desejado; elas devem ser usadas apenas para arquivos de saída (comumente chamados de fluxos de saída ou output streams).

Arquivos texto também são comumente usados para tarefas de logging, normalmente para fins de depuração. Pode-se armazenar mensagens ou valores de interesse em um arquivo para inspecioná-los em caso de problemas ou travamentos de um programa. Algumas linguagens de programação fornecem implementações para log na biblioteca padrão. Caso elas não existam, é comum existirem bibliotecas que forneçam a funcionalidade. Caso contrário, basta criar um arquivo de texto e mantê-lo aberto durante o uso do programa. Quando se quiser persistir uma mensagem, basta usá-lo. Antes do final do programa, fecha-se o arquivo.

Escrita de Arquivo Texto

Para escrever em um arquivo texto, deve-se converter os dados desejados para uma cadeia de caracteres. Algumas implementações fazem conversões de tipos automaticamente; caso uma não fizer, basta fazer a conversão antes. Para melhor desempenho, costuma ser melhor armazenar o todo conteúdo em uma cadeia de caracteres para se escrever de uma única vez. Uma variável utilizada assim é chamada de buffer.

Embora seja possível usar JavaScript fora de navegadores, o exemplo a seguir considera o uso da linguagem em navegadores. Por isso, ele será um pouco diferente das versões escritas para Python, Lua e GDScript, que são comumente usadas fora de um navegador.

let caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
let conteudo = "Olá, meu nome é Franco.\n"
conteudo += "Olá, meu nome é Franco.\n"
conteudo += "1 2 3\n"
conteudo += "-1.23\n"

let arquivo = new File([conteudo], caminho_arquivo, {type: "text/plain"})
console.log("Arquivo criado com sucesso.")

let link_download = document.createElement("a")
link_download.target = "_blank"
link_download.href = URL.createObjectURL(arquivo)
link_download.download = arquivo.name
if (confirm("Fazer download do arquivo '" + arquivo.name + "'?")) {
    link_download.click()
    // Neste caso, revokeObjectURL() poderia ser usado tanto para confirmação,
    // quanto para cancelamento.
    URL.revokeObjectURL(link_download.href)
}

import io
import sys

try:
    caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    arquivo = open(caminho_arquivo, "w")

    arquivo.writelines([
        "Olá, meu nome é Franco.\n",
        "Olá, meu nome é Franco.\n",
        "1 2 3\n",
        "-1.23"
    ])

    arquivo.close()

    print("Arquivo criado com sucesso.")
except IOError as excecao:
    print("Erro ao tentar criar arquivo de texto.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar criar arquivo de texto.", file=sys.stderr)
    print(excecao)

-- <https://en.cppreference.com/w/c/program/EXIT_status>
local EXIT_FAILURE = 1

local caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
local arquivo = io.open(caminho_arquivo, "w")
if (arquivo == nil) then
    print(debug.traceback())

    error("Erro ao tentar criar arquivo de texto.")
    os.exit(EXIT_FAILURE)
end

arquivo:write("Olá, meu nome é Franco.\n")
arquivo:write("Olá, meu nome é Franco.\n")
arquivo:write("1 2 3\n")
arquivo:write("-1.23\n")

io.close(arquivo)

print("Arquivo criado com sucesso.")

extends Node

# <https://en.cppreference.com/w/c/program/EXIT_status>
const EXIT_FAILURE = 1

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.WRITE) != OK):
        printerr("Erro ao tentar criar arquivo de texto.")
        get_tree().quit(EXIT_FAILURE)

    arquivo.store_string("Olá, meu nome é Franco.\n")
    arquivo.store_string("Olá, meu nome é Franco.\n")
    arquivo.store_string("1 2 3\n")
    arquivo.store_string("-1.23\n")

    arquivo.close()

    print("Arquivo criado com sucesso.")

A execução dos programas em Python, Lua e GDScript gerará um arquivo texto chamado franco-garcia-arquivo_texto_escrita.txt no diretório em que o programa for executado (ou seja, no diretório de trabalho). A execução do programa em JavaScript gerará um arquivo texto que pode ser salvo na máquina. Todos os arquivos terão o mesmo conteúdo; é possível usar um editor de texto para abrir o arquivo e ler o conteúdo. Também é possível modificar o arquivo resultante em um editor de texto. Contudo, os exemplos de leitura assumem a existência dos dados criados no programa; portanto, caso você modifique os valores, execute os programas novamente para gerar um arquivo equivalente ao original.

Os exemplos em Python, Lua e GDScript fornecem a forma clássica de trabalhar com arquivos.

A versão em Python abre um novo arquivo usando open() (documentação; é possível usar um parâmetro nomeado para a escolha de codificação; por exemplo, encoding="utf-8"). O parâmetro "w" (write ou escrita) indica o modo da abertura de arquivo; "w" significa abrir o arquivo em modo de escrita, criando um novo arquivo vazio (caso ele não exista) ou apagando todos os dados existentes (caso o arquivo exista). Em seguida, a manipulação do arquivo é feita usando a classe TextIOBase (documentação) e TextIOWrapper (documentação). O método writelines() (documentação) permite escrever um vetor de cadeias de caracteres no arquivo. Ao final do uso, utiliza-se close() (documentação) para fechar o arquivo.

A versão em Lua usa io.open() (documentação) para abrir o arquivo; o parâmetro "w" funciona da mesma forma que em Python. A escrita utiliza io.write() (documentação). Após o término do uso, io.close() (documentação) permite fechar o arquivo. Como io.open(), io.write() e io.close() usam, respectivamente, file.open(), file.write() e file.close(), convém consultar também a documentação desses métodos. Em caso de erro, os.exit() (documentação) permite terminar o programa prematuramente. EXIT_FAILURE é uma constante definida em C para indicar o término de um programa como erro (documentação); como ela não existe em Lua, definiu-se uma com o valor 1 (o valor pode variar entre sistemas operacionais e plataformas; 1 é um valor comum para arquiteturas para desktop). A função debug.traceback() (documentação) provê dados sobre a pilha de chamadas (call stack) no momento do erro.

A versão em GDScript utiliza a classe File (documentação) para as operações. O método open() (documentação) abre o arquivo; o parâmetro File.WRITE (documentação) indica o modo de escrita, funcionando da mesma forma que "w". O método store_string() (documentação) permite escrever uma cadeia de caracteres no arquivo. Ao final do uso, close() (documentação) permite fechar o arquivo. A constante EXIT_FAILURE é definida como em Lua, seguindo as mesmas considerações. Para terminar o programa, usa-se get_tree() (documentação), depois quit() (documentação).

Em JavaScript para back-end (por exemplo, usando Node.js), é possível usar arquivos como em Python, Lua e GDScript. Para front-end (ou seja, em navegadores), o uso é um pouco diferente, como ilustrado no exemplo. Ao invés de criar-se um arquivo no sistema, cria-se um arquivo temporariamente no navegador para download (ser baixado para a máquina). Isso requer que todo o texto a ser armazenado esteja pronto (no caso, ele está salvo em conteudo). Em seguida, usa-se File() (documentação) para criar o arquivo. O tipo escolhido "text/plain" é uma designação de media type ou Multipurpose Internet Mail Extensions types (MIME type; documentação). Com o arquivo criado, gera-se um link na página usando-se document.createElement() (documentação) que é preenchido com os dados do arquivo: destino em target ("_blank" significa nova aba ou janela), endereço para o arquivo em href (gerado com URL.createObjectURL(); documentação), e nome do arquivo para download em download. Por fim, cria-se um diálogo de confirmação usando-se confirm() (documentação). Caso a pessoa confirme o diálogo, clica-se programaticamente no link criado usando-se click() (documentação). Em seguida, remove-se o link para download com URL.revokeObjectURL() (documentação). O arquivo será transferido do navegador para o computador, como se fosse um download real. Entretanto, como o código é local, não é necessária conexão com a Internet para se obter o arquivo resultante.

Além do modo "w" para escrita, outro modo usual chama-se append ("a"), que funciona de forma similar à "w" caso o arquivo não exista. Contudo, caso um arquivo com o mesmo caminho exista, o modo append abre o arquivo existente no fim para a adição de novos dados (ao invés de apagar o conteúdo existente). Isso é bastante prático quando se deseja acrescentar novos conteúdos no fim de um arquivo, como em um log. A inclusão de novos dados é fácil no final um arquivo texto, mas mais complicada (e menos eficiente) em qualquer outra posição.

Também existe o modo "rw+" ou "r+w", que abre o arquivo em modo de leitura e escrita. O modo é útil para edição de arquivos existentes, pois preserva os valores armazenados (caso um arquivo já exista) ou cria um arquivo vazio (caso o arquivo não exista). Diferentemente de append, o arquivo pode ser lido e escrito em qualquer posição (ao invés de apenas escrito no fim). Contudo, a escrita antes do final do arquivo requer mover o conteúdo existente para frente. Como será comentado como uma técnica, costuma ser mais simples criar um novo arquivo com o conteúdo modificado e sobrescrever o original (ou mantê-lo como back-up).

Fechamento Automático ao Final de Escopo

Em Python e Lua (a partir da versão 5.4), existe uma forma alternativa de fechar um arquivo. A alternativa fecha automaticamente o arquivo após o final do escopo da variável. O exemplo a seguir utiliza a escrita de um arquivo texto; contudo, bastaria modificar as chamadas de open() em Python ou io.open() em Lua para usá-las com quaisquer outros tipos ou operações com arquivos.

import io
import sys

caminho_arquivo = "franco-garcia-arquivo_texto_escrita_escopo.txt"
with open(caminho_arquivo, "w") as arquivo:
    arquivo.writelines([
        "Olá, meu nome é Franco.\n",
        "Olá, meu nome é Franco.\n",
        "1 2 3\n",
        "-1.23"
    ])

    print("Arquivo criado com sucesso.")
    # Fim do escopo; arquivo fechado automaticamente.

print("Arquivo foi fechado.")

local EXIT_FAILURE = 1

local caminho_arquivo = "franco-garcia-arquivo_texto_escrita_escopo.txt"
do
    local arquivo <close> = io.open(caminho_arquivo, "w")
    if (arquivo == nil) then
        print(debug.traceback())

        error("Erro ao tentar criar arquivo de texto.")
        os.exit(EXIT_FAILURE)
    end

    arquivo:write("Olá, meu nome é Franco.\n")
    arquivo:write("Olá, meu nome é Franco.\n")
    arquivo:write("1 2 3\n")
    arquivo:write("-1.23\n")

    print("Arquivo criado com sucesso.")
    -- Fim do escopo; arquivo fechado automaticamente.
end

print("Arquivo foi fechado.")

Em Lua, pode-se forçar a criação de um novo escopo usando um par do e end (isso pode não ser necessário caso se defina o código dentro de uma subrotina, que possuirá sem próprio escopo local). Em seguida, usa-se o modificador <close> para indicar que se deseja fechar o arquivo ao final do escopo (documentação). Também é possível definir <close> personalizados para tipos definidos como registros em tabelas.

Em Python, usa-se a palavra reservada with para a abertura do arquivo (documentação). Deve-se notar que exceções ainda podem ocorrer (o tratamento foi omitido no código).

A forma alternativa fecha o arquivo assim que o escopo terminar. Isso possui duas vantagens. A primeira é que não se corre o risco de fechar o arquivo. A segunda é que o arquivo é fechado automaticamente em caso de problemas (como exceções). Assim, o fechamento automático pode ser mais seguro que a forma tradicional. Em C++, a generalização dessa técnica é chamada de resource acquisition is initialization (RAII; aquisição de recurso é inicialização).

Leitura de Arquivo Texto

Existem três formas principais de ler um arquivo texto:

1. Ler o arquivo todo como uma única cadeia de caracteres;
2. Separar o conteúdo do arquivo em um vetor de valores separados por um delimitador. Por exemplo, ler o arquivo linha por linha;
3. Extrair dados do arquivo texto. Na terceira forma, tenta-se extrair os dados e convertê-los para variáveis de tipos mais apropriados.

Também existem outras formas, como ler o arquivo caractere por caractere. O final de um arquivo texto possui um valor especial chamado end of file (EOF, que significa fim do arquivo). Para comodidade de processamento, é comum terminar o arquivo com uma linha vazia antes de EOF (embora ela não seja necessária).

Leitura do Arquivo Texto Inteiro

A leitura do arquivo texto inteiro normalmente é simples, embora possa requerer mais memória primária que as outras formas de leitura. Armazenar todo o conteúdo de um arquivo em uma variável é útil como otimização, para evitar múltiplas leituras de dados da memória secundária (mais lenta que a primária). Após a leitura de todo o conteúdo, pode-se processar a variável lida como qualquer outra cadeia de caracteres.

A versão em JavaScript não poderá ser usada diretamente, pois ela requer uma página definida em código HTML para acompanhá-la (o código HTML é apresentado na seqüência desta seção). Ela também será mais complexa que as demais, por algumas restrições impostas por navegadores. Por outro lado, a implementação permitirá exibir o conteúdo lido no navegador.

// Este código deve ser salvo em um arquivo chamado "script.js".
// Ele será processado por uma página HTML com código para envio do arquivo
// texto via formulário.

// <https://www.francogarcia.com/pt-br/blog/ambientes-de-desenvolvimento-javascript/>
function adicione_elemento(valor, nome_elemento = "p") {
    const pai = document.getElementById("conteudo")
    const novo_elemento = document.createElement(nome_elemento)
    novo_elemento.innerHTML = valor
    pai.appendChild(novo_elemento)
}

function leia_arquivo(arquivo_texto) {
    // console.log(arquivo_texto)
    if (!arquivo_texto) {
        return
    } else if (!(arquivo_texto instanceof File)) {
        return
    }

    let leitor_arquivos = new FileReader()
    leitor_arquivos.onload = function(evento) {
        let conteudo = evento.target.result
        console.log(conteudo)

        // Troca todas as ocorrência de \n por uma tag de quebra de linha <br/>
        // para exibição do texto no navegador.
        // Opcionalmente, caso o sistema defina quebras de linha como \r\n,
        // a expressão regular troca ambas as ocorrências pela tag.
        adicione_elemento(conteudo.replace(new RegExp("\\r?\\n", "g"), "<br/>"))
    }
    leitor_arquivos.readAsText(arquivo_texto)

    // Impede a submissão do formulário, permitindo a visualização do
    // resultado de adicione_elemento() na mesma página.
    return false
}

import io
import sys

try:
    caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    arquivo = open(caminho_arquivo, "r")
    conteudo = arquivo.read()
    arquivo.close()

    print("Arquivo lido com sucesso.")
    print(conteudo)
except IOError as excecao:
    print("Erro ao tentar ler arquivo de texto.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar ler arquivo de texto.", file=sys.stderr)
    print(excecao)

local EXIT_FAILURE = 1

local caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
local arquivo = io.open(caminho_arquivo, "r")
if (arquivo == nil) then
    print(debug.traceback())

    error("Erro ao tentar ler arquivo de texto.")
    os.exit(EXIT_FAILURE)
end

local conteudo = arquivo:read("*all")
io.close(arquivo)

print("Arquivo lido com sucesso.")
print(conteudo)

extends Node

const EXIT_FAILURE = 1

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.READ) != OK):
        printerr("Erro ao tentar ler arquivo de texto.")
        get_tree().quit(EXIT_FAILURE)

    var conteudo = arquivo.get_as_text()
    arquivo.close()

    print("Arquivo lido com sucesso.")
    print(conteudo)

A estrutura de um código para ler um arquivo é similar a usada para escrever em um arquivo, pois ela também começa com a abertura do arquivo e termina com o fechamento dele. Uma tentativa de ler um arquivo inexistente resultaria em erro. O programa tentará ler o arquivo criado gerado pelo programa anterior para criação de arquivo texto. Caso ele tenha sido apagado por qualquer motivo, deve-se recriá-lo.

Em Python, a operação de leitura usa o parâmetro "r" (read ou leitura). Em seguida, o uso do método read() (documentação) sem nenhum parâmetro permite ler o arquivo todo; a provisão de um parâmetro permite ler partes do arquivo (o parâmetro é um número com a quantidade desejada de bytes para a leitura). Alternativamente, pode-se usar readall() (documentação) para a leitura do arquivo todo.

Em Lua, também usa-se o parâmetro "r" para se especificar o modo de leitura. O uso de file:read() (documentação) permite ler dados do arquivo da mesma forma que para io.read() (documentação) para a entrada padrão. Assim, pode-se ler um número com "*number", uma linha com "*line", o arquivo todo com "*all" ou uma quantidade de bytes especificando-se um número inteiro.

Em GDScript, o método get_as_text() (documentação) lê o arquivo todo como um texto codificado em UTF-8. Para a leitura de partes do arquivo, deve-se usar os outros métodos disponíveis.

A versão em JavaScript requererá uma página HTML com um formulário para envio do arquivo, pois, por motivos de segurança, o envio de um arquivo em um navegador requer que uma usuário ou um usuário inicie a interação com um clique (ou com qualquer interação explícita). A página é uma adaptação do exemplo fornecido para configuração de ambiente em JavaScript. O procedimento adicione_elemento() também foi definido no exemplo da configuração de ambiente. Neste tópico, ele é usado para exibir o conteúdo do arquivo no navegador.

<!DOCTYPE html>
<html lang="pt-BR">

  <head>
    <meta charset="utf-8">
    <title>Leitura de Arquivo Texto</title>
    <meta name="author" content="Franco Eusébio Garcia">
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>

  <body>
    <header>
      <h1>Leitura de Arquivo</h1>
    </header>

    <main>
      <!-- Formulário para envio do arquivo texto. -->
      <form method="post"
            enctype="multipart/form-data"
            onsubmit="return leia_arquivo(arquivos.files[0])">
        <label for="arquivos">Escolha um arquivo texto:</label>
        <input id="arquivos"
               name="arquivos"
               type="file"
               accept="text/plain"/>
        <input type="submit"/>
      </form>

      <div id="conteudo">
      </div>

      <!-- O nome do arquivo JavaScript deve ser igual ao definido abaixo. -->
      <script src="./script.js"></script>
    </main>
  </body>

</html>

Na página HTML, define-se um formulário usando-se a tag <form> (documentação). O formulário contém uma tag de entrada <input> (documentação), configurada para a escolha de um arquivo (file picker). Para isso, usa-se type="file" (documentação). O formulário possui um botão para envio do arquivo escolhido, definido por <input type="submit"/>. O processamento feito pela função leia_arquivo(), como definido em onsubmit na definição de <form>. A função leia_arquivo() deverá estar implementada no arquivo script.js, armazenado no mesmo diretório do arquivo HTML.

No caso, o formulário faz processamento local, então nenhum dado é enviado para a Internet. No código JavaScript, instanceof (documentação) verifica se a variável é instância do tipo File. Caso o parâmetro represente um arquivo, usa-se FileReader (documentação) para a leitura do conteúdo. A leitura é feita na chamada do método readAsText() (documentação). Quando ela termina, a implementação executa o código definido em onload (documentação), que deve ser definido antes da chamada de readAsText(). Em onload, definiu-se uma função anônima (lambda) para escrever o conteúdo no console (terminal) e também na página exibida 2 2navegador, usando adicione_elemento(). A expressão regular troca quebras de linha da cadeia de caracteres por tags para quebra de linha no navegador, para que as linhas do texto apareçam corretamente.

No caso, onload define uma função callback, chamada pela implementação da classe FileReader para processar os dados lidos no momento adequado.

Leitura do Arquivo Texto Delimitado (Linha por Linha)

Quando a quantidade de memória primária (RAM) livre é suficiente para armazenar todo o conteúdo do arquivo, pode-se lê-lo de uma única vez. Embora isso seja comum em máquinas modernas (como computadores de mesa e dispositivos móveis recentes), existem máquinas com quantidades limitada de memória (como dispositivos embarcados). Em outros casos, pode ser desejável operar com partes menores do arquivo em memória primária.

Uma segunda abordagem comum para a leitura de arquivos textos é ler partes do arquivo até o próximo delimitador. Normalmente, o delimitador escolhido é a quebra de linhas. Ou seja, lê-se uma linha do arquivo de cada vez.

Implementações de arquivos texto comumente fornecem uma subrotina para a leitura de uma linha (JavaScript para navegadores é uma exceção). Com uma estrutura de repetição, pode-se ler cada linha do arquivo até seu final.

import io
import sys

try:
    caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    arquivo = open(caminho_arquivo, "r")

    linha_texto = arquivo.readline()
    while (linha_texto):
        print(linha_texto, end="")
        linha_texto = arquivo.readline()

    arquivo.close()
    print("Arquivo lido com sucesso.")
except IOError as excecao:
    print("Erro ao tentar ler arquivo de texto.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar ler arquivo de texto.", file=sys.stderr)
    print(excecao)

local EXIT_FAILURE = 1

local caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
local arquivo = io.open(caminho_arquivo, "r")
if (arquivo == nil) then
    print(debug.traceback())

    error("Erro ao tentar ler arquivo de texto.")
    os.exit(EXIT_FAILURE)
end

local linha_texto = arquivo:read("*line")
while (linha_texto) do
    print(linha_texto)
    linha_texto = arquivo:read("*line")
end

io.close(arquivo)

print("Arquivo lido com sucesso.")

-- Alternativa:
for linha_texto in io.lines(caminho_arquivo) do
    print(linha_texto)
end

extends Node

const EXIT_FAILURE = 1

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.READ) != OK):
        printerr("Erro ao tentar ler arquivo de texto.")
        get_tree().quit(EXIT_FAILURE)

    var linha_texto = arquivo.get_line()
    while (linha_texto):
        print(linha_texto)
        linha_texto = arquivo.get_line()

    print("Arquivo lido com sucesso.")

Python fornece o método readline() (documentação) para a leitura da próxima linha. Lua permite usar io.read() ou file:read() como o parâmetro "*line" como se fosse a entrada padrão; a linguagem também fornece io.lines() (documentação) para um iterador sobre as linhas. GDScript fornece get_line() (documentação) para a leitura da próxima linha.

Em todos os casos, pode-se usar o valor lido como condição para a estrutura de repetição enquanto. Enquanto o valor for uma cadeia de caracteres válida ou não nula, a repetição continuará.

Caso se deseje contar o número de linhas no arquivo, pode-se instanciar uma variável do tipo inteiro como contador e incrementar o valor a cada nova linha lida com sucesso.

Leitura de Arquivo Texto com Extração de Dados

Quando se conhece o conteúdo de um arquivo de texto ou ele possua um formato bem definido e regular, pode-se extrair dados armazenados para processamento mais granular. Para isso, pode-se converter os dados de cadeias de caracteres para tipos mais adequados, como números inteiros, números reais ou valores lógicos. Assim, é possível, por exemplo, efetuar operações aritméticas, relacionais e lógicas usando os valores extraídos.

Por exemplo, o arquivo criado nas seções anteriores contém duas linhas de texto, seguidas de uma linha três números inteiros, seguida de um linha um com um número real, seguida de uma linha vazia e do final do arquivo. Como o formato do arquivo é conhecido, pode-se ler o arquivo todo (ou cada linha) e extrair os valores.

Existem duas abordagens principais para a leitura de um arquivo para extração.

1. Pode-se ler o arquivo todo de uma vez e separá-lo (split) em um vetor usando delimitadores. Em seguida, processa-se cada valor do vetor.
2. Pode-se imaginar o arquivo de texto como se ele representasse todas as entradas fornecidas por uma usuária ou um usuário final durante o uso de um programa. Nesse caso, pode-se interpretar o arquivo como se ele fosse a origem de valores para comandos de leitura como input(), io.read() ou prompt().

Em algumas linguagens de programação (por exemplo, JavaScript em navegadores), o primeiro caso será imposto, pois o arquivo será lido por inteiro. Em outras linguagens, pode-se escolher a abordagem mais simples para se resolver o problema.

// Este código deve ser salvo em um arquivo chamado "script.js".
// Ele será processado por uma página HTML com código para envio do arquivo
// texto via formulário.

// <https://www.francogarcia.com/pt-br/blog/ambientes-de-desenvolvimento-javascript/>
function adicione_elemento(valor, nome_elemento = "p") {
    const pai = document.getElementById("conteudo")
    const novo_elemento = document.createElement(nome_elemento)
    novo_elemento.innerHTML = valor
    pai.appendChild(novo_elemento)
}

function leia_arquivo(arquivo_texto) {
    if (!arquivo_texto) {
        return
    } else if (!(arquivo_texto instanceof File)) {
        return
    }

    let leitor_arquivos = new FileReader()
    leitor_arquivos.onload = function(evento) {
        // Abordagem 1: leitura do arquivo todo e uso de split.
        console.log("Abordagem 1")
        let conteudo = evento.target.result

        let linhas = conteudo.split("\n")
        console.log(linhas)

        let primeira_frase = linhas[0]
        let segunda_frase = linhas[1]
        let numeros_inteiros = []
        let soma_numeros_inteiros = 0
        for (let texto_numero of linhas[2].split(" ")) {
            let numero = parseInt(texto_numero)
            numeros_inteiros.push(numero)
            soma_numeros_inteiros += numero
        }

        let numero_real = parseFloat(linhas[3])

        console.log(primeira_frase)
        console.log(segunda_frase)
        console.log(numeros_inteiros, soma_numeros_inteiros)
        console.log(numero_real, "Número positivo?", numero_real > 0)

        adicione_elemento(primeira_frase)
        adicione_elemento(segunda_frase)
        adicione_elemento("[" + numeros_inteiros + "] " + soma_numeros_inteiros)
        adicione_elemento(numero_real + " " +  "Número positivo?" + " " + (numero_real > 0))
    }
    leitor_arquivos.readAsText(arquivo_texto)

    // Impede a submissão do formulário, permitindo a visualização do
    // resultado de adicione_elemento() na mesma página.
    return false
}

import io
import sys

try:
    caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    arquivo = open(caminho_arquivo, "r")

    # Abordagem 1: leitura do arquivo todo e uso de split.
    print("Abordagem 1")
    conteudo = arquivo.read()

    linhas = conteudo.split("\n")
    print(linhas)

    primeira_frase = linhas[0]
    segunda_frase = linhas[1]
    numeros_inteiros = []
    soma_numeros_inteiros = 0
    for texto_numero in linhas[2].split():
        numero = int(texto_numero)
        numeros_inteiros.append(numero)
        soma_numeros_inteiros += numero

    numero_real = float(linhas[3])

    print(primeira_frase)
    print(segunda_frase)
    print(numeros_inteiros, soma_numeros_inteiros)
    print(numero_real, "Número positivo?", numero_real > 0)

    # Abordagem 2: leitura do arquivo como se fosse a entrada de um usuário.
    print("\nAbordagem 2")
    arquivo.seek(0) # ou arquivo.seek(0, 0) ou arquivo.seek(0, io.SEEK_SET)

    primeira_frase = arquivo.readline().rstrip()
    segunda_frase = arquivo.readline().rstrip()
    numeros_inteiros = []
    soma_numeros_inteiros = 0
    for texto_numero in arquivo.readline().split():
        numero = int(texto_numero)
        numeros_inteiros.append(numero)
        soma_numeros_inteiros += numero

    numero_real = float(arquivo.readline())

    print(primeira_frase)
    print(segunda_frase)
    print(numeros_inteiros, soma_numeros_inteiros)
    print(numero_real, "Número positivo?", numero_real > 0)

    arquivo.close()

except IOError as excecao:
    print("Erro ao tentar ler arquivo de texto.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar ler arquivo de texto.", file=sys.stderr)
    print(excecao)

function escreva_indentacao(nivel)
    for indentacao = 1, nivel do
        io.write("  ")
    end
end

function escreva_tabela(tabela, nivel)
    nivel = nivel or 1
    if (type(tabela) == "table") then
        io.write("{\n")
        for chave, valor in pairs(tabela) do
            escreva_indentacao(nivel)
            io.write(tostring(chave) .. ": ")
            escreva_tabela(valor, nivel + 1)
            io.write("\n")
        end
        escreva_indentacao(nivel - 1)
        io.write("},")
    else
        local aspas = ""
        if (type(tabela) == "string") then
            aspas = "\""
        end
        io.write(aspas .. tostring(tabela) .. aspas .. ",")
    end
end

function split(cadeia_caracteres, delimitador)
    delimitador = delimitador or " "
    local resultado = {}
    local tamanho = #cadeia_caracteres
    local inicio = 1
    while (inicio <= tamanho) do
        local fim, proximo = string.find(cadeia_caracteres, delimitador, inicio, true)
        if (fim ~= nil) then
            table.insert(resultado, string.sub(cadeia_caracteres, inicio, fim - 1))
            inicio = proximo + 1
        else
            table.insert(resultado, string.sub(cadeia_caracteres, inicio))
            inicio = tamanho + 1
        end
    end

    if (string.sub(cadeia_caracteres, -#delimitador) == delimitador) then
        table.insert(resultado, "")
    end

    return resultado
end

-- O programa começa aqui.
local EXIT_FAILURE = 1
local caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
local arquivo = io.open(caminho_arquivo, "r")
if (arquivo == nil) then
    print(debug.traceback())

    error("Erro ao tentar ler arquivo de texto.")
    os.exit(EXIT_FAILURE)
end

-- Abordagem 1: leitura do arquivo todo e uso de split.
print("Abordagem 1")
local conteudo = arquivo:read("*all")

local linhas = split(conteudo, "\n")
escreva_tabela(linhas)
print()

local primeira_frase = linhas[1]
local segunda_frase = linhas[2]
local numeros_inteiros = {}
local soma_numeros_inteiros = 0
for _, texto_numero in ipairs(split(linhas[3], " ")) do
    local numero = tonumber(texto_numero)
    table.insert(numeros_inteiros, numero)
    soma_numeros_inteiros = soma_numeros_inteiros + numero
end

local numero_real = tonumber(linhas[4])

print(primeira_frase)
print(segunda_frase)
escreva_tabela(numeros_inteiros)
print(" " .. soma_numeros_inteiros)
print(numero_real, "Número positivo?", numero_real > 0)

-- Abordagem 2: leitura do arquivo como se fosse a entrada de um usuário.
print("\nAbordagem 2")
arquivo:seek("set")

primeira_frase = arquivo:read("*line")
segunda_frase = arquivo:read("*line")
numeros_inteiros = {}
soma_numeros_inteiros = 0
for indice_numero = 1, 3 do
    local numero = arquivo:read("*number")
    table.insert(numeros_inteiros, numero)
    soma_numeros_inteiros = soma_numeros_inteiros + numero
end

numero_real = tonumber(arquivo:read("*number"))

print(primeira_frase)
print(segunda_frase)
escreva_tabela(numeros_inteiros)
print(" " .. soma_numeros_inteiros)
print(numero_real, "Número positivo?", numero_real > 0)

io.close(arquivo)

extends Node

const EXIT_FAILURE = 1

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_texto_escrita.txt"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.READ) != OK):
        printerr("Erro ao tentar ler arquivo de texto.")
        get_tree().quit(EXIT_FAILURE)

    # Abordagem 1: leitura do arquivo todo e uso de split.
    print("Abordagem 1")
    var conteudo = arquivo.get_as_text()

    var linhas = conteudo.split("\n")
    print(linhas)

    var primeira_frase = linhas[0]
    var segunda_frase = linhas[1]
    var numeros_inteiros = []
    var soma_numeros_inteiros = 0
    for texto_numero in linhas[2].split(" "):
        var numero = int(texto_numero)
        numeros_inteiros.append(numero)
        soma_numeros_inteiros += numero

    var numero_real = float(linhas[3])

    print(primeira_frase)
    print(segunda_frase)
    printt(numeros_inteiros, soma_numeros_inteiros)
    printt(numero_real, "Número positivo?", numero_real > 0)

    # Abordagem 2: leitura do arquivo como se fosse a entrada de um usuário.
    print("\nAbordagem 2")
    arquivo.seek(0)

    primeira_frase = arquivo.get_line()
    segunda_frase = arquivo.get_line()
    numeros_inteiros = []
    soma_numeros_inteiros = 0
    for texto_numero in arquivo.get_line().split(" "):
        var numero = int(texto_numero)
        numeros_inteiros.append(numero)
        soma_numeros_inteiros += numero

    numero_real = float(arquivo.get_line())

    print(primeira_frase)
    print(segunda_frase)
    printt(numeros_inteiros, soma_numeros_inteiros)
    printt(numero_real, "Número positivo?", numero_real > 0)

    arquivo.close()

O exemplo em JavaScript requer a mesma página HTML usada anteriormente para a submissão de um arquivo texto para processamento. Para o uso em navegadores, apenas a primeira abordagem é possível, já que o arquivo será lido por inteiro. Na primeira abordagem, divide-se o conteúdo inteiro em um vetor de linhas. Em seguida, processa-se cada linha de acordo com o(s) tipo(s) de dado(s) armazenado(s), para a extração de valores. Para exemplificar operações com os valores convertidos, os números inteiros foram somados, e o número real foi comparado.

Em Python, Lua e GDScript, ambas as abordagens são possíveis. O exemplo em Lua é um pouco mais longo porque usa subrotinas definidas anteriormente para escrita e processamento de valores. A primeira abordagem funciona da mesma que em JavaScript, então ela não será comentada novamente. Para a segunda abordagem, em cada uma das linguagens:

1. Utiliza-se seek() para alterar a posição no arquivo. Subrotinas como seek() permitem alterar posições de leitura e/ou escrita no arquivo, para acessos ou modificações de valores em posições arbitrárias. Em arquivos texto, é comum usar a operação para retornar ao início do arquivo (posição set) ou para avançar para o final (posição end). Também é possível avançar ou voltar de acordo com a posição atual (posição cur ou current), embora tais deslocamentos nem sempre sejam possíveis com arquivos de texto.

   Os valores usados para cada linguagem de programação para operações de skip tendem a variar. Assim, é importante consultar a documentação. Para Python: documentação; para Lua: documentação; para GDScript: documentação.

   No caso do exemplo, retornar-se ao início do arquivo (seek set), com deslocamento zero. Na prática, isso permite evitar fechar o arquivo e abri-lo novamente para lê-lo desde o início novamente.

2. Em seguida, processa-se cada linha de acordo com o seu valor. As linhas são lidas individualmente. Em Python, como readline() mantém a quebra de linha ao final, usa-se rstrip() (documentação) para removê-la.

   Em Lua, é possível ler os valores da mesma forma que a entrada padrão (stdin).

A extração de dados de arquivos texto permite manipulações mais sofisticadas do conteúdo. Contudo, isso nem sempre é possível ou simples extrair dados corretamente de qualquer arquivo texto. Por exemplo, caso o conteúdo do arquivo usado no exemplo mudasse, seria necessário reescrever o código para a extração de dados. Assim, uma solução melhor precisa ser genérica o suficiente para acomodar cenários de modificações. Para isso, estruturação é necessária, para se definir um padrão para os dados armazenados.

Arquivos de Texto Estruturados

Uma forma de facilitar significativamente a extração de dados consiste na adoção de formatos de arquivos de texto estruturado. As próximas subseções apresentam alguns formatos e linguagens de marcação (markup languages) populares para armazenamento e troca de dados. A sigla de cada formato é comumente usada como extensão para arquivos de texto armazenando dados no formato.

Embora alguns formatos possam ser facilmente processados com manipulação de cadeias de caracteres, o ideal é usar (ou criar) uma biblioteca de qualidade para uso profissional de qualquer um dos formatos.

Além disso, existem ferramentas para conversão e apoio de uso de arquivos de texto estruturados. Dois exemplos interessantes são Data-Selector (Dasel) e uma lista de ferramentas disponível neste repositório.

Comma Separated Values (CSV)

Um formato popular usado em programas matemáticos e de planilhas de cálculos chama-se Comma Separated Values (CSV). O nome do formato é a sua própria especificação: valores são separados por vírgulas.

Olá,meu,nome,é,Franco,Tudo bem?
1,2,3,4,5,6
1.1,2.2,3.3,4.4,5.5,6.6

Caso um valor precise ser armazenado com uma vírgula, ele pode ser especificado entre aspas duplas. Contudo, a convenção pode variar de acordo com a implementação.

Para a especificação oficial do formato, pode-se consultar a Request for Comment (RFC) 4180.

Tab Separated Values (TSV)

Uma variação do formato CSV consiste no uso tabulações (tabs) ao invés de vírgulas para separar valores. Em cadeias de caracteres de linguagens de programação, tabulações são comumente representadas por \t. O formato resultante chama-se Tab Separated Values (TSV), ou seja, valores separados por tabulações.

Olá	meu	nome	é	Franco	Tudo bem?
1	2	3	4	5	6
1.1	2.2	3.3	4.4	5.5	6.6

Quando se usa TSV, é importante configurar o editor de texto para inserção de tabulações. Editores de texto para programação podem ser configurados para trocar uma tabulação por uma certa quantidade de espaços. Para o formato TSV, é importante que as tabulações sejam, de fato, caracteres de tabulações reais.

A especificação do formato é simples; ela pode ser encontrada nesta página da Internet Assigned Numbers Authority (IANA).

Extensible Markup Language (XML)

Extensible Markup Language (XML) é um dos formatos pioneiros para troca de dados. A especificação do formato está disponível na página oficial do formato.

O formato XML é parecido com HTML, embora uma programadora ou um programador possa escolher os nomes para as tags. O único requisito é a correspondência entre a tag que inicia um valor com a que termina. Uma tag pode ser definida como <NomeTag atributo="valor">Valor armazenado</NomeTag>. Caso ela não possua valor entre o início e o fim, pode-se escrevê-la como <NomeTag atributo="valor"></NomeTag>, ou, simplesmente, <NomeTag atributo="valor"/>.

<?xml version="1.0" encoding="UTF-8"?>
<!-- Este é um comentário. -->
<Valores>
  <Textos>
    <Texto>Olá</Texto>
    <Texto>meu</Texto>
    <Texto>nome</Texto>
    <Texto>é</Texto>
    <Texto>Franco</Texto>
    <Texto>Tudo bem?</Texto>
  </Textos>
  <NumerosInteiros>
    <NumeroInteiro>1</NumeroInteiro>
    <NumeroInteiro>2</NumeroInteiro>
    <NumeroInteiro>3</NumeroInteiro>
    <NumeroInteiro>4</NumeroInteiro>
    <NumeroInteiro>5</NumeroInteiro>
    <NumeroInteiro>6</NumeroInteiro>
  <NumerosInteiros>
  <NumerosReais>
    <NumeroReal valor="1.1"/>
    <NumeroReal valor="2.2"/>
    <NumeroReal valor="3.3"/>
    <NumeroReal valor="4.4"/>
    <NumeroReal valor="5.5"/>
    <NumeroReal valor="6.6"/>
  <NumerosReais>
</Valores>

Valores podem ser armazenados entre tags ou como atributos de uma tag. Por exemplo, poder-se-ia alterar Texto para <Texto texto="Franco"/>. Da mesma forma, poder-se-ia escrever <NumeroReal>1.1</NumeroReal>.

O formato XML é versátil, embora seja verboso (isto é, longo para escrever). Para maior facilidade de escrita e desempenho, formatos mais recentes são mais concisos e fáceis de processar que XML. Por outro lado, XML fornece recursos adicionais como esquemas e namespaces que são raros em outros formatos. Programadoras e programadores podem definir esquemas como forma de validação de arquivos seguindo o esquema proposto. Eles são úteis para garantir a validade de um arquivo com dados para um determinado domínio ou problema.

JavaScript Object Notation (JSON)

Atualmente, JavaScript Object Notation (JSON) é um dos formatos mais populares para arquivos de texto estruturados. O formato pode ser usado facilmente com a linguagem JavaScript. Como o nome sugere, o formato é similar a JavaScript Objects.

{
  "Textos": ["Olá", "meu", "nome", "é", "Franco", "Tudo bem?"],
  "Numeros Inteiros": [1, 2, 3, 4, 5, 6],
  "Numeros Reais": [1.1, 2.2, 3.3, 4.4, 5.5, 6.6]
}

Em outras palavras, você já sabe usá-los. JSON pode ter vetores, dicionários e tipos de dados primitivos como valores. Valores inteiros ou reais são escritos sem aspas (simples ou duplas). Cadeias de caracteres ou valores lógicos requerem o uso de aspas. Algo que se deve observar é que JSON não admite o uso de comentários.

A especificação do formato está disponível na página oficial. Linguagens de programação modernas costumam oferecer implementações para uso de JSON na biblioteca padrão. Caso contrário, é bastante provável que exista uma biblioteca para uso do formato na linguagem de programação escolhida.

Além disso, existem ferramentas para edição de arquivos JSON como DEPOT. A interface de tais ferramentas são mais próximas de programas de planilhas de cálculo.

Para operação de aquivos usando linha de comando JSON, o programa jq é bastante conveniente para buscas e extração de valores.

YAML Ain't Markup Language (YAML)

JSON é um bom formato para programação, porém bastante próximo da estrutura de linguagens de programação. Existem formatos que tentam ser mais acessíveis a usuários finais. Um deles chama-se YAML Ain't Markup Language (YAML), cuja especificação está disponível na página oficial. O conteúdo da página oficial, inclusive, é um exemplo de arquivo no formato.

%YAML 1.2
---
Textos:
  - Olá
  - meu
  - nome
  - é
  - Franco
  - Tudo bem?
Numeros Inteiros:
  - 1
  - 2
  - 3
  - 4
  - 5
  - 6
Numeros Reais:
  - 1.1
  - 2.2
  - 3.3
  - 4.4
  - 5.5
  - 6.6

O formato YAML assemelha-se a uma lista estruturada feita em um editor de textos.

Tom's Obvious Minimal Language (TOML)

Tom's Obvious Minimal Language (TOML) é outro formato para arquivos texto estruturados. O formato assemelha-se a arquivos de configuração usados no Windows. A especificação está disponível na página oficial do projeto.

Textos = ["Olá", "meu", "nome", "é", "Franco", "Tudo bem?"]
NumerosInteiros = [1, 2, 3, 4, 5, 6]
NumerosReais = [1.1, 2.2, 3.3, 4.4, 5.5, 6.6]

Em particular, Godot Engine usa um formato parecido com TOML para armazenamento das cenas em formato de texto criadas pelo editor.

Arquivos Binários (Binary Files)

Além de arquivos texto, é possível armazenar dados em arquivos como despejos (dumps) diretos de memória. Em outras palavras, ao invés de codificar o conteúdo como texto, salva-se em memória secundária os bytes armazenados em memória primária. Arquivos assim são chamados de arquivos binários (mesmo que, tecnicamente, arquivos textos também sejam arquivos binários codificados).

Ao contrário de arquivos texto, arquivos binários não possuem o objetivo de serem legíveis por seres humanos. Não há marcações de onde um dado começa ou termina; dados são, simplesmente, seqüências de bits armazenados na memória. Assim, para determinar o conteúdo de um arquivo binário com exatidão, deve-se conhecer a ordem e os tipos de dados armazenados em seqüência. Caso essas informações não sejam conhecidas, a identificação de valores em um arquivo binário requer esforços de engenharia reversa para determinação do que está armazenado.

Pode-se pensar em um arquivo binário como um grande vetor de dados. Entretanto, ao invés de posições pré-definidas, cada dado ocupa um certo número de bits ou bytes. A leitura de um certo número de bytes a partir de uma posição inicial até uma posição final permite extrair o valor de um dado. Da mesma forma, a escrita do valor do tipo lido nas mesmas posições permite armazenar um valor. Assim, arquivos binários permitem leitura e escrita com acesso aleatório; sabendo-se o "endereço" do valor no arquivo, é possível acessá-lo e/ou modificá-lo. Ou seja, o deslocamento (offset) a partir de uma posição conhecida (como início, fim ou a posição atual) permite escrever ou extrair dados em posições arbitrárias do arquivo. Para fazer o deslocamento, basta usar uma operação de seek. Isso facilita a extração de dados de arquivos binários.

De fato, a combinação de arquivos binários com registros (no sentido de Plain Old Data ou POD) pode tornar trivial o armazenamento e recuperação de dados em algumas linguagens de programação. Contudo, isso tende a ser mais fácil de fazer em linguagens de programação nível mais baixo (como C e C++) que em linguagens de programação de nível mais alto (como JavaScript, Python e Lua). A razão é que, em linguagens de baixo nível, os tipos de dados tendem a possuir tamanhos fixos em bytes, o que facilita a obtenção do tamanho de um registro POD.

Editor Hexadecimal (Hexadecimal Editor ou Hex Editor)

Arquivos texto podem ser lidos e modificados usando editores de texto. Arquivos binários podem ser lidos e modificados usando editores hexadecimais.

Ao contrário de editores de texto que (mesmo que simples) costumam ser fornecidos por padrão em quaisquer sistemas operacionais, normalmente é necessário instalar um editor hexadecimal. Alguns ambientes gráficos incluem editores hexadecimais entre o programas instalados por padrão. Por exemplo, o KDE fornece o editor Okteta. Okteta pode ser usado e instalado em sistemas operacionais Windows e Linux.

Uma alternativa de código aberto que pode ser usada em Windows, Linux e macOS chama-se ImHex. Existem também ferramentas que podem ser usadas online, como HexEd.it (gratuito, mas não é de código aberto).

Por fim, alguns editores de texto incluem modos de editor hexadecimal. Por exemplo, GNU Emacs fornece hexl-mode para visualização e edição de arquivos binários.

Neste tópico, o editor ImHex será usado para inspeções de arquivos binários. Ele será escolhido por permitir definir valores baseados em deslocamentos ("endereços de memória") e realçá-los com diferentes cores. A sintaxe utilizada para definição dos dados está disponível na documentação do programa.

Operações Básicas Usando Arquivos Binários

Operações usando arquivos binários são semelhantes às feitas para arquivos texto, embora o arquivo resultante seja mais difícil de visualizar que um arquivo texto. Por isso a sugestão de uso de um editor hexadecimal.

Assim como arquivos textos, todo o uso de um arquivo binário inicia-se pela abertura (ou criação) de um arquivo, e termina com o fechamento dele. A principal diferença são as operações de leitura e escrita. Ao invés de caracteres ou linhas (qualquer tipo de texto codificado), as operações trabalham com blocos de memória cujo tamanho é definido em bytes.

Escrita de Arquivo Binário

As implementações em Python, Lua e GDScript são mais simples que a implementação em JavaScript. A versão em JavaScript requer a montagem dos bytes para se salvar no arquivo. Python, Lua e GDScript fornecem subrotinas para conversão automática, simplificando o processo. A versão em GDScript é a mais simples de ler, pois a linguagem fornece métodos específicos para cada tipo de dado. Assim, pode-se se interessante ler primeiro o código em GDScript, depois o código em Python ou Lua, e, por último, o código em JavaScript. Como as quatro implementações são equivalentes, isso pode facilitar o entendimento dos programas.

A implementação em Lua requer versão 5.3 ou mais recente para uso de string.pack(). Para as versões 5.1 e 5.2 da linguagem, pode-se usar uma extensão criada pelo autor de Lua para se obter struct.pack() e struct.unpack(), que funcionam como string.pack() e string.unpack(). É possível alterar a versão do interpretador Lua usada pelo ZeroBrane Studio em Projeto (Project), depois Interpretador de Lua (Lua Interpreter), depois Lua 5.3.

Os arquivos nos exemplos possuem a extensão .bin, escolhida por ser comum para arquivos binários. Contudo, pode-se escolher qualquer extensão. Uma extensão não modifica o conteúdo de um arquivo, ou seja, ela não define o que um arquivo é. A extensão serve como dica (heurística) para que o sistema operacional escolha um programa apropriado para abrir o arquivo. Para visualizar o conteúdo do arquivo gerado em um editor de textos, pode-se escolher a extensão .txt (algo interessante de fazer). Para se criar uma extensão própria, pode-se adotar a extensão .dados ou .franco.

let caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
let conteudo = []

let linha_texto = "Olá, meu nome é Franco.\n"
let text_encoder = new TextEncoder()
let texto_codificado = text_encoder.encode(linha_texto)
let tamanho_texto_codificado = texto_codificado.length

for (let repeticoes = 0; repeticoes < 2; ++repeticoes) {
    let tamanho = new Int32Array(1)
    tamanho[0] = tamanho_texto_codificado
    let bytes_tamanho = new Uint8Array(tamanho.buffer)
    for (let byte_tamanho of bytes_tamanho) {
        conteudo.push(byte_tamanho)
    }

    for (let byte_texto of texto_codificado) {
        conteudo.push(byte_texto)
    }
}

let numeros_inteiros = new Int32Array(3)
numeros_inteiros[0] = 1
numeros_inteiros[1] = 2
numeros_inteiros[2] = 3
let bytes_numeros_inteiros = new Uint8Array(numeros_inteiros.buffer)
for (let byte_numeros of bytes_numeros_inteiros) {
    conteudo.push(byte_numeros)
}

let numero_real = new Float32Array(1)
numero_real[0] = -1.23
let bytes_numero_real = new Uint8Array(numero_real.buffer)
for (let byte_numero of bytes_numero_real) {
    conteudo.push(byte_numero)
}

let bytes = new Uint8Array(conteudo)
let dados = new Blob([bytes], {type: "application/octet-stream"})
let arquivo = new File([dados], caminho_arquivo, {type: dados.type})
console.log("Arquivo criado com sucesso.")

let link_download = document.createElement("a")
link_download.target = "_blank"
link_download.href = URL.createObjectURL(arquivo)
link_download.download = arquivo.name
if (confirm("Fazer download do arquivo '" + arquivo.name + "'?")) {
    link_download.click()
    // Neste caso, revokeObjectURL() poderia ser usado tanto para confirmação,
    // quanto para cancelamento.
    URL.revokeObjectURL(link_download.href)
}

import io
import struct
import sys

try:
    caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
    arquivo = open(caminho_arquivo, "wb")

    linha_texto = "Olá, meu nome é Franco.\n"
    texto_codificado = bytearray(linha_texto.encode("utf-8"))
    tamanho_texto_codificado = len(texto_codificado)
    arquivo.write(struct.pack("i", tamanho_texto_codificado))
    arquivo.write(texto_codificado)

    arquivo.write(struct.pack("i", tamanho_texto_codificado))
    arquivo.write(texto_codificado)

    arquivo.write(struct.pack("i", 1))
    arquivo.write(struct.pack("i", 2))
    arquivo.write(struct.pack("i", 3))

    arquivo.write(struct.pack("f", -1.23))

    arquivo.close()

    print("Arquivo criado com sucesso.")
except IOError as excecao:
    print("Erro ao tentar criar arquivo binário.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar criar arquivo binário.", file=sys.stderr)
    print(excecao)

local EXIT_FAILURE = 1

local caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
local arquivo = io.open(caminho_arquivo, "wb")
if (arquivo == nil) then
    print(debug.traceback())

    error("Erro ao tentar criar arquivo binário.")
    os.exit(EXIT_FAILURE)
end

local linha_texto = "Olá, meu nome é Franco.\n"
arquivo:write(string.pack("s", linha_texto))
arquivo:write(string.pack("s", linha_texto))

arquivo:write(string.pack("i", 1))
arquivo:write(string.pack("i", 2))
arquivo:write(string.pack("i", 3))

arquivo:write(string.pack("f", -1.23))

io.close(arquivo)

print("Arquivo criado com sucesso.")

extends Node

const EXIT_FAILURE = 1

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.WRITE) != OK):
        printerr("Erro ao tentar criar arquivo binário.")
        get_tree().quit(EXIT_FAILURE)

    arquivo.store_pascal_string("Olá, meu nome é Franco.\n")
    arquivo.store_pascal_string("Olá, meu nome é Franco.\n")

    arquivo.store_32(1)
    arquivo.store_32(2)
    arquivo.store_32(3)

    arquivo.store_float(-1.23)

    arquivo.close()

    print("Arquivo criado com sucesso.")

Em cada um dos programas, escreveu-se o tamanho da cadeia de caracteres antes da frase. Isso permitirá ler o número correto de bytes para extrair os dados nos programas de leitura. Em linguagens de programação compiladas, como C e C++, pode-se sofisticar esta técnica e incluir o tamanho como primeira posição de um vetor. A técnica chama-se Pascal string, pois foi popularizada em implementações da linguagem de programação Pascal.

Para a implementação do exemplo, a abertura e fechamento de arquivos ocorre de forma similar a arquivos texto. Em Python e Lua, usa-se "b" na abertura ("wb") para a criação de um arquivo binário em modo de escrita. Em JavaScript, muda-se o tipo MIME para "application/octet-stream" (todavia, o formato será devido pelo processo de criação) Em GDScript, cria-se o arquivo normalmente.

A escrita varia de linguagem para linguagem. A mais simples dentre as adotadas para exemplos é GDScript, que fornece métodos específicos para cada tipo de dado. O método store_pascal_string() (documentação) permite escrever uma cadeia de caracteres precedida pelo valor inteiro com seu tamanho; store_32() (documentação) permite escrever números inteiros com 4 bytes (32 bits); store_float() (documentação) permite escrever números reais em ponto flutuante com 4 bytes (32 bits).

Python e Lua funcionam de forma similar, com uma subrotina para gerar seqüências de bytes (vetores de bytes) para cada tipo. O princípio é criar tipos compatíveis com struct (registros) em C.

Python provê o módulo struct (documentação); o método pack() (documentação) permite criar as seqüências binárias. Cada parâmetro corresponde a um tipo de dado; "i" é para inteiros de 4 bytes; "f" é para ponto flutuante de 4 bytes. Para cadeias de caracteres, é preciso codificá-las (por exemplo, em UTF-8) com encode() (documentação) e gerar um bytearray (documentação).

Em Lua, a versão 5.3 introduziu string.pack() (documentação) para o mesmo propósito. O parâmetro "s" escreve o tamanho e a cadeia de caracteres; "i" escreve um número inteiro de tamanho padrão; "f" escreve um número em ponto flutuante de tamanho padrão. Na máquina do autor, o tamanho padrão foi 4 bytes para ambos os casos.

JavaScript é a linguagem que demanda maior esforço, porque não há subrotina para conversão direta de tipos. Em JavaScript, deve-se criar um vetor com tamanho fixo de valores desejados, depois converter o vetor para um vetor de bytes (Uint8), depois inserir cada valor em um vetor para se escrever no arquivo. Assumindo-se valores de 4 bytes (32 bits):

• Para números inteiros com sinal, primeiro cria-se um vetor Int32Array (documentação), armazena-se os valores desejados, depois cria-se um vetor Uint8Array (documentação).
• Para números reais, primeiro cria-se um vetor Float32Array (documentação), armazena-se os valores desejados, depois cria-se um vetor Uint8Array;
• Para cadeias de caracteres, primeiro cria-se um codificador de texto TextEncoder (documentação), armazena-se os valores desejados, depois cria-se um vetor Uint8Array. Como nos outros casos, também é interessante armazenar o tamanho da cadeia de caracteres antes dos bytes do texto.

Para facilitar o uso em JavaScript, poderia ser interessante criar funções para a conversão. Isso será feito posteriormente em alguns exemplos, como para a criação de um arquivo de som (funções prefixadas com pack_) e para montagem de valores lidos de arquivos (funções prefixadas com unpack_). As funções não foram criadas para este primeiro exemplo para demonstrar que é possível criar um vetor maior e convertê-lo de uma única vez.

Além disso, JavaScript utiliza um Blob (documentação) para armazenar os bytes antes de salvá-los. O termo blob é usado em programação para se referir a dados binários, sem uma interpretação de tipo. No caso, trata-se de todos os bytes que se deseja salvar.

Usar tipos com uma quantidade fixa de bytes pode economizar memória para salvar arquivos. Por exemplo, os valores 0, 1, 0000001, -123, 123456, 2147483647 e -2147483648 ocupam 4 bytes de memória como números inteiros de 32 bits. Em texto, qualquer valor com 5 ou mais dígitos (incluindo sinal, pontos, vírgulas, ou zeros à esquerda) requereria, no mínimo, o mesmo número de bytes para cada caractere utilizado. Por exemplo, -2147483648 possui 11 caracteres, o que requereria 11 bytes para codificação em ASCII ou UTF-8. O mesmo vale para números em ponto flutuante.

Uma segunda vantagem é a maior facilidade para extração de valores. Como se conhece todos os tamanhos, pode-se determinar onde cada um deles começa e termina. Para carregar o arquivo criado, basta seguir a mesma ordem da criação, mas lendo dados ao invés de escrevê-los. Salvar o tamanho de cadeias de caracteres permite ler a quantidade exata de caracteres armazenados para cada texto salvo.

Ordem de Bytes e Endianness

Diferentemente de arquivos texto, os arquivos binários gerados para cada exemplo anterior podem ser diferentes. Isso ocorre porque eles dependem, por exemplo, do número de bytes escolhido (ou adotado pela linguagem) para representar cada tipo de dados. Além disso, arquivos binários (e a memória de um computador propriamente dita) podem adotar uma entre duas ordens para bytes: little-endian (LE) e big-endian (BE). Na ordem big-endian, o byte mais significativo é armazenado no menor endereço de memória. Na ordem little-endian, o byte mais significativo é armazenado no maior endereço de memória. Isso significa que, na ordem little-endian, os bytes são armazenados invertidos em memória. O ordem little-endian é comum em arquiteturas para processadores de arquiteturas x86 e AMD64 (x64). A ordem big-endian é comum em operações de rede (network order).

A rigor, a ordem de bytes também pode afetar arquivos texto. Por exemplo, arquivos codificados em Unicode podem ter um valor inicial chamado Byte Order Mark (BOM), que pode ser usado para se determinar se o arquivo segue a ordem little-endian ou big-endian. Os valores para cada codificação Unicode (como UTF-8) podem ser encontrados neste artigo da Wikipedia. Dependendo do formato adotado, o BOM pode ser opcional, obrigatório ou proibido. Para codificação UTF-8, ele é opcional (por exemplo, os exemplos deste tópico não usam BOM). Para qualquer caso, caso existente, os valores do BOM não devem ser exibidos pelo editor de texto (ou programa processando o arquivo); eles apenas são úteis para a decodificação dos demais bytes do arquivo.

Para ilustrar a diferença de ordem de bytes, pode-se considerar a tabela a seguir, extraída das perguntas gerais relacionadas a UTF ou Forma de Codificação. O cabeçalho foi traduzido.

Um byte possui 8 bits. Dois dígitos hexadecimais podem representar 256 valores, ou seja, de 00 (0 como decimal) até FF (255 como decimal). Em outras palavras, dois dígitos hexadecimais correspondem a um byte. Como curiosidade, um único dígito hexadecimal corresponde a 4 bits (meio byte), chamado de um nibble (ou nybble ou nyble). Como informação útil, é fácil de converter um valor hexadecimal para binário. Para isso, basta escrever o valor de cada dígito hexadecimal em formato binário. Por exemplo, F corresponde a 1111; E corresponde a 1110. Assim, FE corresponde a 11111110. Da mesma forma, pode-se converter cada seqüência de nibbles em um valor hexadecimal. Por exemplo, 1011 em binário corresponde ao valor hexadecimal B.

Com as informações anteriores, pode-se analisar a tabela. Em particular, as entradas para UTF-32 e UTF-16 permitem observar as diferenças de ordem com maior facilidade. As linhas para UTF-32 representam um mesmo valor inteiro de 4 bytes: 00 00 FE FF (valor hexadecimal; como valor decimal: 65279). Na versão big-endian, o valor é armazenado na ordem em que é escrito. Na versão little-endian, os bytes aparecem em ordem invertida. A interpretação como número inteiro sem sinal resultaria no valor 4294836224. No caso de BOM, a leitura do valor permite identificar a ordem de bytes no arquivo (por exemplo, comparando-se o valor lido com cada um dos possíveis resultados). O mesmo vale para as entradas em UTF-16.

No caso de UTF-8, usa-se três bytes como três números de 1 byte cada um (como decimais: 239, 187, 191). Como UTF-8 codifica valores em seqüências de 1 byte, a ordem de bits não afeta o resultado. Afinal, não é possível inverter a ordem de bytes caso exista apenas um byte por valor. Por exemplo, FE (254 como decimal) é um único byte. FE invertido continua FE, pois não se inverte bits individuais, mas bytes inteiros. Assim, a utilidade de BOM em arquivos UTF-8 é sinalizar que se trata de um arquivo de texto codificado em UTF-8 (ao invés de outra codificação, como ISO-8859-1, que codifica o alfabeto latino). Em outras palavras, ele serve como uma garantia adicional para reconhecimento do arquivo.

Quando se programa, o interpretador ou compilador encarrega-se de armazenar valores em memória na ordem de bytes correta. Contudo, quando se cria arquivos binários, é preciso saber a ordem adotada caso se deseje compartilhar o arquivo criado em máquinas com diferentes arquiteturas. Caso contrário, a interpretação de valores lidos pode ser feita incorretamente, resultando em erros potencialmente inesperados.

Inspecionando-se o Arquivo Binário Criado

Embora seja possível abrir um arquivo binário (que não seja um arquivo de texto) em um editor de texto (na realidade, qualquer arquivo pode ser aberto em um editor de texto), o resultado será peculiar.

Por exemplo, pode-se abrir o arquivo franco-garcia-arquivo_binario_escrita.bin em um editor de texto. Alguns caracteres estarão corretos, outros serão estranhos. Isso ocorre porque o editor de texto tenta interpretar todos os dados como caracteres codificados, algo que não reflete realmente os dados dos arquivos. Por exemplo, a imagem a seguir ilustra o arquivo binário criado na implementação em Python, aberto no editor de texto GNU Emacs. A parte esquerda mostra o arquivo interpretado como texto. A parte direita da imagem ilustra o arquivo como exibido pelo modo hexadecimal hexl-mode. No modo hexadecimal, os números em linhas e colunas são deslocamentos para acesso à memória. Os valores exibidos são números hexadecimais representado os bytes armazenados, em ordem little-endian.

Na parte esquerda da imagem, apenas valores codificados usando valores válidos em ASCII são apresentados corretamente. Caracteres acentuados são trocados por valores de escape. Os números inteiros e o número real armazenados também. Na parte direita, com a visualização em hexadecimal, todos os valores para os bytes estão corretos. Novamente, valores em texto ASCII são apresentados corretamente na parte interpretada assim (extremo direito da imagem). Os demais valores requerem conhecer o tipo de dado armazenado. Por exemplo, na última linha, a seqüência 0200 0000 em little-endian corresponde a seqüência hexadecimal 0000 0002 em big-endian, ou seja, ao número inteiro 2.

Logo, para interpretar corretamente os dados armazenados, é preciso saber onde cada dado começa e termina, assim como o tipo de dado armazenado. Para isso, pode-se usar um editor hexadecimal. A próxima imagem inspeciona o conteúdo gerado pelo programa em Python usando o editor hexadecimal ImHex. O editor hexadecimal apresenta valores binários armazenados no arquivo como números hexadecimais (por isso o nome). Caso se prefira visualizá-los de outra forma (por exemplo, como os valores binários), pode-se configurar o editor para alterar a forma de exibição de valores.

Na imagem, cada um dos dados está realçado para facilitar a identificação. A correspondência de padrões é feita usando as opções Pattern Editor e Pattern Data no editor ImHex. Quando os valores estão corretos, os dados são interpretados corretamente. Os tipos de dados estão transcritos no bloco abaixo. O tipo s32 é um inteiro com sinal de 32 bits (4 bytes); char é um caractere de 1 byte; float é um número real de 32 bits (4 bytes).

s32 tamanho_frase1 @ 0x00;
char frase1[26] @ 0x04;
s32 tamanho_frase2 @ 0x1E;
char frase2[26] @ 0x22;
s32 inteiro1 @ 0x3C;
s32 inteiro2 @ 0x40;
s32 inteiro3 @ 0x44;
float real @0x48;

O valor após o símbolo de arroba (@) é o offset do dado considerando o início do arquivo. Isso significa, por exemplo, que tamanho_frase2 inicia-se no byte com endereço 1E₁₆ em base hexadecimal, ou seja, 30₁₀ em base decimal. Caso se comece a leitura no offset 1E e leia-se 4 bytes, o valor extraído será o valor armazenado para o tamanho da segunda frase.

A definição de tipos permite apresentar os valores esperados.

O tamanho usando em cada vetor é o tamanho da cadeia de caracteres considerando os acentos (pois o arquivo está codificado em UTF-8).

Para as implementações em JavaScript e GDScript, a definição de tipos feita para Python deve funcionar corretamente (embora possa ser preciso alterar a ordem de bytes em JavaScript). Para a implementação em Lua, pode ser necessário ajustar os formatos e endereços, pois string.pack("s") utiliza um inteiro sem sinal de 8 bytes em máquinas 64-bit para armazenar o tamanho da cadeia de caracteres. Isso corresponde ao tipo u64 em ImHex.

u64 tamanho_frase1 @ 0x00;
char frase1[26] @ 0x08;
u64 tamanho_frase2 @ 0x22;
char frase2[26] @ 0x2A;
s32 inteiro1 @ 0x44;
s32 inteiro2 @ 0x48;
s32 inteiro3 @ 0x4C;
float real @0x50;

Em máquinas 32-bit, a definição para as demais linguagens pode funcionar em Lua, já que o valor usado para o tamanho da cadeia de caracteres seria um inteiro de 4 bytes, como nos outros casos.

Leitura de Arquivo Binário

Existem duas formas principais de ler um arquivo binário:

1. Ler o arquivo todo como um bloco de memória, possivelmente abstraído como vetor de bytes;
2. Extrair dados do arquivo binário.

Também é possível ler o arquivo byte por byte, embora isso nem sempre seja útil. Um dos exemplos deste tópico demonstra a leitura byte a byte para copiar arquivos.

Leitura do Arquivo Binário Inteiro

Em algumas linguagens, é possível ler um arquivo binário inteiro de uma vez e extrair todos os dados como campos de um registro. Por exemplo, em C e C++, basta uma chamada de função para ler e carregar todos os dados salvos de um arquivo para um registro POD de uma única vez (assim como também é possível salvar todos os dados de um registro em uma única operação). Isso ocorre porque é possível manipular a memória como um bloco de bytes. Caso os dados sejam armazenados em endereços contíguos, é possível salvar e restaurar a memória como se fosse um único bloco (porque ela é, de certa forma). Desde que o layout de dados seja o mesmo, é possível salvar e restaurar múltiplas variáveis cujos endereços comecem em um mesmo endereço base.

Em JavaScript, Python, Lua e GDScript, isso não é tão imediato, pois as linguagens abstraem o uso da memória. Embora em JavaScript o arquivo todo seja lido de uma vez, o resultado é um vetor de bytes, não um bloco de memória que pode ser interpretado de acordo com a vontade da programadora ou do programador.

Leitura de Arquivo Binário com Extração de Dados

Embora não se possa carregar todos os dados de uma única vez, ainda é simples extrair cada um dos dados salvos. As implementações em Python, Lua e GDScript são mais simples que a em JavaScript. A implementação em JavaScript requer converter bytes armazenados em variáveis de tipos intermediários antes de carregá-las em memória. Ela também requer uma página HTML para o envio do arquivo em navegadores; o código é apresentado na seqüência.

A implementação em Lua assume uso da versão 5.3 ou mais recente, como comentado para a criação de arquivos binários.

// Este código deve ser salvo em um arquivo chamado "script.js".
// Ele será processado por uma página HTML com código para envio do arquivo
// texto via formulário.

// <https://www.francogarcia.com/pt-br/blog/ambientes-de-desenvolvimento-javascript/>
function adicione_elemento(valor, nome_elemento = "p") {
    const pai = document.getElementById("conteudo")
    const novo_elemento = document.createElement(nome_elemento)
    novo_elemento.innerHTML = valor
    pai.appendChild(novo_elemento)
}

function unpack_int32(bytes) {
    var array_buffer = new ArrayBuffer(4)
    var resultado = new DataView(array_buffer)
    for (let indice in bytes) {
        resultado.setUint8(indice, bytes[indice])
    }

    // true para little-endian, false para big-endian.
    return resultado.getInt32(0, true)
}

function unpack_float32(bytes) {
    var array_buffer = new ArrayBuffer(4)
    var resultado = new DataView(array_buffer)
    for (let indice in bytes) {
        resultado.setUint8(indice, bytes[indice])
    }

    // true para little-endian, false para big-endian.
    return resultado.getFloat32(0, true)
}

function leia_arquivo(arquivo_binario) {
    if (!arquivo_binario) {
        return
    } else if (!(arquivo_binario instanceof File)) {
        return
    }

    let leitor_arquivos = new FileReader()
    leitor_arquivos.onload = function(evento) {
        let bytes = new Uint8Array(evento.target.result)
        let indice = 0

        let text_decoder = new TextDecoder()

        let tamanho_primeira_frase = unpack_int32(new Uint8Array(bytes.slice(indice, 4)))
        indice += 4
        let primeira_frase = text_decoder.decode(bytes.slice(indice, indice + tamanho_primeira_frase))
        indice += tamanho_primeira_frase

        let tamanho_segunda_frase = unpack_int32(new Uint8Array(bytes.slice(indice, indice + 4)))
        indice += 4
        let segunda_frase = text_decoder.decode(bytes.slice(indice, indice + tamanho_segunda_frase))
        indice += tamanho_segunda_frase

        let numeros_inteiros = []
        let soma_numeros_inteiros = 0
        for (let i = 0; i < 3; ++i) {
            let numero = unpack_int32(new Uint8Array(bytes.slice(indice, indice + 4)))
            indice += 4
            numeros_inteiros.push(numero)
            soma_numeros_inteiros += numero
        }

        console.log(indice, bytes)
        let numero_real = unpack_float32(new Uint8Array(bytes.slice(indice, indice + 4)))
        indice += 4

        console.log(primeira_frase)
        console.log(segunda_frase)
        console.log(numeros_inteiros, soma_numeros_inteiros)
        console.log(numero_real, "Número positivo?", numero_real > 0)

        adicione_elemento(primeira_frase)
        adicione_elemento(segunda_frase)
        adicione_elemento("[" + numeros_inteiros + "] " + soma_numeros_inteiros)
        adicione_elemento(numero_real + " " +  "Número positivo?" + " " + (numero_real > 0))
    }
    leitor_arquivos.readAsArrayBuffer(arquivo_binario)

    // Impede a submissão do formulário, permitindo a visualização do
    // resultado de adicione_elemento() na mesma página.
    return false
}

import io
import struct
import sys

try:
    caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
    arquivo = open(caminho_arquivo, "rb")

    # A vírgula é importante, porque string.unpack() retorna uma tupla.
    tamanho_primeira_frase, = struct.unpack("i", arquivo.read(struct.calcsize("i")))
    texto_codificado = arquivo.read(tamanho_primeira_frase)
    primeira_frase = texto_codificado.decode("utf-8")

    tamanho_segunda_frase, = struct.unpack("i", arquivo.read(struct.calcsize("i")))
    texto_codificado = arquivo.read(tamanho_segunda_frase)
    segunda_frase = texto_codificado.decode("utf-8")

    numeros_inteiros = []
    soma_numeros_inteiros = 0
    for i in range(3):
        numero, = struct.unpack("i", arquivo.read(struct.calcsize("i")))
        numeros_inteiros.append(numero)
        soma_numeros_inteiros += numero

    numero_real, = struct.unpack("f", arquivo.read(struct.calcsize("f")))

    arquivo.close()

    # Para remover a quebra de linha:
    # primeira_frase.rstrip()
    print(primeira_frase)
    print(segunda_frase)
    print(numeros_inteiros, soma_numeros_inteiros)
    print(numero_real, "Número positivo?", numero_real > 0)
except IOError as excecao:
    print("Erro ao tentar ler arquivo binário.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar ler arquivo binário.", file=sys.stderr)
    print(excecao)

function escreva_indentacao(nivel)
    for indentacao = 1, nivel do
        io.write("  ")
    end
end

function escreva_tabela(tabela, nivel)
    nivel = nivel or 1
    if (type(tabela) == "table") then
        io.write("{\n")
        for chave, valor in pairs(tabela) do
            escreva_indentacao(nivel)
            io.write(tostring(chave) .. ": ")
            escreva_tabela(valor, nivel + 1)
            io.write("\n")
        end
        escreva_indentacao(nivel - 1)
        io.write("},")
    else
        local aspas = ""
        if (type(tabela) == "string") then
            aspas = "\""
        end
        io.write(aspas .. tostring(tabela) .. aspas .. ",")
    end
end

-- O programa começa aqui.
local EXIT_FAILURE = 1
local caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
local arquivo = io.open(caminho_arquivo, "rb")
if (arquivo == nil) then
    print(debug.traceback())

    error("Erro ao tentar ler arquivo binário.")
    os.exit(EXIT_FAILURE)
end

local tamanho_primeira_frase = string.unpack("T", arquivo:read(string.packsize("T")))
print(tamanho_primeira_frase)
local primeira_frase = arquivo:read(tamanho_primeira_frase)

local tamanho_segunda_frase = string.unpack("T", arquivo:read(string.packsize("T")))
print(tamanho_primeira_frase)
local segunda_frase = arquivo:read(tamanho_segunda_frase)

local numeros_inteiros = {}
local soma_numeros_inteiros = 0
for indice_numero = 1, 3 do
    local numero = string.unpack("i", arquivo:read(string.packsize("i")))
    table.insert(numeros_inteiros, numero)
    soma_numeros_inteiros = soma_numeros_inteiros + numero
end

local numero_real = string.unpack("f", arquivo:read(string.packsize("f")))

io.close(arquivo)

-- Para remover a quebra de linha:
-- string.sub(primeira_frase, 1, tamanho_primeira_frase - 1)
print(primeira_frase)
print(segunda_frase)
escreva_tabela(numeros_inteiros)
print(" " .. soma_numeros_inteiros)
print(numero_real, "Número positivo?", numero_real > 0)

extends Node

const EXIT_FAILURE = 1

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_binario_escrita.bin"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.READ) != OK):
        printerr("Erro ao tentar ler arquivo binário.")
        get_tree().quit(EXIT_FAILURE)

    var primeira_frase = arquivo.get_pascal_string()
    var segunda_frase = arquivo.get_pascal_string()

    var numeros_inteiros = []
    var soma_numeros_inteiros = 0
    for i in range(3):
        var numero = arquivo.get_32()
        numeros_inteiros.append(numero)
        soma_numeros_inteiros += numero

    var numero_real = arquivo.get_float()

    arquivo.close()

    # Para remover a quebra de linha:
    # primeira_frase.rstrip("\n")
    print(primeira_frase)
    print(segunda_frase)
    printt(numeros_inteiros, soma_numeros_inteiros)
    printt(numero_real, "Número positivo?", numero_real > 0)

Para o código JavaScript, é necessário criar uma página HTML para o envio do arquivo.

<!DOCTYPE html>
<html lang="pt-BR">

  <head>
    <meta charset="utf-8">
    <title>Leitura de Arquivo Binário</title>
    <meta name="author" content="Franco Eusébio Garcia">
    <meta name="viewport" content="width=device-width, initial-scale=1">
  </head>

  <body>
    <header>
      <h1>Leitura de Arquivo</h1>
    </header>

    <main>
      <!-- Formulário para envio do arquivo texto. -->
      <form method="post"
            enctype="multipart/form-data"
            onsubmit="return leia_arquivo(arquivos.files[0])">
        <label for="arquivos">Escolha um arquivo binário:</label>
        <input id="arquivos"
               name="arquivos"
               type="file"
               accept="application/octet-stream"/>
        <input type="submit"/>
      </form>

      <div id="conteudo">
      </div>

      <!-- O nome do arquivo JavaScript deve ser igual ao definido abaixo. -->
      <script src="./script.js"></script>
    </main>
  </body>

</html>

Pode-se, agora, discutir o código-fonte. Os programas são simples; contudo, as operações necessárias para trabalhar com bytes brutos nas linguagens JavaScript, Python e Lua tornam a solução mais complexa do que ela realmente é. Comparar cada implementação com a versão em GDScript pode ser uma boa idéia, pois os códigos fazem exatamente as mesmas operações (normalmente nas mesmas ordens).

Um detalhe: a execução dos programas imprimirá uma quebra de linha ao final da escrita de cada frase. Isso não é um erro; a quebra de linha foi armazenada no arquivo e recuperada durante a leitura. Como o programa original salvou cadeias de caracteres com uma quebra de linha no final, elas foram recuperadas na última posição dos valores lidos. É possível removê-las após a leitura ou, caso elas não sejam desejadas, salvar as frases sem a quebra de linha final em cadeias de caracteres.

Assim como para a criação do arquivo binário, é comum que subrotinas para abertura de arquivos utilizem uma flag ou valor para a abertura de um arquivo binário (ao invés de um arquivo texto). O "rb" usando em algumas implementações serve para esse propósito.

Em Python, pode-se ler bytes de um arquivo usando-se read() (documentação). O parâmetro passado é o número de bytes desejado; struct.calcsize() (documentação) fornece tamanhos (em bytes) para os tipos de dados primitivos usados. O método unpack() (documentação) converte os dados lidos nos tipos de dados escolhidos no primeiro parâmetro. Para texto, usa-se decode() (documentação) para converter a seqüência de bytes em uma cadeia de caracteres.

Em Lua, io.read() ou file:read() (documentação) permitem ler bytes, caso se passe um número como parâmetro. Assim como em Python, usa-se o tamanho do dado do tipo esperado, usando-se string.packsize() (documentação); para a conversão de bytes em dados do tipo, usa-se string.unpack() (documentação).

Em GDScript, a manipulação de arquivos binários é simples, porque existem métodos para abstrair as conversões. A leitura de dados é feita com o método get_ correspondente ao método set_ usado para armazenar o dado no arquivo binário. Assim, por exemplo, o método get_pascal_string() (documentação) lê uma seqüência de um inteiro com tamanho e os bytes para carregar uma cadeia de caracteres; get_32() (documentação) carrega um número inteiro (sem sinal) de 4 bytes (32 bits; a recuperação de sinais será apresentada em uma função chamada uint32_para_int32() disponível em um exemplo); get_float() (documentação) carrega um número em ponto flutuante de 4 bytes.

A versão em JavaScript requer mais trabalho que as demais. A leitura do arquivo usa FileReader, como em arquivos texto. Contudo, o método escolhido para leitura é readAsArrayBuffer() (documentação), que fornece um vetor de bytes. O vetor é salvo em um Uint8Array (documentação), que é um vetor de números inteiros de um byte sem sinal (ou seja, um vetor de bytes). O restante da solução consiste em interpretar seqüências de bytes armazenadas no vetor como outros tipos de dados. A função criada unpack_int32() cria um inteiro de 4 bytes (32 bits; por isso o valor 4 passado para ArrayBuffer) usando um vetor com quatro bytes, criado por slice(). Os valores são armazenados em um ArrayBuffer (documentação), que é manipulado usando DataView (documentação) para a montagem do número inteiro, armazenado-se cada um dos quatro bytes com setUint8() (documentação), e lendo o valor resultante como um inteiro de 32 bits por meio de getInt32() (documentação). A função unpack_float32() opera de forma similar, mas interpreta o valor criado como um número real em ponto flutuante de 32 bits usando getFloat32() (documentação). Para decodificar os bytes codificados de uma cadeia de caracteres, usa-se o método decode() (documentação) de TextDecoder (documentação). Deve-se notar que indice é incrementado com o número de bytes processados após cada operação, para permitir a leitura do próximo valor esperado em seu índice inicial no vetor.

O exemplo em JavaScript reforça a idéia de que linguagens de programação são ferramentas e que o ideal é escolher a melhor ferramenta para cada problema. A análise do exemplo permite sugerir que, embora possível, JavaScript não é uma linguagem muito conveniente para manipulação de bytes. Outras linguagens podem ser opções melhores para operações assim. Por exemplo, Python, Lua e GDScript fornecem algumas facilidades para manipulação de dados, por meio de abstrações como subrotinas. Caso realmente se deseje trabalhar com JavaScript para manipulação de bytes, é conveniente definir subrotinas similares. Por outro lado, elas ainda tendem exigir mais esforços para manipulação de bytes que linguagens de nível mais baixo como C e C++, nas quais bastaria informar o compilador de como se deve interpretar a seqüencia de bytes.

Técnicas Usando Arquivos

Existem técnicas e recursos avançados para uso de arquivos, como memory-mapped files, paginação, e operações de entrada e saída não bloqueantes (assíncronas; asynchronous input/output (IO)). Existem recursos convenientes para segurança, como travas para arquivos (file locking). Também existem técnicas práticas para armazenamento e recuperação de dados, especialmente em linguagens de nível mais baixo.

Como este é um tópico introdutório, as próximas subseções destacam algumas técnicas mais simples, que podem ser usadas em todos os programas. Algumas delas são mais próximas de dicas ou conselhos que de técnicas propriamente ditas, embora ainda sejam úteis.

Verificar Se Arquivo Existe Antes de Criar um Novo

A abertura de um arquivo em modo de escrita é uma operação potencialmente destrutiva, porque trunca (apaga) dados existentes caso já exista um arquivo com o caminho escolhido. Existem duas formas tradicionais para se evitar o problema:

1. A primeira é usar uma biblioteca de sistemas de arquivo que forneça uma função para verificar se um arquivo com o mesmo nome existe no caminho fornecido. O suporte para essa opção, contudo, depende da biblioteca padrão ou do uso de bibliotecas externas como dependências. Por exemplo, Python fornece vários módulos para esse fim. GDScript fornece a classe Directory (documentação);

2. A segunda funciona em qualquer linguagem de programação com suporte a arquivos. Antes de criar um novo arquivo, pode-se tentar abri-lo. Caso a operação falhe, não existe arquivo no caminho especificado. Ou seja, é possível criar um novo arquivo sem riscos de perda de dados. Caso contrário, já existe um arquivo. Nesse caso, pode-se solicitar uma confirmação para ação, preferencialmente com um aviso sobre perda de dados. Outra opção é abrir o arquivo em modo de leitura e escrita, para se preservar os dados existes e inserir novos, ou em modo append, para adição de novo conteúdo no final do arquivo.

   Também existe uma técnica derivada da segunda forma, caso se deseje usar sempre a mesma forma de manipular arquivos. Caso o arquivo não exista, cria-se um. Após a criação, o novo arquivo é fechado e reaberto em modo de leitura e escrita. Caso o arquivo já exista, ele também é aberto para leitura a escrita. Essa abordagem será necessária para GDScript, já que não existe um modo append.

O próximo exemplo utiliza a segunda forma para:

• Se o arquivo não existir, criá-lo com a mensagem: Olá, meu nome é Franco!;
• Se o arquivo já existir, abri-lo em modo append, adicionando-se uma nova exclamação ao final do arquivo.

O modo de abertura para escrita append não destrói o arquivo original; contudo, neste exemplo, ele é usado para fins ilustrativos, já que não foi usado em nenhum momento prévio.

Como o exemplo não se aplica para JavaScript (para navegadores), ele será apresentado apenas para as demais linguagens.

import io
import sys

caminho_arquivo = "franco-garcia-reuso_arquivo.txt"

try:
    arquivo = open(caminho_arquivo, "r")
    arquivo.close()

    arquivo = open(caminho_arquivo, "a")
    arquivo.write("!")
    arquivo.close()

    print("Arquivo atualizado com sucesso.")
except IOError as excecao:
    try:
        arquivo = open(caminho_arquivo, "w")
        arquivo.write("Olá, meu nome é Franco!")
        arquivo.close()

        print("Arquivo criado com sucesso.")
    except IOError as excecao:
        print("Erro ao tentar criar arquivo de texto.", file=sys.stderr)
        print(excecao)
    except OSError as excecao:
        print("Erro ao tentar criar arquivo de texto.", file=sys.stderr)
        print(excecao)
except OSError as excecao:
    print("Erro ao tentar atualizar arquivo de texto.", file=sys.stderr)
    print(excecao)

local caminho_arquivo = "franco-garcia-reuso_arquivo.txt"
local arquivo = io.open(caminho_arquivo, "r")
if (arquivo == nil) then
    arquivo = io.open(caminho_arquivo, "w")
    arquivo:write("Olá, meu nome é Franco!")
    io.close(arquivo)

    print("Arquivo criado com sucesso.")
else
    io.close(arquivo)
    arquivo = io.open(caminho_arquivo, "a")
    arquivo:write("!")
    io.close(arquivo)

    print("Arquivo atualizado com sucesso.")
end

extends Node

func _ready():
    var caminho_arquivo = "franco-garcia-reuso_arquivo.txt"
    var arquivo = File.new()
    if (arquivo.open(caminho_arquivo, File.READ) != OK):
        arquivo.open(caminho_arquivo, File.WRITE)
        arquivo.store_string("Olá, meu nome é Franco!")
        arquivo.close()

        print("Arquivo criado com sucesso.")
    else:
        arquivo.close()

        arquivo.open(caminho_arquivo, File.READ_WRITE)
        arquivo.seek_end()
        arquivo.store_string("!")
        arquivo.close()

        print("Arquivo atualizado com sucesso.")

As versões em Python e Lua utilizam o modo "a" para modo append em arquivo texto. Em Python, pode-se usar write() ao invés de writelines() para escrever uma única linha. Também é possível usar writelines(["Mensagem"]), caso se prefira.

Como GDScript não fornece-se o modo, abre-se o arquivo para leitura e atualização, usando-se File.READ_WRITE (não se deve usar File.WRITE_READ para esse propósito, pois ele remove os dados do arquivo original da mesma forma que File.WRITE). Em seguida, usa-se seek_end() (documentação) para avançar até o final do arquivo.

No primeiro uso do programa (ou ao executar o programa após apagar o arquivo), o programa criará e escreverá Olá, meu nome é Franco! no arquivo. Em execuções seguintes (assumindo que o arquivo exista), adicionar-se-á uma exclamação. Por exemplo, após executar o programa mais duas vezes, o arquivo armazenará Olá, meu nome é Franco!!!.

Uma aplicação prática para o código criado é logging.

Edição de Arquivo Existente: Inserção de Novo Conteúdo

Existem duas formas principais de modificar um arquivo existente: a forma simples e a forma mais complicada. A forma simples consiste em ler o arquivo todo em memória primária, modificar o conteúdo em memória primária, e reescrever o arquivo original usando a cópia modificada.

A forma mais complicada é fazer uma alteração in-place. Para preservar o conteúdo existente no arquivo, deve-se:

1. Avançar até o ponto da nova inserção;
2. Salvar o conteúdo deste ponto até o final do arquivo (em uma variável ou outro arquivo);
3. Adicionar o novo conteúdo;
4. Restaurar o conteúdo salvo após o novo conteúdo.

Isso é necessário porque a escrita de novos dados em qualquer posição que não seja o fim do arquivo pode resultar em sobrescrita de valores. Para entender o que ocorre, pode-se abrir um editor de texto, e escrever uma frase qualquer. Em seguida, pode-se pressionar a tecla Insert (Ins) do teclado e escrever em qualquer posição antes do final do texto. Ao invés de adicionar novos caracteres, o texto será modificado com o que se digitar. Para restaurar o comportamento original, deve-se apertar Insert novamente.

Para a programação de arquivos, existem bibliotecas que facilitam a operação. Por exemplo, em Python, pode-se usar o módulo fileinput (documentação) para modificações in-place de arquivos texto. Como o próximo exemplo aplica-se apenas para Python, a implementação adota fechamento automático.

import fileinput

caminho_arquivo = "franco-garcia-modificacao_in_place.txt"
try:
    with open(caminho_arquivo, "w", encoding="utf-8") as arquivo:
        arquivo.writelines([
            "Olá, meu nome é Franco!\n",
            "Tudo bem?\n",
            "Tchau!\n"
    ])

    with fileinput.FileInput(caminho_arquivo, inplace = True) as arquivo:
        for linha in arquivo:
            # print() é modificado para alterar o arquivo original.
            # linha contém a linha original.
            print("[Franco] ", linha, sep="", end="")

    print("Arquivo criado e modificado com sucesso.")
except IOError as excecao:
    print("Erro ao manipular arquivo.")
    print(excecao)
except OSError as excecao:
    print("Erro ao manipular arquivo.")
    print(excecao)

Por outro lado, desde que o número de bytes da alteração substitua o mesmo número de bytes presentes originalmente, a alteração pode ser mais simples. Assim, para simplificar a modificação, pode-se definir formatos de arquivos com estruturas de tamanho fixo pré-definido. Com arquivos binários, isso é mais simples: basta definir tamanhos esperados para cada parte do arquivo (preferencialmente usando um registro); a técnica será comentada em uma seção, usando um vetor como exemplo. Com arquivos textos, a técnica também é possível, embora mais restrita. Para se definir conteúdo com tamanho fixo, pode-se adicionar espaços ou outros caracteres considerados neutros (ou vazios) para preencher lacunas.

Por exemplo, para armazenar uma linha com nomes, pode-se definir um tamanho máximo de 15 caracteres. Caso um nome ocupasse menos caracteres, o texto é preenchido com o caractere escolhido como neutro para completar 15 caracteres (deve-se considerar que caracteres acentos podem ocupar múltiplos bytes). or ............... seriam duas possibilidades para um nome vazio. A primeira tem 15 espaços; a segunda tem 15 pontos finais. Franco ou Franco......... são dois exemplos de nome que cabem nos espaços. Uma modificação para Franco Garcia ou Franco Garcia.. seria possível no espaço disponível. A modificação também remover conteúdo. Uma modificação para Garcia ou Garcia......... também seria válida e caberia no espaço existente.

O mesmo vale para números. No caso, existiria um limite máximo para uma combinação da quantidade de dígitos, vírgula decimal, sinal, etc. Por exemplo, 12345, 1.234, -1.23, 0 ou 0 são números codificados em texto com exatamente 5 caracteres.

Em suma, quando possível, é mais fácil usar a forma simples e reescrever todo o conteúdo do arquivo. Embora ela possa parecer rudimentar, ela é usada com freqüência em muitos programas. A próxima seção fornece um exemplo de como aproveitá-la para gerar cópias de segurança.

Arquivo Binário: Acesso Aleatório e Modificação

Em arquivos binários, é possível manipular valores armazenados como se fosse um vetor ou um registro. Para isso, pode usar operações de seek para acesso aleatório.

Como JavaScript para navegadores lê o arquivo todo de uma vez, omite-se o exemplo para a linguagem. Afinal, para o uso do exemplo, é necessário usar uma subrotina seek() para alterar a posição do arquivo. Para um exemplo mais compacto, usa-se asserções (assert()) ao invés de tratamento de erros. Em um programa real, o tratamento adequado para erros é essencial. Para facilitar a leitura, dividiu-se a implementação nos procedimentos crie_arquivo(), modifique_arquivo() e imprima_arquivo(), chamados nessa ordem. Por curiosidade, o procedimento imprima_arquivo() foge ao padrão adotado de escreva_arquivo(), para evitar confusão com escreva_valor().

import io
import struct
import sys

TAMANHO_INTEIRO = struct.calcsize("i")

# indice 0 corresponde ao primeiro valor.
def acesse_valor(arquivo, indice):
    # O incremento por TAMANHO_INTEIRO permite pular o valor
    # armazenado com o total de números, para leitura do início
    # dos valores do vetor.
    offset_cabecalho = TAMANHO_INTEIRO
    offset_numeros = offset_cabecalho + indice * TAMANHO_INTEIRO
    arquivo.seek(offset_numeros)

def leia_valor(arquivo, indice):
    acesse_valor(arquivo, indice)
    resultado, = struct.unpack("i", arquivo.read(TAMANHO_INTEIRO))

    return resultado

def escreva_valor(arquivo, indice, valor):
    acesse_valor(arquivo, indice)
    arquivo.write(struct.pack("i", valor))

def crie_arquivo(caminho_arquivo):
    print("Criação de " + caminho_arquivo)

    arquivo = open(caminho_arquivo, "wb")
    assert(arquivo)

    total_numeros = 20
    arquivo.write(struct.pack("i", total_numeros))

    for numero in range(total_numeros):
        arquivo.write(struct.pack("i", numero + 1))

    arquivo.close()

def modifique_arquivo(caminho_arquivo):
    print("Modificação de " + caminho_arquivo)

    arquivo = open(caminho_arquivo, "rb+")
    assert(arquivo)

    total_numeros, = struct.unpack("i", arquivo.read(TAMANHO_INTEIRO))

    # Acessa o 11o valor inteiro armazenado.
    indice = 10
    valor = leia_valor(arquivo, indice)
    print(valor, valor == 11)
    # Modifica o 11o valor inteiro armazenado.
    escreva_valor(arquivo, indice, 12345)
    valor = leia_valor(arquivo, indice)
    print(valor, valor == 12345)

    escreva_valor(arquivo, 0, -1111)
    escreva_valor(arquivo, 19, 191919)

    arquivo.close()

def imprima_arquivo(caminho_arquivo):
    print("Valores em " + caminho_arquivo)

    arquivo = open(caminho_arquivo, "rb")
    assert(arquivo)

    total_numeros, = struct.unpack("i", arquivo.read(TAMANHO_INTEIRO))
    for indice_numero in range(total_numeros):
        numero, = struct.unpack("i", arquivo.read(TAMANHO_INTEIRO))
        print(numero)

    arquivo.close()

def main():
    caminho_arquivo = "franco-garcia-numeros.bin"
    crie_arquivo(caminho_arquivo)
    print()
    modifique_arquivo(caminho_arquivo)
    print()
    imprima_arquivo(caminho_arquivo)

if (__name__ == "__main__"):
    main()

local TAMANHO_INTEIRO = string.packsize("i")

-- indice 0 corresponde ao primeiro valor.
function acesse_valor(arquivo, indice)
    -- O incremento por TAMANHO_INTEIRO permite pular o valor
    -- armazenado com o total de números, para leitura do início
    -- dos valores do vetor.
    local offset_cabecalho = TAMANHO_INTEIRO
    local offset_numeros = offset_cabecalho + indice * TAMANHO_INTEIRO
    arquivo:seek("set", offset_numeros)
end

function leia_valor(arquivo, indice)
    acesse_valor(arquivo, indice)
    local resultado = string.unpack("i", arquivo:read(TAMANHO_INTEIRO))

    return resultado
end

function escreva_valor(arquivo, indice, valor)
    acesse_valor(arquivo, indice)
    arquivo:write(string.pack("i", valor))
end

function crie_arquivo(caminho_arquivo)
    print("Criação de " .. caminho_arquivo)

    local arquivo = io.open(caminho_arquivo, "wb")
    assert(arquivo)

    local total_numeros = 20
    arquivo:write(string.pack("i", total_numeros))

    for numero = 1, total_numeros do
        arquivo:write(string.pack("i", numero))
    end

    arquivo:close()
end

function modifique_arquivo(caminho_arquivo)
    print("Modificação de " .. caminho_arquivo)

    local arquivo = io.open(caminho_arquivo, "r+b")
    assert(arquivo)

    local total_numeros = string.unpack("i", arquivo:read(TAMANHO_INTEIRO))

    -- Acessa o 11o valor inteiro armazenado.
    local indice = 10
    local valor = leia_valor(arquivo, indice)
    print(valor, valor == 11)
    -- Modifica o 11o valor inteiro armazenado.
    escreva_valor(arquivo, indice, 12345)
    valor = leia_valor(arquivo, indice)
    print(valor, valor == 12345)

    escreva_valor(arquivo, 0, -1111)
    escreva_valor(arquivo, 19, 191919)

    arquivo:close()
end

function imprima_arquivo(caminho_arquivo)
    print("Valores em " .. caminho_arquivo)

    local arquivo = io.open(caminho_arquivo, "rb")
    assert(arquivo)

    local total_numeros = string.unpack("i", arquivo:read(TAMANHO_INTEIRO))
    for indice_numero = 1, total_numeros do
        local numero = string.unpack("i", arquivo:read(TAMANHO_INTEIRO))
        print(numero)
    end

    arquivo:close()
end

function main()
    local caminho_arquivo = "franco-garcia-numeros.bin"
    crie_arquivo(caminho_arquivo)
    print()
    modifique_arquivo(caminho_arquivo)
    print()
    imprima_arquivo(caminho_arquivo)
end

main()

extends Node

# 4 bytes = 32 bits
const TAMANHO_INTEIRO = 4

const INT31_MAX = 1 << 31
const INT32_MAX = 1 << 32

func uint32_para_int32(valor):
    var resultado = (valor + INT31_MAX) % INT32_MAX - INT31_MAX

    return resultado

# indice 0 corresponde ao primeiro valor.
func acesse_valor(arquivo, indice):
    # O incremento por TAMANHO_INTEIRO permite pular o valor
    # armazenado com o total de números, para leitura do início
    # dos valores do vetor.
    var offset_cabecalho = TAMANHO_INTEIRO
    var offset_numeros = offset_cabecalho + indice * TAMANHO_INTEIRO
    arquivo.seek(offset_numeros)

func leia_valor(arquivo, indice):
    acesse_valor(arquivo, indice)
    var resultado = arquivo.get_32()

    return resultado

func escreva_valor(arquivo, indice, valor):
    acesse_valor(arquivo, indice)
    arquivo.store_32(valor)

func crie_arquivo(caminho_arquivo):
    print("Criação de " + caminho_arquivo)

    var arquivo = File.new()
    arquivo.open(caminho_arquivo, File.WRITE)
    assert(arquivo.is_open())

    var total_numeros = 20
    arquivo.store_32(total_numeros)

    for numero in range(total_numeros):
        arquivo.store_32(numero + 1)

    arquivo.close()

func modifique_arquivo(caminho_arquivo):
    print("Modificação de " + caminho_arquivo)

    var arquivo = File.new()
    arquivo.open(caminho_arquivo, File.READ_WRITE)
    assert(arquivo.is_open())

    var total_numeros = arquivo.get_32()

    # Acessa o 11o valor inteiro armazenado.
    var indice = 10
    var valor = leia_valor(arquivo, indice)
    printt(valor, valor == 11)
    # Modifica o 11o valor inteiro armazenado.
    escreva_valor(arquivo, indice, 12345)
    valor = leia_valor(arquivo, indice)
    printt(valor, valor == 12345)

    escreva_valor(arquivo, 0, -1111)
    escreva_valor(arquivo, 19, 191919)

    arquivo.close()

func imprima_arquivo(caminho_arquivo):
    print("Valores em " + caminho_arquivo)

    var arquivo = File.new()
    arquivo.open(caminho_arquivo, File.READ)
    assert(arquivo.is_open())

    var total_numeros = arquivo.get_32()
    for indice_numero in range(total_numeros):
        var numero = uint32_para_int32(arquivo.get_32())
        print(numero)

    arquivo.close()

func _ready():
    var caminho_arquivo = "franco-garcia-numeros.bin"
    crie_arquivo(caminho_arquivo)
    print()
    modifique_arquivo(caminho_arquivo)
    print()
    imprima_arquivo(caminho_arquivo)

O arquivo criado armazena o número de valores inteiros armazenados no arquivo (como um inteiro de 4 bytes ou 32 bits), seguido desta quantidade de números inteiros de 4 bytes. O tamanho definido por total_numeros permite conhecer quantos números existem no arquivo. Alternativamente, caso se omitisse o tamanho e se salvasse apenas números no arquivo, poder-se-ia determinar a quantidade dos números dividindo-se o tamanho total do arquivo pelo tamanho de cada valor armazenado (4 bytes ou 32 bits).

De qualquer forma, a adição do tamanho (como comprimento) é interessante em termos conceituais. Por conveniência, o valor 4 bytes foi armazenado em uma constante chamada TAMANHO_INTEIRO.

A função mais importante na implementação chama-se acesse_valor(). Ela utiliza seek() para avançar na posição do arquivo. A implementação pula 4 bytes (que corresponde à região de memória na qual o valor do tamanho está armazenada armazenada no arquivo), e, em seguida, calcula um deslocamento multiplicando o índice pelo tamanho de cada valor (4 bytes). A operação é similar cálculo de um deslocamento de memória em um vetor, usando um recurso de baixo nível chamado ponteiro (pointer). Com a função, pode-se acessar os valores armazenados como se fossem valores de um vetor, mas armazenados em memória secundária (no arquivo) ao invés de em memória primária, e com as subrotinas leia_valor() e escreva_valor() ao invés do uso do operador colchetes. Como se trata de deslocamentos em memória a partir de um endereço base, a "indexação" inicia-se em zero.

O restante da implementação consiste na criação, modificação e leitura do arquivo criado. Em modifique_arquivo(), é importante ressaltar que o arquivo foi aberto em modo de leitura e escrita binária. Em Lua, usa-se "w+b" para designer o modo, Em Python, pode usar-se "wb+", "w+b" ou qualquer outra combinação dos três símbolos. Em GDScript, usa-se File.READ_WRITE; novamente, é importante usar File.READ_WRITE ao invés de File.WRITE_READ, pois não se deseja apagar o conteúdo de um arquivo existe, mas mantê-lo.

Para leitura e escrita de arquivo texto, o modo é semelhante, mas se omite o b em Lua e Python. Ou seja, usa-se "wb".

Para o arquivo binário, a edição pode ser feita in-place desde que o tamanho em bytes de cada valor modificado continue o mesmo. Isso é o que permite o acesso aleatório na posição específica tanto para leitura, quanto para escrita. Desde que o tipo e o tamanho seja o mesmo, qualquer valor válido para o tipo pode ser modificado sem comprometer a estrutura do arquivo.

Para comparação, arquivos texto utilizam acesso seqüêncial. Ou seja, é necessário percorrer o arquivo até encontrar um valor desejado, pois cada dado pode possui um número diferente de bytes armazenados. Em particular, qualquer modificação que altere o tamanho da string alterada afetará a seqüência de bytes no arquivo, inibindo o uso de acesso aleatório. Por outro lado, a leitura atenta da frase anterior revela que, caso sempre se salve valores com o mesmo tamanho para a cadeia de caracteres representando o valor (como mencionado em seção prévia), é possível simular acesso aleatório no arquivo texto.

Voltando ao exemplo, a implementação em GDScript requer atenção ao usar números negativos em arquivos binários. Como os valores são salvos e recuperados sem sinal, deve-se reinterpretar o número após a leitura caso o valor possa ser negativo. A função uint32_para_int32() possui este propósito, implementada como uma adaptação da nota fornecida para store_16() (documentação). Caso o valor como um número sem sinal esteja no intervalo considerado como um número negativo em complemento de dois, a seqüência de operações restaura o sinal negativo para o número. Caso o número seja positivo, o valor é preservado. O operador << usado é uma operação bit a bit (bitwise) de deslocamento de bits. Em particular, para números inteiros positivos (ou seja, números reais), o resultado de um deslocamento para a esquerda é equivalente a multiplicar um número por dois; contudo, a operação é mais rápida que a potenciação. Assim, o valor resultante corresponde a para INT31_MAX e para INT32_MAX.

Cópia Temporária Ao Salvar (ou Para Versões Anteriores do Arquivo)

Uma das formas mais simples de editar um arquivo existente é substituí-lo por um novo com o conteúdo atualizado. Uma prática comum é criar o arquivo novo da forma de um arquivo temporário, mantendo o original como uma cópia de segurança (back-up). Para isso:

1. Cria-se um novo arquivo com um nome diferente do original;
2. Se o arquivo for criado com sucesso, renomeia-se o arquivo original como uma cópia de segurança. Alternativamente, pode-se apagar o arquivo original (caso não se queira uma cópia de segurança);
3. Renomeia-se o nome do novo arquivo com o nome original.

Operações de renomear e excluir arquivos são comuns em Interface de Programação de Aplicações (Application Programming Interfaces; APIs) para manipulação de arquivos.

Como esse tipo de operação não é comum em navegadores (nem seguro; permitir que um website apague arquivos do computador não é uma boa idéia), novamente omitir-se-á um exemplo para JavaScript.

import io
import os
import sys

caminho_arquivo = "franco-garcia-arquivo_back_up.txt"
arquivo = open(caminho_arquivo, "w")
assert(arquivo)
arquivo.write("Olá, meu nome é Franco!\n")
arquivo.close()

arquivo = open(caminho_arquivo, "r")
assert(arquivo)
conteudo = arquivo.read()
arquivo.close()

conteudo += "Tchau!\n"

arquivo = open(caminho_arquivo + ".TMP", "w")
assert(arquivo)
arquivo.write(conteudo)
arquivo.close()

os.rename(caminho_arquivo, caminho_arquivo + ".BAK")
# Alternativamente, para apagar o arquivo original:
# os.remove(caminho_arquivo)

os.rename(caminho_arquivo + ".TMP", caminho_arquivo)

print("Arquivo criado e modificado com sucesso.")

local caminho_arquivo = "franco-garcia-arquivo_back_up.txt"
local arquivo = io.open(caminho_arquivo, "w")
assert(arquivo)
arquivo:write("Olá, meu nome é Franco!\n")
io.close(arquivo)

arquivo = io.open(caminho_arquivo, "r")
assert(arquivo)
local conteudo = arquivo:read("*all")
io.close(arquivo)

conteudo = conteudo .. "Tchau!\n"

arquivo = io.open(caminho_arquivo .. ".TMP", "w")
assert(arquivo)
arquivo:write(conteudo)
io.close(arquivo)

os.rename(caminho_arquivo, caminho_arquivo .. ".BAK")
-- Alternativamente, para apagar o arquivo original:
-- os.remove(caminho_arquivo)

os.rename(caminho_arquivo .. ".TMP", caminho_arquivo)

print("Arquivo criado e modificado com sucesso.")

extends Node

func _ready():
    var caminho_arquivo = "franco-garcia-arquivo_back_up.txt"
    var arquivo = File.new()
    arquivo.open(caminho_arquivo, File.WRITE)
    assert(arquivo.is_open())
    arquivo.store_string("Olá, meu nome é Franco!\n")
    arquivo.close()

    arquivo.open(caminho_arquivo, File.READ)
    assert(arquivo.is_open())
    var conteudo = arquivo.get_as_text()
    arquivo.close()

    conteudo += "Tchau!\n"

    arquivo.open(caminho_arquivo + ".TMP", File.WRITE)
    assert(arquivo.is_open())
    arquivo.store_string(conteudo)
    arquivo.close()

    var directory = Directory.new()
    directory.rename(caminho_arquivo, caminho_arquivo + ".BAK")
    # Alternativamente, para apagar o arquivo original:
    # directory.remove(caminho_arquivo)

    directory.rename(caminho_arquivo + ".TMP", caminho_arquivo)

    print("Arquivo criado e modificado com sucesso.")

Para simplificar o exemplo, a implementação utiliza asserções (assert()) ao invés de tratamento de erro. Em um programa real, o tratamento adequado para erros é essencial.

A implementação é simples. Cria-se um arquivo com algum conteúdo (que será modificado); fecha-o. Abre-se o arquivo criado; lê-se o conteúdo; fecha-o. Modifica-se o conteúdo do arquivo. Cria-se um novo arquivo para o conteúdo modificado; para diferenciá-lo do original, anexou-se a extensão .TMP, comumente usada para arquivos temporários. A extensão poderia usar letras minúsculas; o uso de maiúsculas é para realçar a extensão.

Com o novo arquivo criado, pode-se renomear ou apagar o arquivo original. No exemplo, a implementação padrão renomeia o arquivo original adicionado o sufixo .BAK, comumente usando para back-up. A linha comentada permite apagar o arquivo original. Caso ela seja usada, não se deve renomear o arquivo (caso contrário, deve-se atualizar o valor do parâmetro). É importante notar que se deve apagar o arquivo original, não o novo arquivo. Apagar o arquivo original apenas após a geração do novo arquivo permite restaurar o arquivo antigo caso a criação do novo arquivo falhe. Além disso, arquivos apagados por APIs de programação normalmente são deletados permanentemente, ou seja, eles não são enviados para a lixeira do sistema operacional. Portanto, deve-se tomar cuidado ao apagar arquivos em programas.

Em Python, o módulo os abstrai operações do sistema operacional. A subrotina os.rename() (documentação) permite renomear arquivos; os.remove() (documentação) permite apagar arquivos. Em Lua, os.rename() (documentação) permite renomear arquivos; os.remove() (documentação) permite apagar um arquivo. Em GDScript, a classe Directory fornece o método rename() (documentação) para renomear arquivos, e remove() (documentação) para apagar arquivos.

Novamente, deve usar a subrotina para apagar arquivos com cuidado. Caso contrário, perdas de dados podem ocorrer. Além disso, embora seja possível (em potencial) apagar qualquer arquivo que se tenha permissão de leitura ou escrita, não é um comportamento ético apagar arquivos que não sejam criados pelo próprio programa (exceto caso o programa criado tenha o propósito de apagar arquivos; ainda assim, é educado solicitar autorização antes de quaisquer remoções ou renomeações).

Além disso, algumas APIs podem fornecer subrotinas específicas para a criação de arquivos temporários. Por exemplo, Python provê o módulo tempfile (documentação) para criação de arquivos e diretórios temporários. Lua fornece io.tmpfile() (documentação) para criar um arquivo que é apagado automaticamente ao final do programa. A linguagem também fornece os.tmpname() (documentação) para gerar nomes para arquivos temporários.

Tamanho do Arquivo

A operação de seek permite alterar a posição no arquivo. Tanto em arquivos texto quanto em binários, é possível avançar para o final do arquivo ou retroceder para o início. A operação complementar de seek normalmente chama-se tell, que fornece a posição atual do cursor no arquivo. Caso se obtenha a posição do final e a do início, a subtração do valor do fim pelo do início pode fornecer o tamanho do arquivo em bytes.

import io

caminho_arquivo = "franco-garcia-tamanho_arquivo.txt"
arquivo = open(caminho_arquivo, "w")
assert(arquivo)
arquivo.write("Olá, meu nome é Franco!\n")
arquivo.close()

arquivo = open(caminho_arquivo, "r")
assert(arquivo)

posicao_inicio = arquivo.tell()
arquivo.seek(0, io.SEEK_END) # ou 2
posicao_fim = arquivo.tell()

arquivo.close()

tamanho = posicao_fim - posicao_inicio
print("Tamanho do arquivo: ", tamanho, " bytes.")

local caminho_arquivo = "franco-garcia-tamanho_arquivo.txt"
local arquivo = io.open(caminho_arquivo, "w")
assert(arquivo)
arquivo:write("Olá, meu nome é Franco!\n")
io.close(arquivo)

arquivo = io.open(caminho_arquivo, "r")
assert(arquivo)

posicao_inicio = arquivo:seek()
arquivo:seek("end")
posicao_fim = arquivo:seek()

io.close(arquivo)

local tamanho = posicao_fim - posicao_inicio
print("Tamanho do arquivo: " .. tamanho .. " bytes.")

extends Node

func _ready():
    var caminho_arquivo = "franco-garcia-tamanho_arquivo.txt"
    var arquivo = File.new()
    arquivo.open(caminho_arquivo, File.WRITE)
    assert(arquivo.is_open())
    arquivo.store_string("Olá, meu nome é Franco!\n")
    arquivo.close()

    arquivo.open(caminho_arquivo, File.READ)
    assert(arquivo.is_open())

    var posicao_inicio = arquivo.get_position()
    arquivo.seek_end()
    var posicao_fim = arquivo.get_position()

    arquivo.close()

    var tamanho = posicao_fim - posicao_inicio
    printt("Tamanho do arquivo: ", tamanho, " bytes.")

Em Python, tell() (documentação) fornece o valor para a posição atual do arquivo. Em Lua, isso é feito usando-se seek() sem parâmetros (documentação). Em GDScript, usa-se get_position() (documentação).

Contudo, algumas implementações de subrotinas para arquivos podem fornecer um tamanho incorreto. Assim, caso possível, pode ser preferível usar uma API para o sistema do arquivo para solicitar o tamanho real do arquivo.

Serialização (Serialization ou Marshalling) e Desserialização (Deserialization ou ou Unmarshalling)

Quando se trabalha com arquivos ou transmissão de dados via rede, termos como serialização ou marshalling são usados para se referir ao armazenamento de dados em um formato para posterior recuperação. Os dados restaurados devem ser idênticos aos dados originais, assim como os tipos usados para armazená-los. Uma aplicação comum é serializar dados armazenados em objetos de classes ou variáveis de registros.

Uma abordagem popular de serialização usando arquivos texto consiste no uso de JSON. Para ilustrar a prática, a próxima seção fornece um exemplo.

Exemplos

Em problemas envolvendo arquivos, as operações de entrada e saída usando arquivos tende a ser a parte mais simples da solução. Carrega-se dados de um arquivo para a memória primária; salva-se dados da memória primária para o arquivo. O restante da solução compreende processamento de cadeias de caracteres, conversões de tipos, inicialização de dados em registros...

Como os exemplos fornecidos ao longo deste tópico ilustram como usar as subrotinas importantes para manipulação de arquivos, os exemplos desta seção serão mais práticos e diferentes, embora potencialmente mais complexos.

Com os conceitos explorados anteriormente e arquivos, é possível começar a explorar tópicos e problemas mais interessantes. Por exemplo, a possibilidade de gerar arquivos para uso com outros programas permite a criação de conteúdo multimídia. Assim, pode-se investigar formatos formatos simples para imagens e sons. Os formatos simples podem ser reproduzidos por programas específicos (como reprodutores de mídia (media player)) ou convertidos para formatos mais comuns. Isso pode ser feito programaticamente ou usando ferramentas para conversão.

Logo, os exemplos demonstram possíveis aplicações do conhecimento em programação obtido até este ponto. De certa forma, eles são o fechamento de uma jornada básica de aprendizado de programação, marcando a transição de iniciante para alguém com conhecimento adequado de programação. Adequado no sentido de que se possui a base e os fundamentos para programação de muitos sistemas complexos, mas ainda sem a experiência e a prática necessária para se atingir competência e proficiência. Em outras palavras, tem-se potencial; é hora, pois, de materializar o potencial em sistemas.

Para propósitos didáticos e facilitar a leitura e o entendimento, as implementações não possuem otimizações. A falta de otimizações poderá ser notada em alguns exemplos, principalmente caso se aumente o valor de alguns parâmetros. Por exemplo, algumas implementações utilizam arquivos texto e cadeia de caracteres, quando o ideal seria usar arquivos binários e tipos numéricos. Ainda assim, mesmo optando-se pela simplicidade, os exemplos podem ser complexos para iniciantes (ou mesmo para profissionais; não é raro encontrar profissionais que nunca criaram uma imagem ou som programaticamente, especialmente sem o uso de bibliotecas). Por outro lado, ao final dos exemplos, você entenderá melhor como um computador funciona.

Além disso, algumas seções listam e descrevem programas para uso de alguns dos arquivos criados. A simplicidade para implementação de um formato pode resultar em maior complexidade para uso. Arquivos multimídia sem cabeçalhos requerem configuração manual para uso. Em geral, pode-se instalar apenas o recomendado, usar uma alternativa online, ou mesmo apenas simplesmente acompanhar o material.

Alternativamente, o autor disponibilizou aplicações online para visualização/reprodução dos formatos mais incomuns na página de Ferramentas. Caso você opte por usá-las, você pode ignorar as subseções descrevendo ferramentas especializadas, embora a leitura ainda possa ser útil.

Serialização e Desserialização com Arquivos JSON

O programa para receitas definido em Registros pode servir como uma boa aplicação para ilustrar o uso se serialização usando JSON. Para simplificar os blocos de código apresentados como exemplo, apenas a definição de cada registro, e o código para serialização e desserialização são apresentados. O restante do código original pode ser restaurado para um programa completo. Inclusive, poder-se-ia adicionar novas opções para o menu para salvar e carregar arquivos.

A versão em Lua requer o uso de uma biblioteca externa para manipulação de JSON. Por simplicidade, escolheu-se a biblioteca json.lua, que define subrotinas para manipulação de JSON em um único arquivo. Detalhes para uso são fornecidos antes da documentação das subrotinas empregadas.

Exemplo Simples: Registro Ingrediente

Para começar com um exemplo simples, pode-se considerar JSON como o formato do conteúdo, sem usar arquivos. Para isso, o registro Ingrediente pode ser uma boa escolha para entender como JSON funciona.

class Ingrediente {
    constructor(nome = "", quantidade = 0.0, unidade_medida = "") {
        this.nome = nome
        this.quantidade = quantidade
        this.unidade_medida = unidade_medida
    }
}

let original = new Ingrediente("Água", 3.0, "Xícaras")
// Serialização.
let texto_json = JSON.stringify(original)
console.log(texto_json)

// Desserialização.
let objeto_json = JSON.parse(texto_json)
console.log(objeto_json)
let recuperado = new Ingrediente
recuperado.nome = objeto_json["nome"]
recuperado.quantidade = objeto_json.quantidade
recuperado.unidade_medida = objeto_json.unidade_medida
console.log(recuperado)

// Se Ingrediente fosse um JavaScript Object usado como registro
// (por exemplo, sem subrotinas em variáveis):
original = {
    "nome": "Água",
    "quantidade": 3.0,
    "unidade_medida": "Xícaras"
}
texto_json = JSON.stringify(original)
console.log(texto_json)

recuperado = JSON.parse(texto_json)
console.log(recuperado)

import json

class Ingrediente:
    def __init__(self, nome = "", quantidade = 0.0, unidade_medida = ""):
        self.nome = nome
        self.quantidade = quantidade
        self.unidade_medida = unidade_medida

original = Ingrediente("Água", 3.0, "Xícaras")
# Serialização.
texto_json = json.dumps({
    "nome": original.nome,
    "quantidade": original.quantidade,
    "unidade_medida": original.unidade_medida
})
print(texto_json)

# Desserialização.
objeto_json = json.loads(texto_json)
print(objeto_json)
recuperado = Ingrediente()
recuperado.nome = objeto_json["nome"]
recuperado.quantidade = objeto_json["quantidade"]
recuperado.unidade_medida = objeto_json["unidade_medida"]
print(recuperado.nome, recuperado.quantidade, recuperado.unidade_medida)

-- <https://github.com/rxi/json.lua>
local json = require "json"

function crie_ingrediente(nome, quantidade, unidade_medida)
    local resultado = {
        nome = nome or "",
        quantidade = quantidade or 0.0,
        unidade_medida = unidade_medida or ""
    }

    return resultado
end

local original = crie_ingrediente("Água", 3.0, "Xícaras")
-- Serialização.
local texto_json = json.encode(original)
print(texto_json)

-- Desserialização.
local objeto_json = json.decode(texto_json)
print(objeto_json.nome, objeto_json.quantidade, objeto_json.unidade_medida)
local recuperado = crie_ingrediente()
recuperado.nome = objeto_json["nome"]
recuperado.quantidade = objeto_json["quantidade"]
recuperado.unidade_medida = objeto_json["unidade_medida"]
print(recuperado.nome, recuperado.quantidade, recuperado.unidade_medida)

extends Node

class Ingrediente:
    var nome
    var quantidade
    var unidade_medida

    func _init(nome = "", quantidade = 0.0, unidade_medida = ""):
        self.nome = nome
        self.quantidade = quantidade
        self.unidade_medida = unidade_medida

func _ready():
    var original = Ingrediente.new("Água", 3.0, "Xícaras")
    # Serialização.
    var texto_json = to_json({
        "nome": original.nome,
        "quantidade": original.quantidade,
        "unidade_medida": original.unidade_medida
    })
    print(texto_json)

    # Desserialização.
    var objeto_json = parse_json(texto_json)
    print(objeto_json)
    var recuperado = Ingrediente.new()
    recuperado.nome = objeto_json["nome"]
    recuperado.quantidade = objeto_json["quantidade"]
    recuperado.unidade_medida = objeto_json["unidade_medida"]
    printt(recuperado.nome, recuperado.quantidade, recuperado.unidade_medida)

Pode-se criar conteúdo em JSON sem arquivos (embora possivelmente não seja muito útil). JSON define o formato do conteúdo a ser armazenado em um arquivo texto; ele não é um tipo diferente de arquivo. O conteúdo JSON é armazenado em um arquivo texto. Assim, para se criar um arquivo JSON com o conteúdo gerado, bastaria salvar texto_json em um arquivo de texto (por exemplo, meu_ingrediente.json). O arquivo resultante possuiria o seguinte conteúdo:

{"nome":"Água","quantidade":3.0,"unidade_medida":"Xícaras"}

O valor 3.0 pode ser convertido para 3. Além disso, a ordem dos pares chave e valor pode ser diferente; assim como em um dicionário ou tabela hash, ela é irrelevante. Algumas implementações ordenam as chaves em ordem alfabética, outras usam a ordem de inserção dos valores, outras empregam ordem aleatória. Para se manter a ordem de valores em um arquivo JSON de forma portável, é necessário usar um vetor.

Assim como linguagens de programação como JavaScript e Lua, pode-se omitir quebras de linhas e espaçamentos em um arquivo JSON. Isso reduz o tamanho do arquivo para compartilhamento e torna o processamento mais rápido, mas dificulta a leitura por seres humanos. Para facilitar a leitura por pessoas, pode-se formatá-lo com indentação adequada. Existem ferramentas para isso, inclusive online (por exemplo, pode-se procurar por "json pretty print", "json beautifier" ou "json formatter"). Alguns editores de texto para programação contém funcionalidades para formatação.

{
  "nome": "Água",
  "quantidade": 3.0,
  "unidade_medida": "Xícaras"
}

Como o nome sugere, o conteúdo de um arquivo JSON é um objeto JavaScript (JavaScript Object) válido. Assim, pode-se copiar e colar qualquer um dos blocos anteriores no console de um navegador para visualizar o conteúdo do arquivo de forma estruturada. Também é possível abrir arquivos JSON no navegador, para visualização estruturada.

Trabalhar com JSON é bastante similar a trabalhar com dicionários e vetores em linguagens de programação. De fato, várias APIs para JSON abstraem o uso do formato por meio de dicionários ou de vetores de dicionários.

No caso deste primeiro exemplo, trabalhar com o conteúdo JSON criado é como usar um dicionário. Cada dicionário corresponde ao tipo definido para o registro Ingrediente codificado como dicionário.

A criação do conteúdo para JSON é simples em JavaScript. As subrotinas, inclusive, já foram usadas para cópias de vetores e dicionários. Para converter dados em JavaScript para uma cadeia de caracteres JSON, usa-se JSON.stringify() (documentação). Para converter uma cadeia de caracteres JSON em um objeto JSON, usa-se JSON.parse() (documentação).

Nas demais linguagens, o processo é similar. Python e GDScript fornecem subrotinas para processar JSON na biblioteca padrão. Lua requer o uso de uma biblioteca externa, usada como dependência. Também seria possível criar uma implementação própria para processar JSON em Lua.

• Python:

  • Serialização: json.dumps() (documentação);
  • Desserialização: json.loads() (documentação).

• Lua: a solução usa a biblioteca json.lua, disponível neste repositório.

  Para usá-la, deve copiar ou armazenar o arquivo json.lua no mesmo diretório do arquivo com código deste exemplo. A biblioteca é carregada em local json = require "json".

  • Serialização: json.encode() (documentação);
  • Desserialização: json.decode() (documentação).

• GDScript:

  • Serialização: to_json() (documentação);
  • Desserialização: parse_json() (documentação).

Com o básico sobre o formato, agora pode-se considerar o uso de JSON com arquivos para se armazenar e recuperar dados. Para isso, pode-se definir um ou vários programas. Por exemplo, um programa pode criar um arquivo, outro pode ler o arquivo criado. Alternativamente, um mesmo programa poderia criar e ler um arquivo. Os exemplos utilizam dois programas, para separar as tarefas.

Salvando um Arquivo JSON

Os próximos blocos de código ilustram como salvar o texto_json gerado em um arquivo texto.

class Ingrediente {
    constructor(nome = "", quantidade = 0.0, unidade_medida = "") {
        this.nome = nome
        this.quantidade = quantidade
        this.unidade_medida = unidade_medida
    }
}

let caminho_arquivo = "franco-garcia-ingrediente.json"

let original = new Ingrediente("Água", 3.0, "Xícaras")
// Serialização.
let texto_json = JSON.stringify(original)

let arquivo = new File([texto_json], caminho_arquivo, {type: "application/json"})
console.log("Arquivo criado com sucesso.")

let link_download = document.createElement("a")
link_download.target = "_blank"
link_download.href = URL.createObjectURL(arquivo)
link_download.download = arquivo.name
if (confirm("Fazer download do arquivo '" + arquivo.name + "'?")) {
    link_download.click()
    // Neste caso, revokeObjectURL() poderia ser usado tanto para confirmação,
    // quanto para cancelamento.
    URL.revokeObjectURL(link_download.href)
}

import io
import json
import sys

class Ingrediente:
    def __init__(self, nome = "", quantidade = 0.0, unidade_medida = ""):
        self.nome = nome
        self.quantidade = quantidade
        self.unidade_medida = unidade_medida

caminho_arquivo = "franco-garcia-ingrediente.json"

original = Ingrediente("Água", 3.0, "Xícaras")
# Serialização.
texto_json = json.dumps({
    "nome": original.nome,
    "quantidade": original.quantidade,
    "unidade_medida": original.unidade_medida
})

try:
    arquivo = open(caminho_arquivo, "w")
    arquivo.write(texto_json)
    arquivo.close()

    print("Arquivo criado com sucesso.")
except IOError as excecao:
    print("Erro ao tentar criar arquivo de texto.", file=sys.stderr)
    print(excecao)
except OSError as excecao:
    print("Erro ao tentar criar arquivo de texto.", file=sys.stderr)
    print(excecao)