(P) Teatteri¶

Alkukommentti ja palautteen kieli¶

Samoin kuin ensimmäisessä projektissa, tässäkin projektissa vaaditaan alkukommentti. Tällä kertaa alkukommenttia ei anneta valmiina, vaan sinun pitää kirjoittaa se itse. Mallia voit katsoa ensimmäisen projektin tehtävänannosta (4.5 (P) Tammi).

Palautteen kieli valitaan palautuslaatikossa (tämän sivun lopussa). Palautteen kielenä on oletuksena suomi, mutta voit vaihtaa sen, jos haluat assistenttien antaman palautteen englanniksi. Kielivalinta määräytyy sen perusteella, minkä kielivalinnan olet tehnyt viimeisimmän palautuksen palautuslaatikossa.

Jos teette parityötä, muistakaa lisätä molempien henkilökohtaiset tiedot.

Ohjelman käsittelemä tieto¶

Ajatellaan seuraavan kaltaista informaatiota näytelmistä eri teattereissa:

Helsinki
    KOM-teatteri
        Rikkaruoho
            Vilma Melasniemi 10
            Juho Milonoff    4
            Niko Saarela     none
        Nukkekoti/A doll's house
            Aleksi Holkko    30
            Niko Saarela     40
            Vilma Melasniemi 43
        The Pimpsons
            Lotta Kaihua     40
            Ria Kataja       none
    Suomen Komediateatteri
        Viimeinen illuusio
            Janne Kataja     28
            Kiti Kokkonen    17
            Joni Pakanen     23
            Katja Lappi      22
        Ilta pilalla
            Ria Kataja       34
            Kiti Kokkonen    5
Tampere
    Tampereen Teatteri
        Piaf
            Annuska Hannula  7
            Pia Piltz        34
            Arttu Ratinen    2
        Anastasia
            Pia Piltz        1
            Sinikka Sokka    4
            Elina Rintala    3
            Arttu Ratinen    none
        Klaani
            Matti Hakulinen  6
            Eeva Hakulinen   8
            Elina Rintala    7
            Tommi Raitolehto 2
    Tampereen Tyovaen Teatteri
        Saituri/Miser
            Samuli Muje      34
            Auvo Vihro       23
        Evita
            Maija Rissanen   2
            Lari Halme       3
Pori
    Porin Teatteri
        Evita
            Heidi Rantakeisu 7
            Maria Pere       none
        Idan pikajunan arvoitus/Murder on the Orient Express
            Janne Turkki     8
            Maria Palmu      none
            Maria Pere       none

Edellä listatun kaltainen tietomäärä voidaan esittää csv-tiedostona, jonka rivit ovat muotoa:

<paikkakunta>;<teatteri>;<näytelmä>;<näyttelijä>;<vapaiden_paikkojen_määrä>

jossa <vapaiden_paikkojen_määrä> voi olla positiivinen kokonaisluku tai literaalinen merkkijono “none”.

Voit olettaa, että <paikkakunta> koostuu vain yhdestä sanasta. Sen sijaan <teatteri>, <näytelmä> ja <näyttelijä> voivat koostua useista sanoista. Jos sanoja on useita, käyttäjä voi antaa ne lainausmerkkien sisällä, mikä näkyy myöhemmin tulevissa esimerkkiajoissa. (Tosin lainausmerkeistä ei tarvitse sen enempää välittää, koska koodinpohjassa on tätä varten toteutettu split-funktio.)

Voit myös olettaa, että näytelmässä ei ole useita samannimisiä näyttelijöitä.

Näytelmällä voi olla varsinaisen nimen lisäksi toinenkin nimi (alias). Useimmiten varsinainen nimi on näytelmän suomenkielinen nimi, ja alias on sen englanninkielinen vastine. Tällöin nämä kaksi nimeä on eroteltu kauttaviivalla ('/').

Yllä käytetty esimerkki näyttäisi syötetiedostoksi kuvattuna siis esimerkiksi seuraavalta:

