1. MANUALE UTENTE
2. PROGETTAZIONE
3. IMPLEMENTAZIONE
4. POST SVILUPPO


1. MANUALE UTENTE

1.1 Presentazione:
1.1.1 Programma

1.2 Inizializzazione:
1.2.1 Caricamento dello script di inizializzazione
1.2.2 Caricamento delle Strutture Dati
1.2.3 Controlli sulle strutture dati

1.3 Simulazione:
1.3.1 Interfaccia utente
1.3.2 Visualizzazione
1.3.3 Correggere la carriera
1.3.4 Aggiungere un'attivita'
1.3.5 Rimuovere un'attivita'
1.3.6 Altre funzioni


2. PROGETTAZIONE

2.1 Diagramma a classi
2.1.1 Diagramma Globale
2.1.2 Specificazione per la classe Activity
2.1.3 Specificazione per la classe Rule
2.1.4 Definizioni complete delle classi


3. IMPLEMENTAZIONE

3.1 Codice
3.2 Main
3.3 Algoritmi di controllo
3.3.1 Validazione delle attivita' svolte
3.3.2 Riduzione delle regole
3.4 Konsole


4. POST SVILUPPO

4.1 Note di sviluppo


1. MANUALE UTENTE

1.1.1 Programma [i]
Il programma realizza un semplice simulatore interattivo di carriera di uno studente unviersitario, dati un determinato ordinamento didattico, un'offerta didattica e (opzionalmente) una carriera parziale iniziale.
Il programma viene invocato dal comando:

> simula ordinamento offerta-didattica [carriera-parziale]

dove ordinamento, offerta-didattica, carriera-parziale sono i nomi dei file contenenti rispettivamente la lista delle regole, l'offerta didattica e l'eventuale carriera parziale, scritti secondo il formato descritto nella sintassi dei file di input.

1.2.1 Caricamento dello script di inizializzazione [i]
La prima azione che compie il programma quando viene invocato e' quella di caricare il file simula.inf che si deve trovare nella stessa directory dell'eseguibile.
All'interno del file ci sono dei comandi che vengono interpretati dalla konsole.
In questa fase viene stampato a video il prompt del programma, vengono decisi il livello di segnalazione output e di registrazione delle segnalazioni, poi vengono associati i comandi per l'interfaccia.
Al termine dello script vengono effettuati i controlli sui file ordinamento e offerta.
Se questi non risultano validi viene caricato lo script simula.err che segnala l'errore e ferma il programma.
NOTE:
In caso il file simula.inf non venga trovato, viene segnalato l'errore ma il programma continua.
Una volta giunti nel menu, entrare in konsole col comando ~ e utilizzare i comandi indicati (stop per uscire).
In caso il file simula.err non venga trovato, viene segnalato l'errore ma il programma continua.

1.2.2 Caricamento delle strutture dati [i]
In questa fase vengono letti i file specificati riga per riga.
La righe nei file deve essere lunghe al massimo 999 caratteri altrimenti vengono troncate.
Il caricamento in memoria dei dati ha inizio dopo la lettura della parola "INIZIO".
Nei file ordinamento didattico e offerta, INIZIO deve essere preceduto rispettivamente da ORDINAMENTO e OFFERTA_DIDATTICA. Al termine della lista dei dati ci si aspetta di trovare "FINE"; se non si trova fine i dati caricati fino a quel momento vengono comuque ritenuti validi.
Per i dettagli si rimanda alla sintassi dei file di input.
In caso la linea presenti degli errori il programma segnala cosa si aspettava di trovare, cosa ha trovato e dove.

ie:
ATTENZIONE: atteso: , trovato: corso (offerta, linea: 7 col: 20).
ERRORE: atteso: corso o stage o tesi trovato: corao (offerta, linea: 7 col: 56).

Nel caso si tratti di un'ATTENZIONE il programma riesce comunque a capire che tipo di dato caricare, in caso di ERRORE la riga non è decifrabile.

NB: in questa fase viene anche caricato il file del menu simula.menu.

