% vim:tw=74:
\section{Implementação}

Nesta secção será detalhado como foi implementado o módulo, especificando
algumas opções de concepção, e será descrita a \ac{API} do módulo.

\subsection{Estruturação do Módulo}

Por forma a melhor organizar a estrutura, a implementação deste módulo foi
separada por vários submódulos. Na Figura~\ref{pic:estrutura}
pode-se ver um esquema desta estrutura.

\begin{figure}[!hbtp]
\begin{center}
\includegraphics[width=17cm]{estrutura}
\end{center}
\caption{Estrutura Geral do Módulo}
\label{pic:estrutura}
\end{figure}

No esquema notam-se claramente três zonas distintas, para além de um
ponto de agregação dessas zonas:

\begin{itemize}
\item O conjunto que engloba os módulos \texttt{Chronology::Metadata},
\texttt{Chronology::Event} e \texttt{Chronology::Chronology} diz respeito
à estrutura interna de uma cronologia.

\item Os módulos \texttt{Chronology::chronl}, \texttt{Chronology::eval} e
\texttt{Chronology::storable}, agrupados pelo módulo
\texttt{Chronology::BaseIO} dizem respeito à interacção com ficheiros
(formatos de intercâmbio de cronologias que oferecem persistência aos
dados.

\item O módulo \texttt{Chronology::CGIApp} serve de esqueleto à construção
de aplicações \ac{CGI} de navegação em cronologias.
\end{itemize}

Por fim o módulo \texttt{Chronology} fornece a interface genérica de
manipulação de cronologias.

\subsection{ChronL}

Como forma de facilitar a escrita de cronologias por terceiros
(especialmente por pessoas não ligadas ao mundo da programação) foi
desenvolvida, em conjunto com este módulo, uma linguagem que permita
descrever uma cronologia. Esta linguagem foi desenvolvida com o intuito de
ser simples (de forma a que qualquer pessoa pudesse facilmente criar uma
cronologia sem dificuldades) e poderosa (de forma a ser possível embutir
bastantes tipos de informação na cronologia).

Para o nome da linguagem escolheu-se \textbf{ChronL}\footnote{Nome
derivado da designação em inglês \emph{\textbf{Chron}ology
\textbf{L}anguage}.} e na sua definição tentou-se usar algumas notações
usadas no universo Wiki\footnote{Também conhecido por WikiWikiWeb, é um
tipo de colecção de documentos hipertextuais e simultaneamente o
ambiente colaborativo usada para os criar. A sintaxe usada varia um bocado
de implementação para implementação mas existem algumas convenções
utilizadas universalmente.}.

\subsubsection{Conceitos gerais}

A forma mais simplificada de esquematizar uma cronologia é como sendo uma
ou mais associações entre uma data e uma descrição de algo que ocorreu
nessa data. A esta associação irá, de agora em diante, ser referenciada
como sendo um \emph{evento}.

Uma cronologia é pois uma lista de eventos, geralmente agrupados por terem
algum denominador comum. Cada evento pode ser associado a uma data ou a um
intervalo de tempo. De forma a enriquecer a cronologia podem estar
associados ao evento, para além da descrição textual, um conjunto de
meta informação que possa ser útil. Também ao nível da cronologia pode
existir meta informação que se aplique a todos os eventos dessa cronologia.

\subsubsection{Estrutura}\label{cl}

Segue-se um pequeno exemplo da linguagem, neste caso um extracto de uma
cronologia da 2ª Guerra Mundial.

\begin{verbatim}
>> Segunda Guerra Mundial {sgm}
!!ref:[Portal de História|http://www.arqnet.pt]
!!lang:pt_PT
!!keyword:internacional
 
[1939/01/06]
Proclamação, pelo governo francês, de que em caso de guerra cooperaria com
a Grã-Bretanha. A proclamação recíproca foi feita pelo governo britânico
em 6 de Fevereiro.
 
[1939/01/26]
!!local:barcelona
As tropas nacionalistas conquistam Barcelona.
 
[1939/03/15][1939/03/16] Alemães ocupam Praga {e1}
!!isa:[Hitler|estadista]
As tropas alemãs entram em Praga, e ocupam a Boémia e a Morávia, enquanto
a Hungria ocupa a Ruténia.

Hitler proclama que a *Checo-Eslováquia deixou de existir*.

[1939/03/17]
!!ref:[Ocupação de Praga|{e1}]
A Grã-Bretanha e a França protestam contra a violação do Acordo de Munique,
de 1938, não reconhecendo a validade da nova situação criada na
Checo-Eslováquia pela acção da Alemanha.

[1939/03/17]
!!isa:[Franco|estadista]
!!keyword:nacional
Portugal e a Espanha nacionalista, representada pela Junta de Burgos e pelo
Nuevo Estado dirigido por Franco, assinam em Lisboa um Tratado de Amizade
e Não Agressão.
\end{verbatim}

Pelo exemplo já se consegue deduzir grande parte da sintaxe da linguagem
mas iremos ver agora a mesma com mais detalhe.

\paragraph{Cronologia}

Uma cronologia inicia-se com um cabeçalho. Este tem de conter uma linha
começada por \texttt{>>} e seguida do título da cronologia. Opcionalmente
essa linha pode conter, no fim, um identificador da cronologia escrito
entre chavetas (p.e., \texttt{\{sgm\}}). Depois desta linha podem-se
seguir várias linhas com meta dados (que serão descritos mais à frente) e
os eventos da cronologia.

\paragraph{Evento}

Um evento também é iniciado por cabeçalho. A primeira linha é iniciada por
uma data (dentro de parêntesis rectos) e pode opcionalmente conter uma
segunda data (em casos em que o evento seja um intervalo de tempo), um
nome para o evento e um identificador do evento (no mesmo formato do
identificador da cronologia. Depois desta linha podem-se várias seguir
linhas com meta dados (opcionais) e a descrição do evento.

\paragraph{Data}

Uma data pode conter os seguintes elementos (indicados por ordem):

\begin{itemize}
\item Aproximado -- indica que a data é aproximada, denota-se pelo símbolo
\texttt{~}.

\item Era -- indica que a data é anterior ao ano 0, denota-se pelo símbolo
\texttt{BC}\footnote{Do termo inglês, \emph{Before Christ}.}.

\item Ano -- indica o ano do evento. É o único componente obrigatório.

\item Mês -- indica o mês do evento.

\item Dia -- indica o dia do evento.

\item Hora -- indica a hora do evento. O formato usado é \texttt{HH:MM}.
\end{itemize}

Os elementos dentro da data são separados por espaço excepto entre o ano,
mês e dia onde  separador pode ser o caracter \texttt{/}, o \texttt{-} ou
o \texttt{:}.

\paragraph{Descrição}

A descrição de um evento deve fornecer a descrição textual do evento. De
forma a não gerar conflitos cada linha da descrição não pode começar com
os destes símbolos: \texttt{>>}, \texttt{!!} e \texttt{[}. Todos os
espaços em branco e mudanças de linha são ignorados, caso se pretenda
inserir uma mudança de linha é necessário deixar uma linha em branco. É
possível inserir referências no meio do texto (com o mesmo formato das
descritas nos Meta dados) e marcas de formatação: texto delimitado
por \texttt{**} é interpretado como estando carregado e texto delimitado
por \texttt{*} é interpretado como estando enfatizado. O caracter
\texttt{$\backslash$} serve de caracter de escape, caso se deseje inserir
esse caracter é necessário repeti-lo~(\texttt{$\backslash\backslash$}).

\paragraph{Metadados}

A região de metadados (tanto de um evento como de uma cronologia) pode
contar várias informações, no entanto a sua presença não é obrigatória.
Cada metadado ocupa uma linha e tem o formato
\texttt{!!\emph{chave}:\emph{valor}}.

Cada chave aceita um tipo de informação distinta. As seguintes chaves
estão definidas:

\begin{description}
\item[local] Descreve o local onde ocorreu a acção.

\item[author] Uma lista dos autores do objecto (evento/cronologia).

\item[ref] Uma referência externa ao objecto. O valor pode ser um dos
seguintes tipo de referência:

\begin{itemize}
\item HTTP:\\
\texttt{[Universidade do Minho|http://www.uminho.pt]}

\item FTP:\\
\texttt{[FTP DI|ftp://ftp.di.uminho.pt]}

\item Imagem:\\
\texttt{[Imagem1|pic1.png]}

\item Ficheiro:\\
\texttt{[Texto|file.txt]}

\item Evento:\\
\texttt{[Outro Evento|\{e1\}]}
\end{itemize}

Em todos os casos a primeira metade da referência fornece uma descrição
textual da referência.

\item[keyword] Uma lista de \emph{keywords} do objecto.

\item[lang] Uma língua em que está escrito o objecto.

\item[isa] Uma lista de pares associativos da forma
\texttt{[entidade|descrição]} também designado por \emph{classe}. A
utilização mais comum é associar participantes ao papel desempenhado na
acção.
\end{description}

Sempre que a chave aceita uma lista como valor, os diversos elementos
devem ser separados pelo caracter \texttt{,} ou \texttt{;}. Em casos em
que o valor seja uma lista pode-se também repetir a mesma chave noutra
linha de metadados.

\subsection{Componentes}

Como já foi dito, o módulo encontra-se dividido em vários submódulos. Nas
próximas secções vai-se explicar cada um dos módulos e descrever a
\ac{API} implementada em cada um deles (em casos onde isso seja
aplicável).

\subsubsection{Chronology}

Este módulo é o módulo principal. É um objecto que pode englobar várias
cronologias e é sobre ele que são efectuadas a maior parte das operações.

A grande parte das operações que este módulo realiza envolvem a invocação
de métodos dos submódulos correspondentes.

Os métodos disponíveis são:

\begin{description}
\item[new]~\\
Parâmetros: \emph{Nenhuns} ou \emph{"backend"}, \emph{"ficheiro"}\\
Saída: objecto \texttt{Chronology}

Construtor do objecto. Caso lhe sejam passados os parâmetros inicializa o
módulo com a cronologia lida do \emph{ficheiro} usando o \emph{backend}.

\item[save]~\\
Parâmetros: (\emph{"backend"}, \emph{"ficheiro"})\\
Saída: \emph{Nenhuma}

Tenta guardar o conteúdo do objecto no \emph{ficheiro} usando o
\emph{backend}.

\item[load]~\\
Parâmetros: \emph{"backend"}, \emph{"ficheiro"}\\
Saída: \emph{Nenhuma}

Tenta carregar o conteúdo do \emph{ficheiro} usando o \emph{backend}.

\item[get\_chronology]~\\
Parâmetros: \emph{"id"}\\
Saída: objecto \texttt{Chronology::Chronology}

Devolve o objecto \texttt{Chronology::Chronology} identificado com o
\emph{id}.

\item[add\_chronology]~\\
Parâmetros: \emph{Chronology::Chronology}\\
Saída: \emph{Nenhuma}

Tenta inserir o objecto \texttt{Chronology::Chronology} passado como
parâmetro.

\item[filter]~\\
Parâmetros: [\emph{"or"},] \emph{filtro1}, \ldots\\
Saída: \emph{Chronology} ou \emph{Lista de Event}

Filtra a cronologia com os filtros especificados. Se for passado como
parâmetro mais do que um filtro o resultado é conjunção lógica de cada um
dos filtros. Caso o primeiro parâmetro seja \emph{"or"} então o resultado
é a disjunção lógica de cada um deles.

O modo normal de funcionamento devolve um objecto \texttt{Chronology} novo
mas isto pode ser alterado passando o filtro \texttt{return\_list => 1}.
Nesta situação é devolvido uma lista anónima de objectos \texttt{Event}.

Os filtros disponíveis são:

\begin{itemize}
\item \texttt{keyword => \emph{regex}}
Unifica com os eventos que tenham alguma keyword que unifique com a
expressão regular \emph{regex}.

\item \texttt{name => \emph{regex}}
Unifica com os eventos cujo nome unifique com a expressão regular
\emph{regex}.

\item \texttt{author => \emph{regex}}
Unifica com os eventos que tenham algum autor que unifique com a expressão
regular \emph{regex}.

\item \texttt{lang => \emph{regex}}
Unifica com os eventos cujo língua unifique com a expressão regular
\emph{regex}.

\item \texttt{local => \emph{regex}}
Unifica com os eventos cujo local unifique com a expressão regular
\emph{regex}.

\item \texttt{description => \emph{regex}}
Unifica com os eventos cuja descrição textual unifique com a expressão
regular \emph{regex}.

\item \texttt{after => \emph{data}}
Unifica com os eventos que tenham ocorrido depois da \emph{data}
especificada em formato ChronL (ver secção~\ref{cl}).

\item \texttt{before => \emph{data}}
Unifica com os eventos que tenham ocorrido antes da \emph{data}
especificada em formato ChronL (ver secção~\ref{cl}).
\end{itemize}
\end{description}

\subsubsection{Chronology::BaseIO}

Este módulo serve de base a qualquer módulo que implemente funções de
entrada/saída (particularmente leitura e escrita em ficheiros). Como
exemplo pode-se consultar um dos seguintes módulos.

Cada módulo apenas tem de implementar dois métodos: \texttt{load} e
\texttt{save}. O método \texttt{load} tem de devolver uma estrutura
\texttt{Chronology}, \texttt{Chronology::Chronology} ou uma lista anónima
de objectos \texttt{Event}.

Os métodos deste módulo (implementados nos módulos) são invocados
directamente pelo módulo \texttt{Chronology}. O nome do módulo invocado é
controlado pelo parâmetro \emph{backend} passado como parâmetro (i.e., se
alguém quiser usar o módulo \texttt{Chronology::chronl} tem de usar o
\emph{backend} \texttt{chronl}).

\subsubsection{Chronology::chronl}

Este módulo é responsável pelo processamento de ficheiros na linguagem
ChronL. O método \texttt{load} usa a gramática definida formalmente no
Anexo~\ref{gramatica}. A implementação em \ac{Perl} foi feita usando o
módulo \texttt{Parse::RecDescent}.

Este módulo permite gerar \emph{parsers} recursivo-descendentes a partir
de uma especificação de gramática. Segue-se um pequeno exemplo desta
gramática:

\begin{verbatim}
my grammar = <<'FIM';
{
  use Chronology::Chronology;
  my $count_c = 0;
}
chrono: '>>' name id(?) /\n/ metadate(s?) event(s?)
{
  my %c;
  my $id;
  if(@{$item[3]} && !(exists $id_c{$item[3]->[0]})) {
    $id = $item[3]->[0];
  } else {
    $id = "_c${count_c}_";
    $count_c++;
  }
  $id_c{$id} = undef;
  $c{id} = $id;
  
  my $c = new Chronology::Chronology(%c);
  map { $_->chrono($c); } (@{$c->events()});
  $return = $c;
}
     |
{ $return = {}; }
...
FIM
\end{verbatim}

O primeiro bloco de código (os blocos de código são delimitados por
chavetas) permite fazer algumas declarações e/ou inicializações.

Cada produção pode conter o seu bloco de código. Nestas situações os
elementos do lado direito da produção podem ser acedidos através da lista
\texttt{@item}. Na variável \texttt{\$return} é colocado o resultado
final.

Os símbolos terminais são identificados por estarem dentro de plicas mas
também podem ser definidos por uma expressão regular \ac{Perl}
(representadas no exemplo por estarem entre caracteres \texttt{/}).

Para os símbolos não terminais é possível especificar operadores de
repetição:

\begin{itemize}
\item \texttt{(?)} -- zero ou uma ocorrência
\item \texttt{(s?)} -- zero ou mais ocorrências
\item \texttt{(s)} -- uma ou mais ocorrências
\end{itemize}

O axioma da gramática é o primeiro símbolo não terminal não definido

\subsubsection{Chronology::storable}

Este módulo usa o conhecido módulo \texttt{Storable} para guardar o
objecto \texttt{Chronology} para um ficheiro. A vantagem deste módulo é
que permite guardar estruturas de dados complexas de uma maneira simples e
eficaz, preservando todo o seu estado interno.

\subsubsection{Chronology::eval}

Este módulo faz uso da primitiva de \ac{Perl} \texttt{eval} e do módulo
\texttt{Data::Dumper}. Este módulo permite guardar uma estrutura num
formato textual que pode interpretado com o \texttt{eval}. Esta abordagem
permite guardar o estado interno do módulo de tal forma que pode ser
consultado com um editor de texto.

\subsubsection{Chronology::Metadata}

Este módulo engloba as operações comuns de manipulação de metadados que se
podem aplicar tanto a um evento como a uma cronologia. Os seguintes
métodos estão definidos:

\begin{description}
\item[name]~\\
Parâmetros: \emph{Nenhuns} ou \emph{"nome"}\\
Saída: \emph{"nome"}

Método que permite consultar o valor do nome do objecto. Caso seja passado
um parâmetro \emph{"nome"} o valor é alterado.

\item[id]~\\
Parâmetros: \emph{Nenhuns} ou \emph{"id"}\\
Saída: \emph{"id"}

Método que permite consultar o valor do identificador do objecto. Caso
seja passado um parâmetro \emph{"id"} o valor é alterado.

\item[lang]~\\
Parâmetros: \emph{Nenhuns} ou \emph{"língua"}\\
Saída: \emph{"língua"}

Método que permite consultar a Língua em que se encontra definido o
objecto. Caso seja passado um parâmetro \emph{"língua"} o valor é alterado.

\item[local]~\\
Parâmetros: \emph{Nenhuns} ou \emph{"local"}\\
Saída: \emph{"nome"}

Método que permite consultar o local do objecto. Caso seja passado um
parâmetro \emph{"local"} o valor é alterado.

\item[references]~\\
Parâmetros: \emph{Nenhuns} ou \emph{Lista de referências} ou
\emph{Referência}, 1\\
Saída: \emph{Lista de referências}

Método que permite consultar a lista de referências associadas a um
objecto. Caso seja passada uma lista anónima o valor é alterado.
Se for passado um segundo argumento com o valor booleano de verdadeiro é
assumido que o primeiro elemento é apenas uma referência e esse valor é
adicionado à lista de referências do objecto.

Uma referência é uma lista anónima composta por (por ordem):

\begin{enumerate}
\item Tipo de referência:
\begin{itemize}
\item \texttt{"http"} -- uma referência HTTP
\item \texttt{"ftp"} -- uma referência FTP
\item \texttt{"img"} -- uma imagem
\item \texttt{"file"} -- um ficheiro
\item \texttt{"chrono"} -- outro evento
\end{itemize}
\item Localização -- tipicamente uma \emph{url} ou um \emph{path}, no caso
de ser outro evento é o identificador do evento.
\item Descrição textual da referência
\end{enumerate}

\item[isa]~\\
Parâmetros: \emph{Nenhuns} ou \emph{Lista de Classes} ou \emph{Classe}, 1\\
Saída: \emph{Lista de Classes}

Método que permite consultar a lista de classes do objecto. Caso seja
passada uma lista anónima o valor é alterado. Se for passado um segundo
argumento com o valor booleano de verdadeiro é assumido que o primeiro
elemento é apenas uma classes e esse valor é adicionado à lista de classes
do objecto.

Uma classe é uma lista anónima em que o primeiro elemento identifica a
entidade e o segundo elemento descreve essa entidade.

\item[keyword]~\\
Parâmetros: \emph{Nenhuns} ou \emph{Lista de keywords} ou
\emph{"keyword"}, 1\\
Saída: \emph{Lista de keywords}

Método que permite consultar as keywords associadas ao do objecto. O
funcionamento é semelhante aos métodos anteriores. sendo que cada keyword
é uma \emph{string}.

\item[author]~\\
Parâmetros: \emph{Nenhuns} ou \emph{Lista de autores} ou
\emph{"autor"}, 1\\
Saída: \emph{Lista de autores}

Método que permite consultar os autores de um objecto. O funcionamento é
semelhante aos métodos anteriores. Cada autor é também uma \emph{string}.

\item[html\_reference]~\\
Parâmetros: \emph{Referência}\\
Saída: \emph{Código HTML}

Método que permite converter uma referência em HTML.

\item[make\_ref]~\\
Parâmetros: \emph{"tipo"}, \emph{"url"}, \emph{"descrição"}\\
Saída: \emph{Referência}

Método que permite criar uma referência a partir dos seus componentes.

\item[make\_isa]~\\
Parâmetros: \emph{"entidade"}, \emph{"descrição"}\\
Saída: \emph{Classe}

Método que permite criar uma classe a partir dos seus componentes.
\end{description}

Os métodos definidos neste módulo podem ser invocados a partir dos dois
módulos seguintes.

\subsubsection{Chronology::Event}

Este objecto engloba as operações disponíveis sobre um evento:

\begin{description}
\item[new]~\\
Parâmetros: emph{Nenhuns} ou \emph{Opção1}, [\emph{Opção2}, \ldots]\\
Saída: Objecto \emph{Chronology::Event}

Este método serve de construtor de um evento. Podem ser passadas opções
que permitem inicializar os campos do evento. As opções são passadas sobre
a forma de lista associativa \texttt{campo => valor}.

\item[chrono]~\\
Parâmetros: \emph{Nenhuns} ou Objecto \emph{Chronology:.Chronology}\\
Saída: Objecto \emph{Chronology::Chronology}

Método que permite obter a cronologia onde o evento se insere de um. Caso
seja passada uma cronologia como parâmetro o valor é alterado.

\item[description]~\\
Parâmetros: \emph{Nenhuns} ou \emph{Descrição} ou \emph{Descrição}, 1\\
Saída: \emph{Descrição}

Método que permite consultar a descrição do objecto. Caso seja passada uma
descrição o valor é alterado. Se for passado um segundo argumento com o
valor booleano verdadeiro, o valor passado como argumento é acrescentado
ao fim da descrição já existente.

A descrição é uma lista anónima de pares \texttt{(tipo de informação,
valor)}. Os tipos de informação disponíveis são:

\begin{itemize}
\item \texttt{"pt"} -- texto sem formatação.
\item \texttt{"st"} -- texto carregado.
\item \texttt{"em"} -- texto enfatizado.
\item \texttt{"nl"} -- parágrafo.
\item \texttt{"ref"} -- referência.
\end{itemize}

\item[toHTML]~\\
Parâmetros: \emph{Nenhuns} ou \emph{toc => 1}\\
Saída: Código HTML

Converte o evento para HTML. Caso seja passado o parâmetro \texttt{toc} é
é apenas gerada uma descrição mais curta do evento.

\item[html\_description]~\\
Parâmetros: \emph{Nenhuns}\\
Saída: Código HTML

Converte a descrição do evento para HTML.

\item[text\_description]~\\
Parâmetros: \emph{Nenhuns}\\
Saída: Texto

Converte a descrição do evento para Texto.

\item[filter]~\\
Parâmetros: [\emph{"or"},] \emph{filtro1}, \ldots\\
Saída: Booleano

Testa se um filtro unifica com o evento. O modo de funcionamento é
semelhante ao do método \texttt{filter} do módulo \texttt{Chronology}. Os
filtros válidos são: \texttt{keyword}, \texttt{name}, \texttt{author},
\texttt{lang}, \texttt{local}, \texttt{description}, \texttt{after} e
\texttt{before}.

\item[make\_plain\_text]~\\
Parâmetros: Texto\\
Saída: Descrição

Converte o texto em texto normal usado num elemento de Descrição.

\item[make\_emph\_text]~\\
Parâmetros: Texto\\
Saída: Descrição

Converte o texto em texto enfatizado usado num elemento de Descrição.

\item[make\_strong\_text]~\\
Parâmetros: Texto\\
Saída: Descrição

Converte o texto em texto carregado usado num elemento de Descrição.

\item[make\_newline]~\\
Parâmetros: \emph{Nenhuns}\\
Saída: Descrição

Gera um elemento de mudança de linha para a Descrição.
\end{description}

Como este módulo deriva do \texttt{Chronology::Metadata} todos os métodos
desse módulo podem ser usados.

\subsubsection{Chronology::Chronology}

Este objecto engloba as operações disponíveis sobre uma cronologia:

\begin{description}
\item[new]~\\
Parâmetros: emph{Nenhuns} ou \emph{Opção1}, [\emph{Opção2}, \ldots]\\
Saída: Objecto \emph{Chronology::Event}

Este método serve de construtor de à cronologia. Podem ser passadas opções
que permitem inicializar os campos da cronologia. As opções são passadas
sobre a forma de lista associativa \texttt{campo => valor}.

\item[events]~\\
Parâmetros: \emph{Nenhuns} ou \emph{Lista de Chronology::Event} ou
\emph{Chronology::Event}, 1\\
Saída: \emph{Lista de Chronology::Event}

Método que permite obter a lista de eventos da cronologia. Caso seja
passada lista anónima de eventos como parâmetro o valor é alterado. Se for
passado apenas um evento seguido de um valor booleano verdadeiro, esse
evento é adicionado à lista de eventos da cronologia.

\item[get\_event]~\\
Parâmetros: \emph{"id"}\\
Saída: \emph{Chronology::Event}

Método que permite obter o evento identificado com um determinado
\emph{"id"}.

\item[filter]~\\
Parâmetros: [\emph{"or"},] \emph{filtro1}, \ldots\\
Saída: Objecto \emph{Chronology::Chronology}

Testa os eventos que unificam com um filtro e devolve um novo objecto
\texttt{Chronology::Chronology} contendo esses eventos. O modo de
funcionamento é semelhante ao do método \texttt{filter} do módulo
\texttt{Chronology}. Os filtros válidos são: \texttt{keyword},
\texttt{name}, \texttt{author}, \texttt{lang}, \texttt{local},
\texttt{description}, \texttt{after} e \texttt{before}.

Os filtros relativos aos metadados são primeiramente aplicados aos
metadados da cronologia. Se unificarem toda a cronologia é devolvida. Caso
contrário é testado cada evento individualmente.

\end{description}

\subsubsection{Chronology::CGIApp}

Este módulo fornece o esqueleto à construção de uma aplicação \ac{CGI}
que permita a navegação numa cronologia. 

Este módulo usa o \emph{framework} \texttt{CGI::Application} que permite o
desenvolvimento de aplicações \ac{CGI} usando uma metodologia de ``Modos
de Execução'', semelhante à abordagem  de ``máquina de estados''
apresentada na secção~\ref{state}. Cada modo de execução corresponde a um
tipo de informação mostrada e a transição entre modos é feita usando hiperligações.

Foram definidos os seguintes modos, cada um com correspondência com uma
função presente neste módulo:

\begin{enumerate}
\item mostrar todas as cronologias -- \texttt{show\_all}
\item mostrar apenas uma cronologia -- \texttt{show\_chrono}
\item mostrar apenas um evento evento -- \texttt{show\_event}
\end{enumerate}

À medida que vamos descendo nesta hierarquia, a granularidade da
informação vai aumentando. Para se permitir capacidades de pesquisa foram
criados dois modos extra: \texttt{find} (mostra formulário de pesquisa) e
\texttt{find\_res} (mostra resultados de pesquisa).

O comportamento da aplicação é descrito na Figura~\ref{pic:cgi}.

\begin{figure}[!hbtp]
\begin{center}
\includegraphics[width=13cm]{cgi-state}
\end{center}
\caption{Comportamento da \ac{CGI}}
\label{pic:cgi}
\end{figure}

Um exemplo de utilização deste módulo pode ser encontrado no
Anexo~\ref{a:browse}. Deve-se ter em atenção os dois parâmetros passados
ao construtor, eles indicam o ficheiro de cronologias a ser utilizado e o
formato em que ele se encontra.

Outro cuidado que deve ser levado em conta na utilização deste módulo é
que o ambiente de execução vai ser definido pelo servidor Web. Nesta
situação é necessária particular atenção aos caminhos para ficheiros
usados.