Helsinki;KOM-teatteri;Rikkaruoho;Vilma Melasniemi;10
Tampere;Tampereen Teatteri;Piaf;Pia Piltz;34
Helsinki;KOM-teatteri;Rikkaruoho;Juho Milonoff;4
Pori;Porin Teatteri;Evita;Heidi Rantakeisu;7
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Kiti Kokkonen;17
Helsinki;KOM-teatteri;Rikkaruoho;Niko Saarela;none
Tampere;Tampereen Teatteri;Piaf;Annuska Hannula;7
Helsinki;KOM-teatteri;Nukkekoti/A doll's house;Niko Saarela;40
Tampere;Tampereen Teatteri;Anastasia;Sinikka Sokka;4
Helsinki;KOM-teatteri;The Pimpsons;Lotta Kaihua;40
Pori;Porin Teatteri;Idan pikajunan arvoitus/Murder on the Orient Express;Maria Palmu;none
Helsinki;KOM-teatteri;The Pimpsons;Ria Kataja;none
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Janne Kataja;28
Tampere;Tampereen Teatteri;Klaani;Matti Hakulinen;6
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Joni Pakanen;23
Pori;Porin Teatteri;Evita;Maria Pere;none
Helsinki;Suomen Komediateatteri;Viimeinen illuusio;Katja Lappi;22
Helsinki;Suomen Komediateatteri;Ilta pilalla;Ria Kataja;34
Tampere;Tampereen Teatteri;Klaani;Elina Rintala;7
Helsinki;Suomen Komediateatteri;Ilta pilalla;Kiti Kokkonen;5
Tampere;Tampereen Tyovaen Teatteri;Saituri/Miser;Samuli Muje;34
Tampere;Tampereen Teatteri;Piaf;Arttu Ratinen;2
Tampere;Tampereen Teatteri;Anastasia;Pia Piltz;1
Pori;Porin Teatteri;Idan pikajunan arvoitus/Murder on the Orient Express;Janne Turkki;8
Tampere;Tampereen Teatteri;Anastasia;Elina Rintala;3
Tampere;Tampereen Teatteri;Anastasia;Arttu Ratinen;none
Helsinki;KOM-teatteri;Nukkekoti/A doll's house;Aleksi Holkko;30
Tampere;Tampereen Teatteri;Klaani;Eeva Hakulinen;8
Pori;Porin Teatteri;Idan pikajunan arvoitus/Murder on the Orient Express;Maria Pere;none
Tampere;Tampereen Teatteri;Klaani;Tommi Raitolehto;2
Tampere;Tampereen Tyovaen Teatteri;Saituri/Miser;Auvo Vihro;23
Helsinki;KOM-teatteri;Nukkekoti/A doll's house;Vilma Melasniemi;43
Tampere;Tampereen Tyovaen Teatteri;Evita;Maija Rissanen;2
Tampere;Tampereen Tyovaen Teatteri;Evita;Lari Halme;3

Kenttiä on rivillä viisi kappaletta, ja mikään kenttä ei saa olla tyhjä tai muodostua pelkistä välilyöntimerkeistä. Viimeisen kentän on oltava positiivista kokonaislukua (int) esittävä merkkijono tai sana “none”. (Voit ajatella, että none tarkoittaa varausten määrää 0, mutta voit olettaa, että luku 0 ei esiinny syötetiedostossa, vaan nollan tilalla on aina teksti none.)

Huomaa, kuinka rivien ei tarvitse csv-tiedostossa olla missään erityisessä järjestyksessä. Syötetiedostossa ei myöskään käytetä skandinaavisia kirjaimia.

Vaikka vapaiden paikkojen määrä näkyykin aina näyttelijän nimen perässä, se on kuitenkin näytelmäkohtainen tieto. Viimeisin samaa näytelmää koskeva paikkatieto jää aina voimaan. Esimerkiksi näytelmässä Saituri (Miser) on ensin paikkatietona 34 (Samuli Mujeen kohdalla) ja myöhemmin 23 (Auvo Vihron kohdalla). Tällöin lopullinen vapaiden paikkojen määrä on 23.