1.2.3 Controlli sulle strutture dati [i]
Si verifica che ogni struttura dati sia corretta in questo modo:
ordinamento:
Controllo se le attivita' e i settori specificati sono descritti in offerta didattica. Se no, la regola viene rimossa.
Riduco il bound associato ad una regola. Viene segnalato se si soddisfa un obiettivo o si viola un vincolo.
offerta:
Controllo se le attivita' specificate nella propedeuticita' di un'attivita' sono descritte in offerta didattica. Se no, l'attivita' viene rimossa.
Controllo se le attivita' sono state svolte.
Carico la lista di attivita' con propedeuticita' completata.
carriera:
Controllo se le attivita' svolte sono valide:
-sono in offerta
-rispettano l'anno
-le attivita' propedeutiche esistono e sono valide
Controllo se le attivita' sono in ordine cronologico.
Stampo lo stato della carriera:
CARRIERA NON CORRETTA, CARRIERA NON COMPLETA, CARRIERA COMPLETA e CARRIERA VUOTA, rispettivamente per segnalare se vi sono errori in carriera, se non ve ne sono ma non tutti gli obiettivi sono soddisfatti, se la carriera e' corretta e tutti gli obiettivi sono soddisfatti e se la carriera non è stata caricata.

In caso di errori l'utente e' sempre informato.


1.3.1 Interfaccia utente [i]
Terminati i controlli standard, il menu caricato in precedenza (simula.menu) viene stampato a schermo e viene richiesto che l'utente inserisca un comando.
I comandi disponibili sono quelli associati nel file simula.inf e il comando di konsole '~'.
Basta scrivere il comando associato all'azione che si vuole effettuare e premere invio. (ie: 1a)

Altri metodi di interfaccia standard sono le domande:

Proseguire ugualmente? (s/[n]/c)

Tra parentesi sono mostrate le tre opzioni possibili: s sta per Sì, n sta per No e c sta per Cancel. Solitamente Cancel ha lo stesso valore di No. Premendo un tasto che non sia ne' s ne' n ne' c l'input è interpretato come un No.


1.3.2 Visualizzazione [i]
La visualizzazione su schermo è sempre gestita in maniera tale che l'utente possa leggere tutto pagina per pagina.
Al termine di una pagina verrà chiesto di premere invio per proseguire.

La stampa delle liste presenta delle particolarità che permettono di evidenziarne elementi e nasconderne altri:


1.3.3 Correggere la carriera [i]
Con il comando 3a (clearcarrier) viene avviata una funzione che prova a sistemare la carriera:
innanzitutto vengono riordinati gli errori di cronologia ma se al termine di quest'azione si presentano altri errori (La carriera è ordinata cronologicamente ma ci sono altri tipi di errori) viene avviata la procedura che porta l'utente a scegliere se cancellare o meno le attività che presentano errori.
Per uscire da questa procedura scegliere Cancel alla domanda di cancellazione.
Se si sceglie di cancellare un'attività, il sistema compirà un nuovo controllo per verificare se si sono risolti degli errori, dopodichè verrà chiesto di cancellare l'attività errata successiva.


1.3.4 Aggiungere un'attivita' [i]
Il comando 4a (addexam) avvia il form di inserimento manuale di una nuova attivita' in carriera.
Per prima cosa, viene chiesto se stampare la lista di attivita' con propedeuticità completata, cioè le prossime attività che è possibile inserire senza violare la propedeuticità.

Vuoi consultare la lista di attivita' con propedeuticità completata? (s/[n]/c)

La prossima richiesta è quella di specificare il codice dell'attività che si vuole inserire:

Inserire CODICE dell'attività o NUMERO corrispondente nella lista delle attività con propedeuticità completata:

E' possibile inserire sia il codice completo (case sensitive) sia il numero corrispondente all'attivita' scelta nella lista delle attivita' con propedeuticita' completata.
Se ci sono errori (ie: il numero non corrisponde ad elementi della lista o il codice non è un codice di un'attivita' in offerta didattica) si ritorna al menu principale.
Altrimenti viene stampata l'attivita' completa con tipo di attività, crediti associati, settore di appartenenza, anno minimo e tra parentesi graffe le attività propedeutiche.

Sicuro di voler aggiungere questa attività alla carriera? (s/[n]/c)

Se No riinizia da capo con l'inserimento, se Cancel esce dal form di inserimento, se Sì continua.

Inserire ANNO:

Inserire l'anno e premere invio.
Se la lista non è vuota viene chiesto dove inserire l'elemento.

