as-utils: AppStream-glib Reference Manual

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

## Stability Level

Stable, unless otherwise indicated

## Functions

gchar * | as_markup_convert_simple ()
gchar * | as_markup_convert ()
gchar ** | as_markup_strsplit_words ()
GQuark | as_utils_error_quark ()
gboolean | as_utils_is_stock_icon_name ()
gboolean | as_utils_is_spdx_license_id ()
gboolean | as_utils_is_spdx_license ()
gboolean | as_utils_is_environment_id ()
gboolean | as_utils_is_category_id ()
gboolean | as_utils_is_blacklisted_id ()
gchar ** | as_utils_spdx_license_tokenize ()
gchar * | as_utils_spdx_license_detokenize ()
gchar * | as_utils_find_icon_filename ()
gchar * | as_utils_find_icon_filename_full ()
gboolean | as_utils_install_filename ()
gboolean | as_utils_search_token_valid ()
gchar ** | as_utils_search_tokenize ()
gint | as_utils_vercmp ()
gboolean | as_utils_guid_is_valid ()
gchar * | as_utils_guid_from_string ()

## Types and Values

enum | AsUtilsError
#define | AS_UTILS_ERROR
enum | AsUtilsFindIconFlag
enum | AsUtilsLocation
enum | AsMarkupConvertFormat

## Includes

    #include <appstream-glib.h>

## Description

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

## Functions

### as_markup_convert_simple ()

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

Converts an XML description into a printable form.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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".

#### Parameters

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.

#### Parameters

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.

#### Parameters

str | A source string to use as a key |

#### Returns

A new GUID, or `NULL` if the string was invalid

Since: 0.5.0

## Types and Values

### enum AsUtilsError

The error type.

#### Members

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

The flags used when finding icons.

#### Members

AS_UTILS_FIND_ICON_NONE | No flags set |
AS_UTILS_FIND_ICON_HI_DPI | Prefer a HiDPI icon |

### enum AsUtilsLocation

The flags used when installing and removing metadata files.

#### Members

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

The output format used when converting AppStream descriptions.

#### Members

AS_MARKUP_CONVERT_FORMAT_SIMPLE | UTF-8 text |
AS_MARKUP_CONVERT_FORMAT_MARKDOWN | Markdown format |