Ohjelman toiminta¶

Kun ohjelma käynnistyy, se lukee käyttäjältä syötetiedoston nimen:

Input file: theatres.txt

Mikäli syötetiedostoa ei saa avattua luettavaksi, tulostetaan käyttäjälle teksti:

Error: input file cannot be opened

Tämän jälkeen ohjelman suoritus päättyy ilman mitään muita tulosteita paluuarvoon EXIT_FAILURE.

Mikäli syötetiedosto saadaan avattua, mutta tiedosto ei ole määritelmän mukainen, esimerkiksi kenttä puuttuu täysin tai kentästä puuttuu arvo, tulostetaan käyttäjälle alla näkyvä virheilmoitus ja lopetetaan ohjelman suoritus paluuarvoon EXIT_FAILURE. Jos esimerkiksi edellä esitetyssä syötetiedostossa rivillä 1 lukisikin:

Helsinki;KOM-teatteri;Rikkaruoho;10

tai:

Helsinki;KOM-teatteri;Rikkaruoho;;10

tai:

Helsinki;KOM-teatteri;Rikkaruoho;   ;10

niin ohjelma tulostaisi:

Error: empty field in line 1

Virheilmoitukseen tulostetaan siis myös rivinumero, joten syötetiedoston rivit pitää laskea.

Ohjelma jäsentelee tiedostosta lukemansa rivit ja tallentaa eri kirjastojen kirjatiedot sopivaan sisäiseen tietorakenteeseen. Tietorakenne on ohjelmoijan itsensä päätettävissä, kunhan se noudattaa kaikkia kohdassa Erityisvaatimukset asetettuja lisäehtoja.

Kun tiedosto on luettu, ohjelma aloittaa varsinaisen suorituksensa. Aina kun käyttäjältä odotetaan syötettä, tulostetaan rivin alkuun komentokehote the> (ja välilyönti):

the>

Tähän kehotteeseen ohjelman käyttäjä voi syöttää seuraavia käskyjä:

• quit - Ohjelman suoritus päätty paluuarvoon EXIT_SUCCESS ilman, että ohjelma tulostaa mitään.

• theatres - Tulostaa aakkosjärjestyksessä allekkain kaikki tunnetut teatterit. Esimerkiksi:

  the> theatres
  KOM-teatteri
  Porin Teatteri
  Suomen Komediateatteri
  Tampereen Teatteri
  Tampereen Tyovaen Teatteri
  the>
  

• plays - Tulostaa allekkain kaikki näytelmät aakkosjärjestyksessä. Vaikka sama näytelmä löytyisi useasta teatterista, näytelmän nimi tulostetaan vain kerran. Jos näytelmällä on alias, myös se tulostetaan seuraavasti (erottimena ***):

  the> plays
  Anastasia
  Evita
  Idan pikajunan arvoitus *** Murder on the Orient Express
  Ilta pilalla
  Klaani
  Nukkekoti *** A doll's house
  Piaf
  Rikkaruoho
  Saituri *** Miser
  The Pimpsons
  Viimeinen illuusio
  the>
  

• theatres_of_play <näytelmä> - Komento tulostaa teatterit, joissa annettua näytelmää esitetään. Teatterit tulostetaan niiden nimien mukaisessa aakkosjärjestyksessä:

  the> theatres_of_play "Ilta pilalla"
  Suomen Komediateatteri
  the> theatres_of_play Evita
  Porin Teatteri
  Tampereen Tyovaen Teatteri
  the>
  

  Esimerkissä näkyy lainausmerkkien käyttö, kun näytelmän nimi koostuu useammasta sanasta. Vaikka nimi koostuisi vain yhdestä sanasta, silloinkin voitaisiin käyttää lainausmerkkejä. Esimerkiksi komennot theatres_of_play Evita ja theatres_of_play "Evita" tuottavat saman tuloksen.

  Komennossa voi käyttää joko näytelmän varsinaista nimeä tai aliasta, mutta ei niiden yhdistelmää:

  the> theatres_of_play Saituri
  Tampereen Tyovaen Teatteri
  the> theatres_of_play Miser
  Tampereen Tyovaen Teatteri
  the> theatres_of_play Saituri/Miser
  Error: unknown play
  the>
  

  Näytelmää ei myöskään löydy sen nimen osalla, vaan nimi tai alias pitää antaa kokonaan. Virheilmoituksista kerrotaan enemmän osiossa Virhetilanteet.

