Manual do Programador

Com o objetivo de viabilizar a colaborao com o projeto foi criado este manual do programador. Nele se pretende explicar em que se baseia o projeto, assim como descrever o modo como ele foi implementado. No manual, o programador que pretende colaborar com o projeto encontra tudo o que precisa para compreender o cdigo fonte. Para maiores detalhes consultar o JavaDOC. Manual do Programador Introduo Idias fundamentais Pr-requisitos Configurao de Ambiente IDE Compilando e executando o tira-teima Funcionamento do Programa Ciclo de Vida Recebimento dos arquivos Inicializao do Programa Gerao de Passos Algoritmo de Gerao de Estados: Execuo dos Comandos Salvamento de Estados Controle de Estados Descrio dos Pacotes Controlador GUI Principal Funcionamento da Principal.java: (a) Instancia a Principal(): (b) Insere o texto do arquivo fonte na caixa de texto(Editor de Texto) Alerta Console Variaveis Editor de Texto

Introduo
O Tirateima uma ferramenta educacional para auxiliar no ensino de disciplinas introdutrias de Computao. Ele apresenta a execuo iterativa de um cdigo fonte fornecido e, atravs de um roteiro, gera animaes e comentrios em Tela. Fornecendo assim uma viso dos estados de execuo do programa estudado.

Idias fundamentais
A idia bsica do programa um interpretador de textos que destaca as palavras chaves do algoritmo estudado junto com a linha que est sendo executada, ao mesmo tempo que o painel direita exibe desenhos a partir de roteiros fornecidos junto com o algoritmo estudado. O programa executa um varredura no arquivo texto contendo o algoritmo estudado e no arquivo contendo o roteiro de animao, gera uma lista de estados de execuo, associando cada linha do cdigo fonte com desenhos, comentrios e animaes. Aps a lista de estados montada, o usurio pode controlar a execuo do algoritmo utilizando um menu de controle apresentado na tela.

Pr-requisitos
Orientao a Objeto (OO): O Tirateima foi concebido a partir de uma modelao orientada a Objetos, ento seu entendimento depende diretamente de conhecimentos prvio de OO. Swing: Toda a interface grfica de menus do programa utiliza componentes do pacote Swing, ento seu conhecimento fundamental para alterar a exibio do programa. JavaCC: O programador que quiser alterar a forma de reconhecimento de comandos a partir dos arquivos textos de imput deve ter conhecimentos bsicos do plugin JavaCC, que utilizado para gerar as classes de parse do programa. Sua utilizao de d devido dificuldade e complexidade no desenvolvimento de um sistema que reconhea uma linguagem apartir de uma gramtica definida.

Configurao de Ambiente
IDE
O tira-teima um programa desenvolvido no Eclipse IDE. A utilizao dessa ferramenta facilitar a compreenso do cdigo atravs de plugins que permitem o highlighting de arquivos com extenso do javacc (.jj) e facilitam o acesso ao repositrio escolhido pelo desenvolvedor (subclipse caso opte pelo svn). O Eclipse pode ser baixado seguindo-se os seguintes passos:

1. Baixe o Eclipse Classic (o ltimo da lista) relativo ao seu sistema operacional em http://www.eclipse.org/downloads/ Obs. 1: no linux, faa "sudo apt-get install eclipse" para baix-lo Obs. 2: no windows, basta descompactar o eclipse na pasta desejada. 2. Com a IDE corretamente instalada, faa o download dos plugins javacc e subclipse. a. Javacc O Javacc um gerador de analisador sinttico para o Java. Ele utilizado no tira-teima com duas finalidades: cria o parser para os arquivos de instruo do tira-teima (funcionalidade padro) e fazer o highlighting dos arquivos com extenso .jj Voc pode fazer o download do plugin Javacc para o Eclipse com os seguintes passos: 1. No eclipse, cliquem em Help, Install New Software e coloquem o seguinte link em Work with: http://eclipse-javacc.sourceforge.net/ 2. Marque o JavaCC Eclipse Plug-in e o instale. Faa tambm o download do Javacc pelo site oficial: https://javacc.dev.java.net/ b. Subclipse Este um plugin que permite o acesso a servidores SVN. Voc pode baix-lo com os seguintes passos: 1. No eclipse, cliquem em Help, Install New Software e coloquem o seguinte link em Work with: http://subclipse.tigris.org/update_1.6.x 2. Marque todos os trs e os instalem.

