as-utils

as-utils — Helper functions that are used inside libappstream-glib

Stability Level

Stable, unless otherwise indicated

Synopsis

#include <appstream-glib.h>

enum                AsUtilsError;
#define             AS_UTILS_ERROR
enum                AsUtilsFindIconFlag;
enum                AsUtilsLocation;
enum                AsMarkupConvertFormat;
gchar *             as_markup_convert_simple            (const gchar *markup,
                                                         GError **error);
gchar *             as_markup_convert                   (const gchar *markup,
                                                         AsMarkupConvertFormat format,
                                                         GError **error);
gchar **            as_markup_strsplit_words            (const gchar *text,
                                                         guint line_len);
GQuark              as_utils_error_quark                (void);
gboolean            as_utils_is_stock_icon_name         (const gchar *name);
gboolean            as_utils_is_spdx_license_id         (const gchar *license_id);
gboolean            as_utils_is_spdx_license            (const gchar *license);
gboolean            as_utils_is_environment_id          (const gchar *environment_id);
gboolean            as_utils_is_category_id             (const gchar *category_id);
gboolean            as_utils_is_blacklisted_id          (const gchar *desktop_id);
gchar **            as_utils_spdx_license_tokenize      (const gchar *license);
gchar *             as_utils_spdx_license_detokenize    (gchar **license_tokens);
gchar *             as_utils_find_icon_filename         (const gchar *destdir,
                                                         const gchar *search,
                                                         GError **error);
gchar *             as_utils_find_icon_filename_full    (const gchar *destdir,
                                                         const gchar *search,
                                                         AsUtilsFindIconFlag flags,
                                                         GError **error);
gboolean            as_utils_install_filename           (AsUtilsLocation location,
                                                         const gchar *filename,
                                                         const gchar *origin,
                                                         const gchar *destdir,
                                                         GError **error);
gboolean            as_utils_search_token_valid         (const gchar *token);
gchar **            as_utils_search_tokenize            (const gchar *search);
gint                as_utils_vercmp                     (const gchar *version_a,
                                                         const gchar *version_b);
gboolean            as_utils_guid_is_valid              (const gchar *guid);
gchar *             as_utils_guid_from_string           (const gchar *str);

Description

These functions are used internally to libappstream-glib, and some may be useful to user-applications.

Details

enum AsUtilsError

typedef enum {
	AS_UTILS_ERROR_FAILED,
	AS_UTILS_ERROR_INVALID_TYPE,
} AsUtilsError;

The error type.

AS_UTILS_ERROR_FAILED

Generic failure

AS_UTILS_ERROR_INVALID_TYPE

Invalid type

AS_UTILS_ERROR

#define AS_UTILS_ERROR				as_utils_error_quark ()

enum AsUtilsFindIconFlag

typedef enum {
	AS_UTILS_FIND_ICON_NONE			= 0,
	AS_UTILS_FIND_ICON_HI_DPI		= 1 << 0,
} AsUtilsFindIconFlag;

The flags used when finding icons.

AS_UTILS_FIND_ICON_NONE

No flags set

AS_UTILS_FIND_ICON_HI_DPI

Prefer a HiDPI icon

enum AsUtilsLocation

typedef enum {
	AS_UTILS_LOCATION_SHARED,
	AS_UTILS_LOCATION_CACHE,
	AS_UTILS_LOCATION_USER,
} AsUtilsLocation;

The flags used when installing and removing metadata files.

AS_UTILS_LOCATION_SHARED

Installed by the vendor, shared

AS_UTILS_LOCATION_CACHE

Installed as metadata, shared

AS_UTILS_LOCATION_USER

Installed by the user

enum AsMarkupConvertFormat

typedef enum {
	AS_MARKUP_CONVERT_FORMAT_SIMPLE,
	AS_MARKUP_CONVERT_FORMAT_MARKDOWN,
} AsMarkupConvertFormat;

The output format used when converting AppStream descriptions.

AS_MARKUP_CONVERT_FORMAT_SIMPLE

UTF-8 text

AS_MARKUP_CONVERT_FORMAT_MARKDOWN

Markdown format

as_markup_convert_simple ()

gchar *             as_markup_convert_simple            (const gchar *markup,
                                                         GError **error);

Converts an XML description into a printable form.

markup :

the text to copy.

error :

A GError or NULL

Returns :

a newly allocated NULL terminated string. [transfer full]

Since 0.1.0


as_markup_convert ()

gchar *             as_markup_convert                   (const gchar *markup,
                                                         AsMarkupConvertFormat format,
                                                         GError **error);

Converts an XML description into a printable form.

markup :

the text to copy.

format :

the AsMarkupConvertFormat, e.g. AS_MARKUP_CONVERT_FORMAT_MARKDOWN

error :

A GError or NULL

Returns :

a newly allocated NULL terminated string. [transfer full]

Since 0.3.5


as_markup_strsplit_words ()

gchar **            as_markup_strsplit_words            (const gchar *text,
                                                         guint line_len);

Splits up a long line into an array of smaller strings, each being no longer than line_len. Words are not split.

text :

the text to split.

line_len :

the maximum length of the output line

Returns :

lines, or NULL in event of an error. [transfer full]

Since 0.3.5


as_utils_error_quark ()

GQuark              as_utils_error_quark                (void);

Returns :

An error quark.

Since 0.3.7


as_utils_is_stock_icon_name ()

gboolean            as_utils_is_stock_icon_name         (const gchar *name);

Searches the known list of stock icons.

name :

an icon name

Returns :

TRUE if the icon is a "stock icon name" and does not need to be included in the AppStream icon tarball

Since 0.1.3


as_utils_is_spdx_license_id ()

gboolean            as_utils_is_spdx_license_id         (const gchar *license_id);

Searches the known list of SPDX license IDs.

license_id :

a single SPDX license ID, e.g. "CC-BY-3.0"

Returns :

TRUE if the icon is a valid "SPDX license ID"

Since 0.1.5


as_utils_is_spdx_license ()

gboolean            as_utils_is_spdx_license            (const gchar *license);

Checks the licence string to check it being a valid licence. NOTE: SPDX licences can't typically contain brackets.

license :

a SPDX license string, e.g. "CC-BY-3.0 and GFDL-1.3"

Returns :

TRUE if the icon is a valid "SPDX license"

Since 0.2.5


as_utils_is_environment_id ()

gboolean            as_utils_is_environment_id          (const gchar *environment_id);

Searches the known list of registered environment IDs.

environment_id :

a desktop ID, e.g. "GNOME"

Returns :

TRUE if the environment ID is valid

Since 0.2.4


as_utils_is_category_id ()

gboolean            as_utils_is_category_id             (const gchar *category_id);

Searches the known list of registered category IDs.

category_id :

a desktop ID, e.g. "AudioVideoEditing"

Returns :

TRUE if the category ID is valid

Since 0.2.4


as_utils_is_blacklisted_id ()

gboolean            as_utils_is_blacklisted_id          (const gchar *desktop_id);

Searches the known list of blacklisted desktop IDs.

desktop_id :

a desktop ID, e.g. "gimp.desktop"

Returns :

TRUE if the desktop ID is blacklisted

Since 0.2.2


as_utils_spdx_license_tokenize ()

gchar **            as_utils_spdx_license_tokenize      (const gchar *license);

Tokenizes the SPDX license string (or any simarly formatted string) into parts. Any licence parts of the string e.g. "LGPL-2.0+" are prefexed with "@", the conjunctive replaced with "&" and the disjunctive replaced with "|". Brackets are added as indervidual tokens and other strings are appended into single tokens where possible.

license :

a license string, e.g. "LGPLv2+ and (QPL or GPLv2) and MIT"

Returns :

array of strings. [transfer full]

Since 0.1.5


as_utils_spdx_license_detokenize ()

gchar *             as_utils_spdx_license_detokenize    (gchar **license_tokens);

De-tokenizes the SPDX licenses into a string.

license_tokens :

license tokens, typically from as_utils_spdx_license_tokenize()

Returns :

string. [transfer full]

Since 0.2.5


as_utils_find_icon_filename ()

gchar *             as_utils_find_icon_filename         (const gchar *destdir,
                                                         const gchar *search,
                                                         GError **error);

Finds an icon filename from a filesystem root.

destdir :

the destdir.

search :

the icon search name, e.g. "microphone.svg"

error :

A GError or NULL

Returns :

a newly allocated NULL terminated string. [transfer full]

Since 0.2.5


as_utils_find_icon_filename_full ()

gchar *             as_utils_find_icon_filename_full    (const gchar *destdir,
                                                         const gchar *search,
                                                         AsUtilsFindIconFlag flags,
                                                         GError **error);

Finds an icon filename from a filesystem root.

destdir :

the destdir.

search :

the icon search name, e.g. "microphone.svg"

flags :

A AsUtilsFindIconFlag bitfield

error :

A GError or NULL

Returns :

a newly allocated NULL terminated string. [transfer full]

Since 0.3.1


as_utils_install_filename ()

gboolean            as_utils_install_filename           (AsUtilsLocation location,
                                                         const gchar *filename,
                                                         const gchar *origin,
                                                         const gchar *destdir,
                                                         GError **error);

Installs an AppData, MetaInfo, AppStream XML or AppStream Icon metadata file.

location :

the AsUtilsLocation, e.g. AS_UTILS_LOCATION_CACHE

filename :

the full path of the file to install

origin :

the origin to use for the installation, or NULL

destdir :

the destdir to use, or NULL

error :

A GError or NULL

Returns :

TRUE for success, FALSE if error is set

Since 0.3.4


as_utils_search_token_valid ()

gboolean            as_utils_search_token_valid         (const gchar *token);

Checks the search token if it is valid. Valid tokens are at least 3 chars in length, not common words like "and", and do not contain markup.

token :

the search token

Returns :

TRUE is the search token was valid

Since 0.3.4


as_utils_search_tokenize ()

gchar **            as_utils_search_tokenize            (const gchar *search);

Splits up a string into tokens and returns tokens that are suitable for searching. This includes taking out common words and casefolding the returned search tokens.

search :

the search string

Returns :

Valid tokens to search for, or NULL for error. [transfer full]

Since 0.3.4


as_utils_vercmp ()

gint                as_utils_vercmp                     (const gchar *version_a,
                                                         const gchar *version_b);

Compares version numbers for sorting. This function cannot deal with version strings that do not contain numbers, for instance "rev2706" or "1.2_alpha".

version_a :

the release version, e.g. 1.2.3

version_b :

the release version, e.g. 1.2.3.1

Returns :

-1 if a < b, +1 if a > b, 0 if they are equal, and G_MAXINT on error

Since 0.3.5


as_utils_guid_is_valid ()

gboolean            as_utils_guid_is_valid              (const gchar *guid);

Checks the source string is a valid string GUID descriptor.

guid :

string to check

Returns :

TRUE if guid was a valid GUID, FALSE otherwise

Since 0.5.0


as_utils_guid_from_string ()

gchar *             as_utils_guid_from_string           (const gchar *str);

Returns a GUID for a given string. This uses SHA1 and some string modification so even small differences in the str will produce radically different GUID return values.

str :

A source string to use as a key

Returns :

A new GUID, or NULL if the string was invalid

Since 0.5.0