• plays_in_theatre <teatteri> - Komento tulostaa annetun teatterin näytelmät niiden nimien mukaisessa aakkosjärjestyksessä:

  the> plays_in_theatre "Tampereen Teatteri"
  Anastasia
  Klaani
  Piaf
  the>
  

• plays_in_town <paikkakunta> - Komento tulostaa annetun paikkakunnan sellaiset näytelmät, joissa on paikkoja vapaana. Jos näytelmällä on alias, myös se tulostetaan (erottimena ---). Tulostuksessa käytetään ensin teatterin mukaista aakkosjärjestystä, ja lisäksi saman teatterin näytelmät tulostetaan näytelmän nimen mukaisessa aakkosjärjestyksessä Myös vapaiden paikkojen määrä tulostetaan:

  the> plays_in_town Helsinki
  KOM-teatteri : Nukkekoti --- A doll's house : 43
  Suomen Komediateatteri : Ilta pilalla : 5
  Suomen Komediateatteri : Viimeinen illuusio : 22
  the>
  

  Jos paikkakunnalla ei ole yhdessäkään näytelmässä vapaita paikkoja, tulostetaan ilmoitus:

  the> plays_in_town Pori
  No plays available
  the>
  

• players_in_play <näytelmä> [<teatteri>] - Komento tulostaa annetussa näytelmässä esiintyvät näyttelijät. Samannimisiä näytelmiä voi olla eri teattereissa, joten komennolle voidaan antaa toisena parametrina haluttu teatteri. Jos teatteri annetaan, tulostetaan vain kyseisestä teatterista löytyvän näytelmän näyttelijät. Jos teatteria ei anneta, annetun näytelmän näyttelijät tulostetaan kaikista teattereista, joista näytelmä löytyy. Joka tapauksessa komento tulostaa ensin teatterin nimen ja sitten näyttelijän nimen alla näkyvällä tavalla. Tulostus noudattaa ensin teatterin mukaista aakkosjärjestystä, ja saman teatterin näyttelijät tulostetaan etunimen mukaisessa aakkosjärjestyksessä. Esimerkiksi:

  the> players_in_play Evita "Tampereen Tyovaen Teatteri"
  Tampereen Tyovaen Teatteri : Lari Halme
  Tampereen Tyovaen Teatteri : Maija Rissanen
  the> players_in_play Evita "Porin Teatteri"
  Porin Teatteri : Heidi Rantakeisu
  Porin Teatteri : Maria Pere
  the> players_in_play Evita
  Porin Teatteri : Heidi Rantakeisu
  Porin Teatteri : Maria Pere
  Tampereen Tyovaen Teatteri : Lari Halme
  Tampereen Tyovaen Teatteri : Maija Rissanen
  the>
  

  Näytelmää voi etsiä joko varsinaisella nimellä tai aliaksella, samoin kuin komennossa theatres_of_play:

  the> players_in_play Saituri
  Tampereen Tyovaen Teatteri : Auvo Vihro
  Tampereen Tyovaen Teatteri : Samuli Muje
  the> players_in_play Miser
  Tampereen Tyovaen Teatteri : Auvo Vihro
  Tampereen Tyovaen Teatteri : Samuli Muje
  the> players_in_play Saituri/Miser
  Error: unknown play
  the>
  