Compilando e executando o tira-teima

Para a correta compilao e posterior execuo do programa necessrio que sejam passados dois parmetros para ele: um arquivo texto com o cdigo fonte do programa a ser analisado pelo usurio e um arquivo com extenso .dat com um script que dir as aes que o tira-teima ir realizar. Caso opte pela utilizao do Eclipse, poder utilizar tais parmetros de compilao de maneira mais fcil: 1. Clique em Run -> Run Configurations -> Java Aplication-> Arguments. 2. Selecione os arquivos com extenses .pas e .dat e cole-os na aba dos argumentos nessa ordem. 3. Clique em Run. Caso opte pela compilao por linha de cdigo leia o artigo Documentao Tira Teima presente na pasta doc do tira-teima.

Funcionamento do Programa
Ciclo de Vida

1. Recebimento dos arquivos Principais Partes Envolvidas: Programa, Applet ou AppletEscondida. O programa se inicia com o recebimento de dois arquivos, um fonte em Pascal, C ou outra linguagem e um roteiro do tirateima. Esses arquivos so recebidos: como argumentos da funo main, localizada na classe Programa; ou como parmetros do Applet, por meio das classes Applet ou AppletEscondida. Usualmente recebe-se um programa.pas como primeiro parmetro e um roteiro.dat como segundo. Esse parmetros (arquivos) so passados para a classe Principal, a qual instanciada com seu construtor recebendo esses dois arquivos. 2. Inicializao do Programa Principais Partes Envolvidas: Principal e Controlador A inicializao do programa fica por conta da classe Principal, a qual quando construda utiliza o mtodo inicializar() para setar os principais componentes da tela, como os painis que daro origem s partes do programa. Em seguida a Principal coloca o texto do arquivo fonte em pascal no editor de texto. Instancia, ento, um Controlador. Aps inicializado, o programa volta para quem chamou a Principal (ou seja, para a Programa ou para a Applet) recebendo enfim o comando para tornar visvel o tirateima. Desse modo, possvel ver que a lgica de inicializao do programa ocorre basicamente na construo do Controlador. Ser explicado, ento, como o programa tem todos os seus estados carregados antes de ser exibido e como o programa caminha entre esses estados sob demanda do usurio.

3. Gerao de Passos

Principais Partes Envolvidas: Parser e Controlador O Parser um pacote gerado automaticamente pelo programa JavaCC. Este programa cria analisadores sintticos (parsers) a partir de um arquivo fonte criado pelo programador em uma linguagem projetada para essa finalidade. O arquivo que gera esse pacote, no caso do tirateima, o tirateima.jj. Compilando este arquivo, o JavaCC cria automaticamente uma srie de classes java que funcionaro como um parser. No caso do tirateima, o Parser analisa sintaticamente um certo roteiro.dat procurando em seu contedo um conjunto de passos (Steps), os quais no passam de uma lista de comandos (Commands). O que o parser basicamente faz, ento, receber o roteiro e retornar um passo por vez. O Controlador, por sua vez, uma classe responsvel por receber os passos (Steps) lidos pelo Parser e colocar estes em uma lista de passos. Em seguida a lista de Estados controlada por essa mesma classe.

Algoritmo de Gerao de Estados:

1. Para poder receber os passos, o Controlador executa um mtodo parse(Reader reader), que recebe o descritor do roteiro.

2. O mtodo citado instancia um Parser repassando para ele o roteiro. 3. O Controlador, em lao, recebe passo por passo do Parser; para cada passo, ele: a. Adiciona na lista de passos.
Execuo dos Comandos

No pacote Controlador existe uma srie de classes que herdam o mtodo execute() da classe abstrata Command. com esse mtodo que cada comando especfico executado. O que esses comandos fazem, basicamente, chamarem a camada de visualizao (GUI) para guardar como se ir desenhar na tela o que o comando mandar, ou realizar alguma outra operao, como tocar um som. Por exemplo, a classe CommandNewVar em seu mtodo execute() chama o mtodo adicionarVariavel() do objeto Mostrador, o qual pertence ao pacote GUI. Para entender os detalhes de como cada comando executado necessrio navegar no corpo da implementao de cada execute() especfico, observando sobretudo o momento em que ele guarda como pintar elementos na tela ou que ele de fato executar o comando, se for uma operao diferente de pintar. Observe-se que esses comandos so executados incrementalmente, sempre pintando algo alm do que j existia. Assim que esses comandos so terminados, o programa precisa salvar esse estado para que seja possvel ao usurio voltar na linha de execuo do tirateima. Para isso foi desenvolvido o salvamento de estados.
Salvamento de Estados

O pacote Controlador possui uma classe chamdada Estado. Esta classe modela uma determinada configurao do tirateima, ou seja, um estado do mesmo. Essa configurao caracterizada por como est cada componente da tela: o mostrador, o editor, a console, os alertas e o gerenciador de arquivos. Se em um dado momento o programa est com uma certa linha do editor destacada e com duas variveis exibidas no mostrador, essa configurao pode ser salva em um estado. Para salvar os estados o Controlador utiliza-se de uma Pilha de Estados. Essa pilha armazena um estado e caso o usurio avance, um estado colocado na pilha. Caso o usurio volte para um estado anterior o estado atual descartado, e carregado um estado anterior retirado da pilha. Esse estado salvo atravs do mtodo saveEstate() contido no Controlador. Esse mtodo recebe um estado e um passo e salva esse estado de acordo com os o panorama momentneo do Tira-Teima. Um ponto importante a se observar que o programa executa cada comando de cada passo em tempo de execuo, na medida que o usurio avana para os prximos passos e dependendo s vezes de entradas dos usurios (em condicionais e repeties). 4. Controle de Estados Principais Partes Envolvidas: Controlador e GUI O Controlador uma classe que responsvel por interceptar as aes do usurio e caminhar na lista de passos. O que ela faz, ento, receber um arquivo fonte, gerar uma lista de passos e percorr-los executando os comandos contidos nesses passos de acordo com a demanda do usurio. Para tanto, o controlador seleciona um passo da lista de passos e utiliza um mtodo denominado setEstado(Estado e) para carregar esse estado aps executar os comandos contidos no passo que o gerou. A interface IEstado quem define esse mtodo, o qual implementado por diversos elementos da camada GUI, cada qual a seu modo. O Console , por exemplo, tem como principal elemento de seu estado atual uma string contendo todo o texto que est escrito nele. No caso dele, o estado preserva a string e esta desenhada na tela no carregamento do estado. Assim, o mtodo setEstado do console pinta o texto armazenado na tela. Com isso o programa caminha nos estados at que o usurio feche a janela do programa, momento em que ele terminar o programa. Veja, por fim, um diagrama mais completo contendo o papel de cada mdulo em vermelho.

Descrio dos Pacotes

