1// Copyright (C) 2024 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
3
4#include "qhelpsearchenginecore.h"
5#include "qhelpenginecore.h"
6
7#include "qhelpsearchindexreader_p.h"
8#include "qhelpsearchindexwriter_p.h"
9
10#include <QtCore/private/qobject_p.h>
11#include <QtCore/qdir.h>
12#include <QtCore/qfile.h>
13#include <QtCore/qfileinfo.h>
14#include <QtCore/qpointer.h>
15#include <QtCore/qtimer.h>
16
17QT_BEGIN_NAMESPACE
18
19using namespace fulltextsearch;
20using namespace Qt::StringLiterals;
21
22class QHelpSearchEngineCorePrivate : public QObjectPrivate
23{
24 Q_DECLARE_PUBLIC(QHelpSearchEngineCore)
25
26public:
27 QString indexFilesFolder() const
28 {
29 QString indexFilesFolder = ".fulltextsearch"_L1;
30 if (m_helpEngine && !m_helpEngine->collectionFile().isEmpty()) {
31 const QFileInfo fi(m_helpEngine->collectionFile());
32 indexFilesFolder = fi.absolutePath() + QDir::separator() + u'.'
33 + fi.fileName().left(n: fi.fileName().lastIndexOf(s: ".qhc"_L1));
34 }
35 return indexFilesFolder;
36 }
37
38 void updateIndex(bool reindex)
39 {
40 Q_Q(QHelpSearchEngineCore);
41 if (m_helpEngine.isNull())
42 return;
43
44 if (!QFile::exists(fileName: QFileInfo(m_helpEngine->collectionFile()).path()))
45 return;
46
47 if (!m_indexWriter) {
48 m_indexWriter.reset(p: new QHelpSearchIndexWriter);
49
50 QObject::connect(sender: m_indexWriter.get(), signal: &QHelpSearchIndexWriter::indexingStarted,
51 context: q, slot: &QHelpSearchEngineCore::indexingStarted);
52 QObject::connect(sender: m_indexWriter.get(), signal: &QHelpSearchIndexWriter::indexingFinished,
53 context: q, slot: &QHelpSearchEngineCore::indexingFinished);
54 }
55
56 m_indexWriter->cancelIndexing();
57 m_indexWriter->updateIndex(collectionFile: m_helpEngine->collectionFile(), indexFilesFolder: indexFilesFolder(), reindex);
58 }
59
60 void search(const QString &searchInput)
61 {
62 Q_Q(QHelpSearchEngineCore);
63 if (m_helpEngine.isNull())
64 return;
65
66 if (!QFile::exists(fileName: QFileInfo(m_helpEngine->collectionFile()).path()))
67 return;
68
69 if (!m_indexReader) {
70 m_indexReader.reset(p: new QHelpSearchIndexReader);
71 QObject::connect(sender: m_indexReader.get(), signal: &QHelpSearchIndexReader::searchingStarted,
72 context: q, slot: &QHelpSearchEngineCore::searchingStarted);
73 QObject::connect(sender: m_indexReader.get(), signal: &QHelpSearchIndexReader::searchingFinished,
74 context: q, slot: &QHelpSearchEngineCore::searchingFinished);
75 }
76
77 m_searchInput = searchInput;
78 m_indexReader->cancelSearching();
79 m_indexReader->search(collectionFile: m_helpEngine->collectionFile(), indexFilesFolder: indexFilesFolder(), searchInput,
80 usesFilterEngine: m_helpEngine->usesFilterEngine());
81 }
82
83 bool m_isIndexingScheduled = false;
84
85 std::unique_ptr<QHelpSearchIndexReader> m_indexReader;
86 std::unique_ptr<QHelpSearchIndexWriter> m_indexWriter;
87
88 QPointer<QHelpEngineCore> m_helpEngine;
89 QString m_searchInput;
90};
91
92/*!
93 \class QHelpSearchEngineCore
94 \since 6.8
95 \inmodule QtHelp
96 \brief The QHelpSearchEngineCore class provides access to index and
97 search documentation.
98
99 Before the search engine can be used, one has to instantiate at least a
100 QHelpEngineCore object that needs to be passed to the search engines constructor.
101 This is required as the search engine needs to be connected to the help
102 engines setupFinished() signal to know when it can start to index documentation.
103
104 After starting the indexing process the signal indexingStarted() is emitted and
105 on the end of the indexing process the indexingFinished() is emitted. To stop
106 the indexing one can call cancelIndexing().
107
108 When the indexing process has finished, the search engine can be used to
109 search through the index for a given term using the search() function. When
110 the search input is passed to the search engine, the searchingStarted()
111 signal is emitted. When the search finishes, the searchingFinished() signal
112 is emitted. The search process can be stopped by calling cancelSearching().
113
114 If the search succeeds, searchingFinished() is called with the search result
115 count to fetch the search results from the search engine. Calling the
116 searchResults() function with a range returns a list of QHelpSearchResult
117 objects within the range. The results consist of the document title and URL,
118 as well as a snippet from the document that contains the best match for the
119 search input.
120*/
121
122/*!
123 \fn void QHelpSearchEngineCore::indexingStarted()
124
125 This signal is emitted when indexing process is started.
126*/
127
128/*!
129 \fn void QHelpSearchEngineCore::indexingFinished()
130
131 This signal is emitted when the indexing process is complete.
132*/
133
134/*!
135 \fn void QHelpSearchEngineCore::searchingStarted()
136
137 This signal is emitted when the search process is started.
138*/
139
140/*!
141 \fn void QHelpSearchEngineCore::searchingFinished()
142
143 This signal is emitted when the search process is complete.
144*/
145
146/*!
147 Constructs a new search engine with the given \a parent. The search engine
148 uses the given \a helpEngine to access the documentation that needs to be indexed.
149 The QHelpEngineCore's setupFinished() signal is automatically connected to the
150 QHelpSearchEngineCore's indexing function, so that new documentation will
151 be indexed after the signal is emitted.
152*/
153QHelpSearchEngineCore::QHelpSearchEngineCore(QHelpEngineCore *helpEngine, QObject *parent)
154 : QObject(*new QHelpSearchEngineCorePrivate, parent)
155{
156 Q_D(QHelpSearchEngineCore);
157 d->m_helpEngine = helpEngine;
158 connect(sender: helpEngine, signal: &QHelpEngineCore::setupFinished,
159 context: this, slot: &QHelpSearchEngineCore::scheduleIndexDocumentation);
160}
161
162/*!
163 Destructs the search engine.
164*/
165QHelpSearchEngineCore::~QHelpSearchEngineCore() = default;
166
167/*!
168 Returns the number of results the search engine found.
169*/
170int QHelpSearchEngineCore::searchResultCount() const
171{
172 Q_D(const QHelpSearchEngineCore);
173 return d->m_indexReader ? d->m_indexReader->searchResultCount() : 0;;
174}
175
176/*!
177 Returns a list of search results within the range from the index
178 specified by \a start to the index specified by \a end.
179*/
180QList<QHelpSearchResult> QHelpSearchEngineCore::searchResults(int start, int end) const
181{
182 Q_D(const QHelpSearchEngineCore);
183 return d->m_indexReader ? d->m_indexReader->searchResults(start, end)
184 : QList<QHelpSearchResult>();
185}
186
187/*!
188 Returns the phrase that was last searched for.
189*/
190QString QHelpSearchEngineCore::searchInput() const
191{
192 Q_D(const QHelpSearchEngineCore);
193 return d->m_searchInput;
194}
195
196/*!
197 Forces the search engine to reindex all documentation files.
198*/
199void QHelpSearchEngineCore::reindexDocumentation()
200{
201 Q_D(QHelpSearchEngineCore);
202 d->updateIndex(reindex: true);
203}
204
205/*!
206 Stops the indexing process.
207*/
208void QHelpSearchEngineCore::cancelIndexing()
209{
210 Q_D(QHelpSearchEngineCore);
211 if (d->m_indexWriter)
212 d->m_indexWriter->cancelIndexing();
213}
214
215/*!
216 Stops the search process.
217*/
218void QHelpSearchEngineCore::cancelSearching()
219{
220 Q_D(QHelpSearchEngineCore);
221 if (d->m_indexReader)
222 d->m_indexReader->cancelSearching();
223}
224
225/*!
226 Starts the search process using the given search phrase \a searchInput.
227
228 The phrase may consist of several words. By default, the search engine returns
229 the list of documents that contain all the specified words.
230 The phrase may contain any combination of the logical operators AND, OR, and
231 NOT. The operator must be written in all capital letters, otherwise it will
232 be considered a part of the search phrase.
233
234 If double quotation marks are used to group the words,
235 the search engine will search for an exact match of the quoted phrase.
236
237 For more information about the text query syntax,
238 see \l {https://sqlite.org/fts5.html#full_text_query_syntax}
239 {SQLite FTS5 Extension}.
240*/
241void QHelpSearchEngineCore::search(const QString &searchInput)
242{
243 Q_D(QHelpSearchEngineCore);
244 d->search(searchInput);
245}
246
247/*!
248 \internal
249*/
250void QHelpSearchEngineCore::scheduleIndexDocumentation()
251{
252 Q_D(QHelpSearchEngineCore);
253 if (d->m_isIndexingScheduled)
254 return;
255
256 d->m_isIndexingScheduled = true;
257 QTimer::singleShot(interval: 0, receiver: this, slot: [this] {
258 Q_D(QHelpSearchEngineCore);
259 d->m_isIndexingScheduled = false;
260 d->updateIndex(reindex: false);
261 });
262}
263
264QT_END_NAMESPACE
265

source code of qttools/src/assistant/help/qhelpsearchenginecore.cpp