Kun käyttäjän syöttämä komento on suoritettu, ohjelma tulostaa kehotteen uudelleen. Tätä jatketaan kunnes käyttäjä syöttää käskyn quit.

Virhetilanteet¶

Mikäli käyttäjän syöte on virheellinen, tulostetaan virheeseen liittyvä virheilmoitus, minkä jälkeen ohjelma palaa odottamaan käyttäjän syötettä. Ohjelman suoritus ei siis pääty käyttäjän virheelliseen syötteeseen.

Käyttäjän syöttäessä tuntemattoman komennon, tulostetaan virheilmoitus:

the> xx
Error: unknown command
the> xx yy
Error: unknown command
the>

Mikäli komennolle annetaan väärä määrä parametreja, tulostetaan virheilmoitus seuraavasti:

the> plays KOM-teatteri
Error: wrong number of parameters
the>

Komennoille theatres_of_play ja players_in_play annetaan parametrina näytelmän nimi. Jos annettua näytelmää ei löydy, tulostetaan virheilmoitus:

the> theatres_of_play xx
Error: unknown play
the> players_in_play xx
Error: unknown play
the> players_in_play xx "Porin Teatteri"
Error: unknown play
the>

Kuitenkin jos jälkimmäisen komennon (players_in_play) jälkimmäistä parametria (teatteria) ei löydy, tulostetaan virheilmoitus:

the> players_in_play xx yy
Error: unknown theatre
the> players_in_play Evita yy
Error: unknown theatre
the>

Toisin sanoen, jos vapaaehtoinen (optionaalinen) parametri annetaan, sen pitää olla jokin olemassa oleva teatteri. Tämä (optionaalisen parametrin mukanaolo ja oikeellisuus) tarkistetaan siis ensin. Vasta sitten tutkitaan ensimmäisen parametrin oikeellisuus.

Komento plays_in_theatre saa parametrinaan teatterin nimen ja komento plays_in_town paikkakunnan nimen. Jos näitä ei löydy, tulostetaan virheilmoitukset vastaavasti:

the> plays_in_theatre xx
Error: unknown theatre
the> plays_in_town xx
Error: unknown town
the>

Erityisvaatimukset¶

Seuraavia vaatimuksia on noudatettava, mikäli haluaa työstä hyväksytyn arvosanan:

• Syötetiedoston saa lukea vain kerran ohjelman suorituksen aikana.
  • Tästä syystä sinun pitää lukea tiedoston tiedot STL:n tietorakenteisiin. Sen jälkeen kaikki haut, lisäykset ja poistot pitää kohdistua valittuihin tietorakenteisiin (eikä siis syötetiedostoon).
• Minkä STL-tietorakenteen tai tietorakenteiden yhdistelmän valitsetkin työhösi, sinun on käytettävä ainakin yhtä map-rakennetta. Tämän map-rakenteen on oltava osana sitä rakennetta, johon tiedostosta luettu informaatio talletetaan myöhempiä hakuja varten.

Vihjeitä¶

• Muista, että oletuksena ohjelma käännetään build-hakemistoon. Testaamista varten kannattaa siirtää mahdolliset syötetiedostot tähän samaan hakemistoon.
• Voit käyttää syötetiedoston ja käyttäjän antamien syötteiden paloitteluun koodipohjan split-funktiota.
• Muistathan, missä järjestyksessä map- ja set-rakenteiden alkiot käydään iteraattorilla läpi.
• Kierrokselta 5 löytyy esimerkkejä STL-säiliöiden yhdistelemisestä (ks. 05/examples/).
• Kierrokselta 3 löytyy esimerkkejä luokkien käytöstä (ks. Plussa-materiaali ja viikkoharjoitukset).

Ohjelman toteuttaminen osissa¶

Ohjelman toteutus muodostuu pääpiirteiltään seuraavista osista:

• tietorakenteen valinta ja tiedoston lukeminen tietorakenteeseen
• mahdollisesti luokan tai luokkien toteuttaminen
• käyttöliittymä
• hakualgoritmit.