Inserire in coda? (s/[n]/c)

Se Si l'elemento viene inserito in coda, se Cancel si esce dal form di inserimento.
Se No viene chiesto se si desidera esaminare la carriera. Al termina della lista viene chiesto di inserire la posizione in cui verrà inserito l'elemento. Se il numero è superiore alla lunghezza della lista, l'elemento viene inserito in coda.
Prima di inserire l'attività in lista viene fatto un breve controllo sull'elemento. Se ci sono degli errori a questo livello si consiglia di non proseguire con l'inserimento.
Al termine dell'inserimento vengono fatti i controlli standard per verificare se ci sono dei nuovi errori o delle vuolazioni di vincoli.
Se si verificano nuovi errori:

L'inserimento ha provocato:
un nuovo errore in carriera
2 nuove violazioni dei vincoli in ordinamento
Cancellare l'attivita' appena inserita? (s/[n]/c)

Se si risponde Sì l'attività appena inserita viene rimossa, se No si continua mantenendo l'errore (Cancel coincide con No).

Infine si può scegliere se aggiungere un'altra attività o uscire.

NOTA: premendo invio quando e' richiesto di inserire dati si esce dal form.


1.3.5 Rimuovere un'attivita' [i]
Il comando 5a (removeexam) attiva il form per la rimozione di un esame.
Innanzitutto viene chiesto se si vuole visionare la carriera, poi si inserisce il codice dell'attività o il numero che la caratterizza in carriera.

Digitare CODICE dell'attività o NUMERO corrispondente nella carriera:

Viene stampata l'attivita' selezionata e viene chiesto se si è sicuri di rimuoverla:

Sicuro di voler eliminare questa attività dalla carriera? (s/[n]/c)

Al termine vengono effettuati i controlli standard. Se si verificano nuovi errori viene chiesto se si desidera reinserire l'attività:

Reinserire l'attivita' appena cancellata? (s/[n]/c)

Infine si può scegliere se rimuovere un'altra attivita' oppure uscire.

NOTA: premendo invio quando e' richiesto di inserire dati si esce dal form.


1.3.6 Altre funzioni [i]
Ora esamineremo in breve le altre funzionalità standard:
VISUALIZZA (1b, 1c): stampa in modalità normale la lista associata.
VISUALIZZA (TOTALMENTE) (1a, 2b, 2c): stampa in modalità avanzata la lista associata.
STATO DELLA CARRIERA: compie i controlli standard.
RIMUOVI CARRIERA: cancella tutti gli elementi della carriera.
SALVA: salva la carriera sullo stesso file da cui è stata caricata. Se nessun file è stato caricato viene chiesto di inserire un nome.
SALVA CON NOME: salva la carriera sul file specificato.
CARICA: carica la carriera dal file specificato.
STATO DI COMPLETAMENTO: controlla l'ordinamento.
ATTIVITA' CON PROPEDEUTICITA' COMPLETATA: stampa in modalità normale la lista di attività con la propedeuticità completata.



2. PROGETTAZIONE

2.1 Diagramma a classi [i]

2.1.1 Diagramma Globale [i]


2.1.2 Specificazione per la classe Activity [i]


2.1.3 Specificazione per la classe Rule [i]


2.1.4 Definizione completa delle classi [i]





3. IMPLEMENTAZIONE

3.1 Codice [i]
Le strutture dati di base possiedono delle caratteristiche particolari:

Il template List sviluppa queste caratteristiche con una lista concatenata di elementi.
Gli oggetti inseriti in lista non vengono copiati ma solo puntati dai Nodi della lista.
Questo significa che alla morte di List muoiono tutti i dati da essa puntati che erano stati creati fuori dall'ambiente lista.

Gli oggetti che ne fanno uso per creare una vera e propria struttura dati sono:
String, Command, Exam (che realizza la carriera), Activity (che realizza l'offerta) e Rule (che realizza l'ordinamento).

Sono inoltre realizzate per supporto altre classi:
Fileman: deve gestire l'interfaccia coi file;
Develop: deve gestire la segnalazione degli errori;
Display: deve gestire l'interfaccia video.

Altri file in cui è stato suddiviso il programma sono:
konsole.cpp: interfacciamento con l'utente
check.cpp: algoritmi di verifica
simula.cpp: programma principale