Controlador Um dos papis do controlador receber passos do parser, construir uma lista de passos para controlar o programa a partir dessa lista de passos. Os passos so conjuntos de comandos para o Tirateima. Ao acessar o mtodo step() do parser, fornecido um Reader de um roteiro no ponto onde ele estava sendo lido e recebido um passo, o qual possui uma lista de comandos. Os comandos so classes herdadas da classe abstrata Command. Eles modelam uma operao a ser realizada no tirateima. Novas variveis, avisos sonoros, escrita na tela e emisso de alertas na tela so exemplos de commandos. Por padro, os comandos so nomeados como Command[Nome_do_Commando]. Um exemplo o comando CommandNewVar, que comando responsvel por criar no mostrador uma nova varivel. Todos os comandos implementam um mtodo abstrato Command.execute(). Basicamente, o que o mtodo execute() faz modificar os objetos que sero afetados pelo comando. O mtodo CommandNewVar, por exemplo, em seu mtodo execute() chama o mtodo mostraror.adicionarVariavel(), ou seja, altera o estado do mostrador de acordo com os comandos descritos no roteiro escrito pelo professor. H tambm o mdodo revert(), que desfaz o que o execute() fez. Isso ocorre em alguns comandos especficos em que necessrio desfazer alguma aes para manter a lgica do programa. Antes de executar um passo, o Controlador salva o estado atual na pilha de estados, e depois executa cada passo do comando, salvando esse estado como estado corrente (saveState() ) e setando (setEstado()) esse estado. Cabe ressaltar, pela particularidade das solues, o papel de algumas classes. A classe Index modela uma matriz, que inclusive pode ser uma matriz 1xn (ou seja, um vetor). Essa classe possui dois ndices, o first e o second, os quais representam as dimenses da matriz. A classe TirateimaLanguageExeption uma classe que estende a classe Exception do Java. A idia de excees, no Java, ao capturar uma exceo, lan-la para quem a chamou at que algum a trate. Logo, todas aquelas Classes que podem gerar excees relacionadas natureza do programa esto com a marca throws TirateimaLanguageExeption. No momento no h nenhum Interceptor que trate tais classes, mas o importante no interromper o programa em tempo de execuo. Para as demais classes, consulte o Javadoc do projeto a atravs do controlador que o usurio controla a execuo do programa e ela que seta qual o estado que ser mostrado em Tela. Mtodos Relevantes proxEstado() Ao: Coloca o estado atual do Tira-Teima na pilha de estados e carrega o prximo estado. A partir do estado corrente esta classe define tudo que ser mostrado em tela, seja escolhendo o estado atravs dos botes prximo/anterior, como atravs do boto pular (boto que pula para um label especfico marcado pelo professor que escreveu o roteiro. O mtodo que define o estado que ser mostrado o setEstado(Estado e) e ele passa os atributos do estado corrente aos objetos mostrador, editor, console, alerta e ga. Ver: private void setEstado(Estado e){ mostrador.setEstado(e.est_mostrador); editor.setEstado(e.est_editor); console.setEstado(e.est_console); alerta.setEstado(e.est_alerta); ga.setEstado(e.est_ga); ajustarBotoes(); } Estado.java Classe abstrata que define o tipo estado public class Estado { public Object est_mostrador; public Object est_editor; public Object est_console; public Object est_alerta; public Object est_ga; } GUI O tirateima.gui o pacote responsvel pela interface grfica com o usurio dentro do tirateima. Ele composto por 5 subpacotes e

2 arquivos: tirateima.gui.alerta, tirateima.gui.arquivos, tirateima.gui.console, tirateima.gui.editortexto, tirateima.gui.variaveis, Constantes.java e Principal.java. Principal A classe principal.java chamada a partir do Programa.java e recebe como parmetros os arquivos fonte e texto, respectivamente. Ela responsvel pela renderizao de toda as divises da janela principal do tirateima. A tela dividida em 3 grandes painis: o Navegador (barra do topo), Editor de Texto (esquerda) e o Painel da direita, que por sua vez, composto por outras quatro divises: o Mostrador (onde ficam as animaes), o Gerenciador de Arquivos, o Console e o Alerta que aparece esporadicamente. Funcionamento da Principal.java: Inicializa o programa (Programa.java) (a) Instancia a Principal(): Chama o mtodo Inicializar() : Define o layout do painel (1) Chama criarPaineldeTexto(): Define as propriedades da caixa de texto (2) Chama criarPainelDireita(): Instancia Console Instancia Alerta Adiciona Console e Alerta na parte inferior do PainelDireita(spl_painel_abaixo) Chama criarAreaDesenho() Chama criarPainelMostrador(): Define os paineis e os layouts do mostrador Instancia o Gerenciador de Arquivos: Define o tamanho do painel e seu evento (3) Adiciona o getBarraTopo() no painel principal: Adiciona os botoes de navegao(btnanterior, btnproximo, btn reiniciar...) (controlenavegao) Adiciona os botoes de zoom e define seus eventos (zoom+, zoom-, zerar zoom) (controlezoom) Adiciona os botoes de som e ajuda bem como seus eventos (controleoutros) Por fim, adiciona os tres painis (controlenavegao, controlezoom e controleoutros que se ligam respectivamente aos trs tpicos acima) ao spl_barra_topo. Adiciona (1), (2) e (3) ao painel principal: spl_principal Define o controle de navegao pelas setas operacionais(up, down, left, right) (b) Insere o texto do arquivo fonte na caixa de texto(Editor de Texto) Chama outro mtodo chamado Inicializar() diferente de (a) Adiciona o layout ao JFrame ( janela do tirateima) Adiciona tudo o que foi elaborado na principal ao JFrame Alerta A classe alerta instanciada durante a execuo da classe Principal da GUI. Ela extende a classe JtextPane e implementa a interface IEstado. A classe Alerta responsvel pelas caractersticas do painel Alerta. Essa classe define a cores e a fonte do Alerta e possui tambm alguns mtodos que administram o som do tirateima. Ela muda os valores, por exemplo, da varivel somAtivado, que setada quando o usurio clica no boto de deixar o som mudo. Alm disso controla quando o som de alerta ser executado. A classe Alerta implementa um mtodo importante, o setEstado(), que um mtodo da IEstado.java. Esse mtodo chamado a partir da classe Controladora e responsvel pela renderizao do estado de Alerta na tela. Console A classe console tem um funcionamento bem semelhante Alerta. Ela tambm instanciada durante a execuo da classe Principal, porm extende a classe JtextArea. O Primeiro ponto a ser ressaltado que o console uma area de texto, que pode receber uma string bem grande (que guarda todo o contedo do console) e mostra a string quebrando-a em vrias linhas, ou seja, cada linha que mostrada no console, na verdade, um elemento de um ArrayList de Strings.

Durante a construo da lista de estados do programa, o Controlador manda para a classe Console, a string a ser adicionada em cada estado e o mtodo gui.console.print(String s) adiciona a respectiva string lista de strings existente no Console por meio da gui.console.organizarLinhas(String s). Feito isso o mtodo gui.console.organizarTexto() fica responsvel por renderizar o novo estado do console. Essa classe tambm responsvel por transformar tudo o que recebe (nmeros float, int ...) em strings que sero mostradas no console. O metodo gui.console.setEstado(Object o) responsvel simplesmente chamar o mtodo gui.console.print(String s) . Variaveis O Pacote gui.variaveis constitudo de um conjunto de classes que possuem uma relao de herana entre si. A classe varivel extende a classe JComponent e a classe pai de todas as classes com definio de vriaveis ( classes cujo nome iniciam com Var). Por exmplo, as classes VarGrade e VarLinha extendem Variavel. VarGrade a classe pai das classes que representam structs, matriz ou vetores, enquanto VarLinha a classe pai das outras classes, como VarBoolean, VarChar, VarFloat e etc. Essas classes de variveis tem como funo principal a definio do funcionamento dos desenhos de cada tipo de dado que ser mostrado na tela, ou seja, definem tamanho, posio e cor. Alm disso, nesse pacote se encontra a implementao da borda das variveis. Editor de Texto O pacote editortexto a parte da GUI responsvel pela parte do editor de texto do tirateima, ou seja, da parte onde fica o cdigo em pascal. Esse pacote trabalha juntamente com a classe Principal da gui. A principal contribuio do pacote gui.editortexto a de dar o highlighting no cdigo pascal e tambm de deixar marcada ( com o fundo amarelo ) a linha correspondente ao que o tirateima est mostrando nas outras janelas. Em linhas gerais o texto mostrado da seguinte forma: A gui.Principal manda o arquivo texto para a EditorTexto, que por sua vez, manda para CaixaTexto. Nessa classe ele define os tipos de estilo (comentario, palavra chave, literal, tipos e outros). Feito isso, o mtodo parseText() da prpria CaixaTexto, jutamente com Anlex e Token ( outras classes do pacote editortexto), vo lendo token a token do arquivo, definindo qual o estilo ele deve receber, colorindo-o (de acordo com cada estilo) e o escrevendo em um documento da classe StyledDocument. Para tanto, foi implementado um analisador lxico por meio de uma mquina de estados. Depois do documento pronto, a classe EditorTexto insere o documento em um painel, que por sua vez, inserido no JTextPane, juntamente com os nmeros das linhas.