Mieti tarkasti, missä järjestyksessä nuo kannattaa toteuttaa, jotta voit toteuttaa ja testata ne yksi kerrallaan, ennen kuin siirryt seuraavaan vaiheeseen. Vähimmäisvaatimuksena versionhallinnan käyttämiselle on, että nämä 3-4 osaa on toteutettu omina committeinaan, mutta parempi tietenkin olisi että committeja olisi enemmän.

Yllä luetellut commitit saa jakaa useampaan osaan.

Arviointi¶

Jotta työ päätyisi assistenttien arvioitavaksi, sen pitää ensin läpäistä automaattitestit. Automaattitestit eivät hyväksy ohjelmaa, jonka kääntäminen tuottaa varoituksia. Jos saat automaattitesteistä 0 pistettä, myös lopullinen pistemääräsi on 0, eikä työ mene assistenttien arvioitavaksi.

Assistentti arvioi ja pisteyttää automaattitestit läpäisseistä (=1 p) sekä tehtävänannon erikoisvaatimukset täyttävistä töistä viimeisen määräajan puitteissa tehdyn commitin seuraavien arviointikriteerien mukaan:

• Ratkaisun yleisperiaate: 0-30 pistettä:
  • Tehtävän osaamistavoitteet on saavutettu.
  • Ohjelmakoodi on jaettu funktioita, luokkia ja/tai metodeita käyttäen loogisiksi kokonaisuuksiksi, jotka ovat sopivan pituisia.
  • Jos luokkia ja olioita on käytetty, ne on toteutettu olio-ohjelmoinnin periaatteita noudattaen (ks. 4-kierroksen Tyyliseikoista kohta Olio-ohjelmointi).
  • Tietorakenne ei sisällä toisteista eikä turhaa tietoa. Valittuja tietorakenteita on käytetty järkevästi.
  • Ohjelmakoodi ei sisällä turhaa toisteisuutta eikä muutakaan turhaa.
  • Ohjelmakoodi ei sisällä tarpeettomia rajoitteita tai oletuksia tai muita väkinäisiä ratkaisuita.
  • Ohjelmarakenteet on toteutettu helposti ymmärrettäviksi.
  • Ohjelmakoodissa ei ole käytetty globaaleja muuttujia (globaalit const-vakiot ovat OK).
  • Ohjelman toimintaa ei lopeteta exit-funktiota käyttäen.
• Ohjelmointityyli: 0-10 pistettä:
  • Muuttujat ja funktiot nimetty selkeästi ja kuvaavasti. Nimeämisessä on käytetty vain yhtä kieltä, ei esim. suomea ja englantia sekaisin.
  • Ohjelmassa on käytetty nimettyjä vakioita taikalukujen sijasta.
  • Ohjelmakoodi on asemoitu siististi.
  • Koodirivien pituus on enintään 80 merkkiä.
  • Jokaisen tiedoston alussa on kommentti, josta käy ilmi tiedoston tarkoitus, työn tekijä(t) ja muut tarvittavat tiedot. (ks. 1-projektin tehtävänanto kierrokselta 4).
  • Jokaisen funktion/metodin alussa (otsikkotiedostossa jos sellainen on) on kommentti, joka kuvaa sen toiminnan, paluuarvon ja parametrit.
  • Kommentteja on muutenkin tarpeellisissa kohdissa.
  • Kommentit liittyvät toteutettuun ohjelmaan eivätkä johonkin sen vanhempaan versioon.
  • Kaikki kommentit on kirjoitettu samalla kielellä (fi/en), mutta kommentoinnissa saa käyttää eri kieltä kuin muuttujien ym. nimissä.
  • Kaikki muuttujat on alustettu.
  • Kääntäjä ei anna koodia käännettäessä varoituksia.
• Versionhallinnan käyttö: 0-10 pistettä:
  • Committeja on riittävä määrä.
  • Commit-viestien sisältö on selkeä ja kuvaava.