Commit fb824677 authored by Friedemann Kleint's avatar Friedemann Kleint

Documentation: Add Core/Mime classes.

parent 4114a218
......@@ -96,17 +96,14 @@ enum {
TextMatchPriority
};
/* Parse sth like (<mime-info> being optional):
*\code
?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<!-- Mime types must match the desktop file associations -->
<mime-type type="application/vnd.nokia.qt.qmakeprofile">
<comment xml:lang="en">Qt qmake Profile</comment>
<glob pattern="*.pro" weight="50"/>
</mime-type>
</mime-info>
*\endcode
/*!
\class Core::IMagicMatcher
\brief Interface for a Mime type magic matcher (examinig file contents).
\sa Core::MimeType, Core::MimeDatabase, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
namespace Core {
......@@ -115,10 +112,18 @@ typedef QSharedPointer<MagicRuleMatcher> MagicRuleMatcherPtr;
namespace Internal {
// FileMatchContext: Passed on to the mimetypes from the database
// when looking for a file match. It exists to enable reading the file
// contents "on demand" (as opposed to each mime type trying to open
// and read while checking).
/*!
\class Core::Internal::FileMatchContext
\brief Context passed on to the mime types when looking for a file match.
It exists to enable reading the file contents "on demand"
(as opposed to each mime type trying to open and read while checking).
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
class FileMatchContext {
Q_DISABLE_COPY(FileMatchContext)
......@@ -170,7 +175,15 @@ QByteArray FileMatchContext::data()
return m_data;
}
// The binary fallback matcher for "application/octet-stream".
/*!
\class Core::Internal::BinaryMatcher
\brief The binary fallback matcher for mime type "application/octet-stream".
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
class BinaryMatcher : public IMagicMatcher {
Q_DISABLE_COPY(BinaryMatcher)
public:
......@@ -179,8 +192,18 @@ public:
virtual int priority() const { return BinaryMatchPriority; }
};
// A heuristic text file matcher: If the data do not contain any character
// below tab (9), detect as text.
/*!
\class Core::Internal::HeuristicTextMagicMatcher
\brief Heuristic text file matcher for mime types.
If the data do not contain any character below tab (9), detect as text.
Additionally, check on UTF16 byte order markers.
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
class HeuristicTextMagicMatcher : public IMagicMatcher {
Q_DISABLE_COPY(HeuristicTextMagicMatcher)
public:
......@@ -214,7 +237,20 @@ bool HeuristicTextMagicMatcher::matches(const QByteArray &data) const
} // namespace Internal
// MagicRule
/*!
\class Core::MagicRule
\brief Base class for standard Magic match rules based on contents
and offset specification.
Stores the offset and provides conversion helpers.
Base class for implementations for "string" and "byte".
(Others like little16, big16, etc. can be created whenever there is a need.)
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
const QChar MagicRule::kColon(QLatin1Char(':'));
MagicRule::MagicRule(int startPos, int endPos) : m_startPos(startPos), m_endPos(endPos)
......@@ -247,6 +283,15 @@ QPair<int, int> MagicRule::fromOffset(const QString &offset)
return qMakePair(startEnd.at(0).toInt(), startEnd.at(1).toInt());
}
/*!
\class Core::MagicStringRule
\brief Match on a string.
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
const QString MagicStringRule::kMatchType("string");
MagicStringRule::MagicStringRule(const QString &s, int startPos, int endPos) :
......@@ -284,6 +329,20 @@ bool MagicStringRule::matches(const QByteArray &data) const
return rc;
}
/*!
\class Core::MagicByteRule
\brief Match on a sequence of binary data.
Format:
\code
\0x7f\0x45\0x4c\0x46
\endcode
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
const QString MagicByteRule::kMatchType(QLatin1String("byte"));
MagicByteRule::MagicByteRule(const QString &s, int startPos, int endPos) :
......@@ -352,7 +411,18 @@ bool MagicByteRule::matches(const QByteArray &data) const
return false;
}
// List matcher
/*!
\class Core::MagicRuleMatcher
\brief A Magic matcher that checks a number of rules based on operator "or".
It is used for rules parsed from XML files.
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
MagicRuleMatcher::MagicRuleMatcher() :
m_priority(65535)
{
......@@ -406,7 +476,15 @@ IMagicMatcher::IMagicMatcherList MagicRuleMatcher::createMatchers(
return matchers;
}
// GlobPattern
/*!
\class Core::GlobPattern
\brief Glob pattern for file names for mime type matching.
\sa Core::MimeType, Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
MimeGlobPattern::MimeGlobPattern(const QRegExp &regExp, unsigned weight) :
m_regExp(regExp), m_weight(weight)
{
......@@ -426,7 +504,38 @@ unsigned MimeGlobPattern::weight() const
return m_weight;
}
// ---------- MimeTypeData
/*!
\class Core::MimeType
\brief Mime type data used in Qt Creator.
Contains most information from standard mime type XML database files.
Currently, magic of types "string", "bytes" is supported. In addition,
C++ classes, derived from Core::IMagicMatcher can be added to check
on contents.
In addition, the class provides a list of suffixes and a concept of the
'preferred suffix' (derived from glob patterns). This is used for example
to be able to configure the suffix used for C++-files in Qt Creator.
Mime XML looks like:
\code
<?xml version="1.0" encoding="UTF-8"?>
<mime-info xmlns="http://www.freedesktop.org/standards/shared-mime-info">
<!-- Mime types must match the desktop file associations -->
<mime-type type="application/vnd.nokia.qt.qmakeprofile">
<comment xml:lang="en">Qt qmake Profile</comment>
<glob pattern="*.pro" weight="50"/>
</mime-type>
</mime-info>
\endcode
\sa Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
class MimeTypeData : public QSharedData {
public:
typedef QHash<QString,QString> LocaleHash;
......@@ -796,8 +905,17 @@ QDebug operator<<(QDebug d, const MimeType &mt)
namespace Internal {
// MimeDatabase helpers: Generic parser for a sequence of <mime-type>.
// Calls abstract handler function process for MimeType it finds.
/*!
\class Core::Internal::BaseMimeTypeParser
\brief Generic parser for a sequence of <mime-type>.
Calls abstract handler function process for MimeType it finds.
\sa Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::MimeTypeParser
*/
class BaseMimeTypeParser {
Q_DISABLE_COPY(BaseMimeTypeParser)
public:
......@@ -1059,28 +1177,50 @@ MimeMapEntry::MimeMapEntry(const MimeType &t, int aLevel) :
{
}
/* MimeDatabasePrivate: Requirements for storage:
* - Must be robust in case of incomplete hierachies, dangling entries
* - Plugins will not load and register their mime types in order
* of inheritance.
* - Multiple inheritance (several subClassesOf) can occur
* - Provide quick lookup by name
* - Provide quick lookup by file type.
* This basically rules out some pointer-based tree, so the structure chosen
* is:
* - An alias map QString->QString for mapping aliases to types
* - A Map QString->MimeMapEntry for the types (MimeMapEntry being a pair of
* MimeType and (hierarchy) level.
* - A map QString->QString representing parent->child relations (enabling
* recursing over children)
* Using strings avoids dangling pointers.
* The hierarchy level is used for mapping by file types. When findByFile()
* is first called after addMimeType() it recurses over the hierarchy and sets
* the hierarchy level of the entries accordingly (0 toplevel, 1 first
* order...). It then does several passes over the type map, checking the
* globs for maxLevel, maxLevel-1....until it finds a match (idea being to
* to check the most specific types first). Starting a recursion from the
* leaves is not suitable since it will hit parent nodes several times. */
/*!
\class Core::MimeDatabase
\brief Mime data base to which the plugins can add the mime types they handle.
The class is protected by a QMutex and can therefore be accessed by threads.
A good testcase is to run it over \c '/usr/share/mime/<*>/<*>.xml' on Linux.
When adding a "text/plain" to it, the mimetype will receive a magic matcher
that checks for text files that do not match the globs by heuristics.
\section1 Design Considerations
Storage requirements:
\list
\o Must be robust in case of incomplete hierarchies, dangling entries
\o Plugins will not load and register their mime types in order of inheritance.
\o Multiple inheritance (several subClassesOf) can occur
\o Provide quick lookup by name
\o Provide quick lookup by file type.
\endlist
This basically rules out some pointer-based tree, so the structure chosen is:
\list
\o An alias map QString->QString for mapping aliases to types
\o A Map QString->MimeMapEntry for the types (MimeMapEntry being a pair of
MimeType and (hierarchy) level.
\o A map QString->QString representing parent->child relations (enabling
recursing over children)
\o Using strings avoids dangling pointers.
\endlist
The hierarchy level is used for mapping by file types. When findByFile()
is first called after addMimeType() it recurses over the hierarchy and sets
the hierarchy level of the entries accordingly (0 toplevel, 1 first
order...). It then does several passes over the type map, checking the
globs for maxLevel, maxLevel-1....until it finds a match (idea being to
to check the most specific types first). Starting a recursion from the
leaves is not suitable since it will hit parent nodes several times.
\sa Core::MimeType, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::BaseMimeTypeParser, Core::Internal::MimeTypeParser
*/
class MimeDatabasePrivate
{
......@@ -1155,6 +1295,17 @@ MimeDatabasePrivate::MimeDatabasePrivate() :
kModifiedMimeTypesPath = ICore::instance()->userResourcePath() + QLatin1String("/mimetypes/");
}
/*!
\class Core::Internal::MimeTypeParser
\brief Mime type parser
Populates Core::MimeDataBase
\sa Core::MimeDatabase, Core::IMagicMatcher, Core::MagicRuleMatcher, Core::MagicRule, Core::MagicStringRule, Core::MagicByteRule, Core::GlobPattern
\sa Core::Internal::FileMatchContext, Core::Internal::BinaryMatcher, Core::Internal::HeuristicTextMagicMatcher
\sa Core::Internal::MimeTypeParser
*/
namespace Internal {
// Parser that builds MimeDB hierarchy by adding to MimeDatabasePrivate
class MimeTypeParser : public BaseMimeTypeParser {
......@@ -1637,7 +1788,6 @@ void MimeDatabasePrivate::debug(QTextStream &str) const
str << "<MimeDatabase\n";
}
// --------------- MimeDatabase
MimeDatabase::MimeDatabase() :
m_d(new MimeDatabasePrivate)
{
......
......@@ -45,9 +45,7 @@
QT_BEGIN_NAMESPACE
class QIODevice;
class QRegExp;
class QDebug;
class QFileInfo;
QT_END_NAMESPACE
namespace Core {
......@@ -60,7 +58,6 @@ namespace Internal {
class FileMatchContext;
}
/* Magic (file contents) matcher interface. */
class CORE_EXPORT IMagicMatcher
{
Q_DISABLE_COPY(IMagicMatcher)
......@@ -77,9 +74,6 @@ public:
virtual ~IMagicMatcher() {}
};
/* Utility class: A standard Magic match rule based on contents. Currently there are
* implementations for "string" and "byte". (Others like little16, big16, etc. can be
* created whenever there is a need.) */
class CORE_EXPORT MagicRule
{
Q_DISABLE_COPY(MagicRule)
......@@ -139,8 +133,6 @@ private:
QList<int> m_bytes;
};
/* Utility class: A Magic matcher that checks a number of rules based on
* operator "or". It is used for rules parsed from XML files. */
class CORE_EXPORT MagicRuleMatcher : public IMagicMatcher
{
Q_DISABLE_COPY(MagicRuleMatcher)
......@@ -184,15 +176,6 @@ private:
int m_weight;
};
/* Mime type data used in Qt Creator. Contains most information from
* standard mime type XML database files.
* Omissions:
* - Only magic of type "string" is supported. In addition, C++ classes
* derived from IMagicMatcher can be added to check on contents
* - acronyms, language-specific comments
* Extensions:
* - List of suffixes and preferred suffix (derived from glob patterns).
*/
class CORE_EXPORT MimeType
{
public:
......@@ -268,12 +251,6 @@ private:
QSharedDataPointer<MimeTypeData> m_d;
};
/* A Mime data base to which the plugins can add the mime types they handle.
* When adding a "text/plain" to it, the mimetype will receive a magic matcher
* that checks for text files that do not match the globs by heuristics.
* The class is protected by a QMutex and can therefore be accessed by threads.
* A good testcase is to run it over '/usr/share/mime/<*>/<*>.xml' on Linux. */
class CORE_EXPORT MimeDatabase
{
Q_DISABLE_COPY(MimeDatabase)
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment