1 /*
2 * read a KEduVocDocument from a KVTML2 file
3 * SPDX-FileCopyrightText: 2007 Jeremy Whiting <jpwhiting@kde.org>
4 * SPDX-FileCopyrightText: 2007-2008 Frederik Gladhorn <frederik.gladhorn@kdemail.net>
5 * SPDX-License-Identifier: GPL-2.0-or-later
6 */
7 
8 #ifndef KEDUVOCKVTML2READER_H
9 #define KEDUVOCKVTML2READER_H
10 
11 #include <QDomDocument>
12 #include <QMap>
13 
14 #include "keduvocexpression.h"
15 #include "keduvocpersonalpronoun.h"
16 #include "keduvocarticle.h"
17 #include "keduvocmultiplechoice.h"
18 #include "keduvocdocument.h"
19 #include "readerbase.h"
20 
21 class QIODevice;
22 class KEduVocDocument;
23 class KEduVocWordType;
24 
25 /**
26 * @brief class to read kvtml2 data files into keduvocdocument
27 * @author Jeremy Whiting
28 */
29 class KEduVocKvtml2Reader : public QObject, public ReaderBase
30 {
31     Q_OBJECT
32 public:
33     /** constructor */
34     explicit KEduVocKvtml2Reader( QIODevice & file );
35     /**destructor*/
~KEduVocKvtml2Reader()36     ~KEduVocKvtml2Reader()override {};
37 
38 
39     /** @brief Can this reader parse this file
40      *
41      Read a small portion of the header of the file
42      and decide if it is a suitable type.
43      @return true if parsable
44      */
45     bool isParsable() Q_DECL_OVERRIDE;
46 
47     /** @brief returns the KEduVocDocument::FileType that this reader handles
48         @return KEduVocDocument::FileType handled
49      */
50     KEduVocDocument::FileType fileTypeHandled() Q_DECL_OVERRIDE;
51 
52     /**  @brief Parse file and write into doc
53      @param doc to be written
54      @return error status of the read.*/
55     KEduVocDocument::ErrorCode read(KEduVocDocument & doc ) Q_DECL_OVERRIDE;
56 
57     /** an error message.
58         @return the error message
59     */
errorMessage()60     QString errorMessage() const Q_DECL_OVERRIDE
61     {
62         return m_errorMessage;
63     }
64 
65 private:
66     /** read information entries
67      * @param informationElement QDomElement information
68      */
69     bool readInformation( QDomElement &informationElement );
70 
71     /** read group elements: identifiers, entries, types, usages, lessons */
72     bool readGroups( QDomElement &domElementParent );
73 
74     /** read an identifier
75      * @param identifierElement QDomElement for the identifier to read
76      */
77     bool readIdentifier( QDomElement &identifierElement );
78 
79     /** read an identifiers articles
80      * @param articleElement QDomElement for the article group
81      * @param identifierNum number of the identifier this article is inside of
82      */
83     bool readArticle( QDomElement &articleElement, int identifierNum );
84 
85     bool readPersonalPronoun( QDomElement &conjugElement, KEduVocPersonalPronoun &pronoun );
86 
87     bool readPersonalPronounChild(QDomElement & personElement, KEduVocPersonalPronoun &pronoun, KEduVocWordFlags flags);
88 
89     /** read the types
90      * @param typesElement QDomElement for the types group
91      */
92     bool readWordType( KEduVocWordType* parentContainer, QDomElement &typesElement );
93 
94     /**
95      * Read a leitner box container.
96      * This is a grading system where the vocabulary are kept in boxes and promoted/demoted during the learning.
97      * Be aware that leitner boxes are a list only and no sub boxes will ever be read or written.
98      * While reusing the lesson class is quite easy for this a proper subclass of KEduVocContainer would be the better solution.
99      * @param parentContainer the parent to append the new leitner container to
100      * @param leitnerElement the element in the dom
101      * @return success
102      */
103     bool readLeitner( KEduVocLeitnerBox* parentContainer, QDomElement &leitnerElement );
104 
105     /**
106      * Read all <container> tags within a word type definition.
107      * @param parentContainer
108      * @param lessonElement
109      * @return
110      */
111     bool readChildWordTypes( KEduVocWordType* parentContainer, QDomElement &lessonElement );
112 
113     /** read the tenses
114      * @param tensesElement QDomElement for the tenses group
115      */
116     QStringList readTenses( QDomElement &tensesElement );
117 
118     /** read the usages
119      * @param usagesElement QDomElement for the usages group
120      */
121     bool readUsages( QDomElement &usagesElement );
122 
123     /** read an entry
124      * @param entryElement QDomElement for the entry to read
125      */
126     bool readEntry( QDomElement &entryElement );
127 
128     /** read a translation
129      * @param translationElement QDomElement for the translation to read
130      */
131     bool readTranslation( QDomElement &translationElement, KEduVocExpression *expr, int index );
132 
133     /** read a comparison
134      * @param comparisonElement comparison group element
135      * @param comp comparison object to read into
136      */
137     bool readComparison( QDomElement &comparisonElement, KEduVocTranslation *translation );
138 
139     /** read a multiple choice group
140      * @param multipleChoiceElement element to read from
141      * @param mc KEduVocMultipleChoice object to read to
142      */
143     bool readMultipleChoice( QDomElement &multipleChoiceElement, KEduVocTranslation* translation );
144 
145     /**
146      * Read <lesson> tags.
147      * @param parentLesson
148      * @param lessonElement
149      * @return
150      */
151     bool readChildLessons( KEduVocLesson* parentLesson, QDomElement &lessonElement );
152 
153     /** read a lesson, and append it to the document
154      * @param lessonElement element to read from
155      */
156     bool readLesson( KEduVocLesson* parentLesson, QDomElement &lessonElement );
157 
158     bool readSynonymsAntonymsFalseFriends( QDomElement &rootElement );
159 
160     /** pre-opened QIODevice to read from */
161     QIODevice *m_inputFile;
162 
163     /** KEduVocDocument to read to */
164     KEduVocDocument *m_doc;
165 
166     /** because we read the entries first, we store them here temporarily.
167      * later we read the lessons and put the entries there based on the key (their id) */
168     QMap<int, KEduVocExpression*> m_allEntries;
169 
170     /** error message */
171     QString m_errorMessage;
172 };
173 
174 #endif
175