Infine due file di script sono stati preparati per velocizzare la compilazione:
compilelx: compilazione sotto Linux
compileux: compilazione sotto Unix

NB: il codice è C++, e l'ambiente di sviluppo Linux (compatibile Unix). E' preferibile far girare il programma da konsole Linux per via della miglioer gestione delle librerie grafiche.


3.2 Main [i]
Il main (simula.cpp) crea tutte le strutture dati principali:
int MAXBUFFERLENGTH: la grandezza standard dei vari buffer;
Display VIDEO: oggetto utilizzato per l'interfaccia lungo tutto il programma;
Develop LOG: oggetto per il controllo degli errori;
char *rule_file: file ordinamento;
char *activity_file: file offerta didattica;
char *exam_file: file carriera;
char *currentfile: ultimo file caricato dallo script;
List < String > string_list: lista di stringhe, usata solo in fase di test;
List < Rule > rule_list: lista di regole, ossia l'ordinamento didattico;
List < Activity > activity_list: lista di attivita', ossia l'offerta didattica;
List < Activity > noprop_activity_list: lista di attivita' (con propedeuticita' completata);
List < Exam > exam_list: lista di attivita' svolte, ossia la carriera;
List < Command > command_list: lista di comandi associati (per l'interfaccia);
List < String > menu_list: lista di stringhe, ossia il menu;
int errors: numero di errori in carriera;
int violations: numero di violazione dei vincoli;
int tot_obj: numero di obiettivi in ordinamento;
int obj: numero di obiettivi soddisfatti.

Vengono poi svolte le seguenti attivita':


3.3 Algoritmi di controllo [i]
Gli algoritmi di controllo sono tutti racchiusi nel file check.cpp.
Di seguito la spiegazione dettagliata di due algoritmi che utilizzano a fondo le peculiarità delle strutture dati.

3.3.1 Validazione delle attivita' svolte [i]
Un ciclo passa in rassegna tutte le attività della carriera e chiama ValidActivity.
Se ValidActivity ritorna zero, l'attività viene marcata con una "x" per segnalare l'errore e non viene calcolata nella riduzione delle regole.

int ValidActivity(Exam &data, int where);

La funzione prende come argomento l'attivita' da controllare e la sua posizione.
La posizione where, in seguito ad evoluzioni del codice, non è più utilizzato ed è stato lasciato solo per facilitare ulteriori possibili modifiche.
Controlla se un'attività è valida compiendo 3 controlli:

3.3.2 Riduzione delle regole [i]

Similmente a ValidActivity la procedura di riduzione di una regola si trova in un ciclo che passa in rassegna tutte le regole e chiama ReduceRule.
La differenza rispetto a ValidActivity è che Reduce Rule non fornisce dati sulla regola. Infatti il chiamante (CheckOrder) compie un ciclo ulteriore per controllare se ci sono obiettivi soddisfatti o vincoli violati.
Questa separazione di controlli è dovuta al fatto che, all'interno della riduzione il bound della regola viene diminuito iterativamente e quindi non riuscirei a tenere traccia di quanti obiettivi/vincoli sono stati soddisfatti/violati ma solo del numero di attività che soddisfano/violano la regola.
Inoltre separare i processi di controllo è utile per il programmatore stesso.

void ReduceRule(Rule &data)

La funzione prende come argomento una regola poi procede al controllo di cosa debba calcolare:

if(!strcmp(data.GetUnita()->GetItem(), "crediti"))
if(strcmp(data.GetQta()->GetItem(),"almeno"))

adesso so se devo calcolare crediti oppure unità e se la regola è un obiettivo o un vincolo.
Poi inizia la fase di conteggio in cui differenzio i tre casi fondamentali:

if(!strcmp(data.GetT_att()->GetItem(), "corso"))
else if(!strcmp(data.GetT_att()->GetItem(), "complessivamente"))
else (if(tesi o stage))


NB: se il vincolo risulta violato l'attività svolta che ha provocato la violazione viene evidenziata con un flag di valore 2.

exam_list.Hide(i+1,2);

Le regole, come già detto, vengono controllate in un altro ciclo. Qui si fa solo la riduzione del bound e il controllo sulle attività che violano vincoli.



online reference