Path handling utilities.

Files
file	glob.hpp
	Defines utilities for handling glob patterns.
file	path_location.hpp
	functions to locate files and directories.

Data Structures
class	hi::v1::glob_pattern
	A glob pattern. More...

Functions
hi_export generator< std::filesystem::path >	hi::v1::glob (std::string_view pattern) noexcept
	Find paths on the filesystem that match the glob pattern.
hi_export generator< std::filesystem::path >	hi::v1::glob (std::string pattern) noexcept
	Find paths on the filesystem that match the glob pattern.
hi_export generator< std::filesystem::path >	hi::v1::glob (char const *pattern) noexcept
	Find paths on the filesystem that match the glob pattern.
hi_export generator< std::filesystem::path >	hi::v1::glob (std::filesystem::path pattern) noexcept
	Find paths on the filesystem that match the glob pattern.
template<path_range Locations>
hi_export generator< std::filesystem::path >	hi::v1::glob (Locations &&locations, std::filesystem::path ref) noexcept
	Find paths on the filesystem that match the glob pattern.
template<path_range Locations>
hi_export generator< std::filesystem::path >	hi::v1::glob (Locations &&locations, std::string_view ref) noexcept
	Find paths on the filesystem that match the glob pattern.
template<path_range Locations>
hi_export generator< std::filesystem::path >	hi::v1::glob (Locations &&locations, std::string ref) noexcept
	Find paths on the filesystem that match the glob pattern.
template<path_range Locations>
hi_export generator< std::filesystem::path >	hi::v1::glob (Locations &&locations, char const *ref) noexcept
	Find paths on the filesystem that match the glob pattern.
template<path_range Locations>
generator< std::filesystem::path >	hi::v1::find_path (Locations &&locations, std::filesystem::path const &ref) noexcept
	Find a path.
generator< std::filesystem::path >	hi::v1::find_path (std::filesystem::path const &location, std::filesystem::path const &ref) noexcept
	Find a path.
template<path_range Locations>
std::filesystem::path	hi::v1::get_path (Locations &&locations, std::filesystem::path const &ref)
	Get a path.
std::filesystem::path	hi::v1::get_path (std::filesystem::path const &location, std::filesystem::path const &ref)
	Get a path.
std::filesystem::path	hi::v1::get_path (std::expected< std::filesystem::path, std::error_code > const &location, std::filesystem::path const &ref)
	Get a path.
std::expected< std::filesystem::path, std::error_code >	hi::v1::executable_file () noexcept
	Get the full path to this executable.
std::expected< std::filesystem::path, std::error_code >	hi::v1::executable_dir () noexcept
	Get the full path to the directory when this executable is located.
std::expected< std::filesystem::path, std::error_code >	hi::v1::data_dir () noexcept
	Get the full path to the directory where the application should store its data.
std::expected< std::filesystem::path, std::error_code >	hi::v1::log_dir () noexcept
	Get the full path to the directory where the application should store its log files.
generator< std::filesystem::path >	hi::v1::resource_dirs () noexcept
	The directories to search for resource files.
generator< std::filesystem::path >	hi::v1::system_font_dirs () noexcept
	The directories to search for system font files.
generator< std::filesystem::path >	hi::v1::font_files () noexcept
	The directories to search for font files of both the application and system.
generator< std::filesystem::path >	hi::v1::theme_files () noexcept
	The directories to search for theme files of the application.
std::optional< std::filesystem::path >	hi::v1::source_dir () noexcept
	Get the full path to source code of this executable.

Detailed Description

This module contains file handling utilities:

• *_dir(), *_dirs(), *_file() for getting the configured paths of the system.
• find_path() to find files in a set of directories.
• glob_pattern, glob() to find files and directories based on a glob pattern.
• URI and URL for managing URLs for local and remote resources.

Path locations

The path-locations functions are used to find files and directories based on the context of the operating system, the user account and application.

For example fonts are located in multiple places:

• the font-directory where a user can install their own fonts,
• the font-directory that is part of the application's resources, and
• the font-directory which is shared between all users of the operating system.

To iterate over all the font directories:

for (auto const &path : font_dirs()) {
    std::cout << path.string() << std::endl;
}

To find the first matching file in one of the font directories:

if (auto const &path : hi::find_path(font_dirs(), "arial.ttf")) {
    std::cout << path->string() << std::endl;
}

glob

To find files based on a pattern using wild cards like * you can use the glob utilities.

The constructor of the glob_pattern object parses a string or std::filesystem::path which contain one or more of the following tokens:

Token	Description
foo	Matches the text "foo".
?	Matches any single character except '/'.
[abcd]	Matches a single character that is 'a', 'b', 'c' or 'd'.
[a-d]	Matches a single character that is 'a', 'b', 'c' or 'd'.
[-a-d]	Matches a single character that is '-', 'a', 'b', 'c' or 'd'.
{foo,bar,baz}	Matches the text "foo", "bar" or "baz".
*	Matches zero or more character except '/'.
/‍**‍/	Matches one or more directories. A single slash or zero or more characters between two slashes.

Then the glob() function will search for files and directories matching this pattern. glob() is also overloaded to directly parse a pattern and combine it with path_location.

For example to find all the files in the font directories:

for (auto const &path : hi::glob(font_dirs(), "**‍/‍
    *.ttf ")) {
    std::cout
    << path.string() << std::endl;
}

URL / URI

The URI, URL and URN terms can be confusing, here is a short explanation.

• A URI (Unique Resource Identifier) is a specification for parsing and writing identifiers.
• A URL (Unique Resource Locator) is a type of URI which is used to address things.
• A URN (Unique Resource Name) is a type of URI which is used to name things.

HikoGUI currently implements dereferencing of the following types of URLs:

• relative path: A relative path does not start with a scheme and can be joined with a base URL to get an absolute URL.
• file-URL: A file accessible via the operating system. This scheme supports the following features:
  • relative paths (can not be joined using URL joining),
  • absolute path (relative to the current drive or file-share),
  • relative path on a specific drive,
  • absolute path on a specific drive and file-share,
  • conversion of drive to a file-share name,
  • the server name may be part of the double-slash "//" path or the authority.
• resource-URL: A relative path that converts into a file-path by searching for the first file in one of the directories of resource_dirs().

Both file: and resource: URLs may be implicitly converted to a std::filesystem::path.

Function Documentation

data_dir()

std::expected< std::filesystem::path, std::error_code > hi::v1::data_dir ( )

inlinenodiscardnoexcept

Get the full path to the directory where the application should store its data.

executable_dir()

std::expected< std::filesystem::path, std::error_code > hi::v1::executable_dir ( )

inlinenodiscardnoexcept

Get the full path to the directory when this executable is located.

executable_file()

std::expected< std::filesystem::path, std::error_code > hi::v1::executable_file ( )

inlinenodiscardnoexcept

Get the full path to this executable.

find_path() [1/2]

template<path_range Locations>

generator< std::filesystem::path > hi::v1::find_path ( Locations && locations, std::filesystem::path const & ref )

inlinenodiscardnoexcept

Find a path.

Parameters

locations	The locations to search for filesystem-object.
ref	A relative path to the filesystem-object.

Returns

full paths to the filesystem-objects found in the location.

find_path() [2/2]

generator< std::filesystem::path > hi::v1::find_path ( std::filesystem::path const & location, std::filesystem::path const & ref )

inlinenodiscardnoexcept

Find a path.

Parameters

location	The location to search for filesystem-object.
ref	A relative path to the filesystem-object.

Returns

full paths to the filesystem-objects found in the location.

font_files()

generator< std::filesystem::path > hi::v1::font_files ( )

inlinenodiscardnoexcept

The directories to search for font files of both the application and system.

get_path() [1/3]

template<path_range Locations>

std::filesystem::path hi::v1::get_path ( Locations && locations, std::filesystem::path const & ref )

inlinenodiscard

Get a path.

Parameters

locations	The locations to search for filesystem-object.
ref	A relative path to the filesystem-object.

Returns

The full path to the first filesystem-object found in the location.

Exceptions

io_error

When a path is not found.

get_path() [2/3]

std::filesystem::path hi::v1::get_path ( std::expected< std::filesystem::path, std::error_code > const & location, std::filesystem::path const & ref )

inlinenodiscard

Get a path.

Parameters

location	The locations to search for filesystem-object.
ref	A relative path to the filesystem-object.

Returns

The full path to the first filesystem-object found in the location.

Exceptions

io_error

When a path is not found.

get_path() [3/3]

std::filesystem::path hi::v1::get_path ( std::filesystem::path const & location, std::filesystem::path const & ref )

inlinenodiscard

Get a path.

Parameters

location	The locations to search for filesystem-object.
ref	A relative path to the filesystem-object.

Returns

The full path to the first filesystem-object found in the location.

Exceptions

io_error

When a path is not found.

glob() [1/8]

hi_export generator< std::filesystem::path > hi::v1::glob ( char const * pattern )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [2/8]

template<path_range Locations>

hi_export generator< std::filesystem::path > hi::v1::glob ( Locations && locations, char const * ref )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

locations	The path-locations to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [3/8]

template<path_range Locations>

hi_export generator< std::filesystem::path > hi::v1::glob ( Locations && locations, std::filesystem::path ref )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

locations	The path-locations to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [4/8]

template<path_range Locations>

hi_export generator< std::filesystem::path > hi::v1::glob ( Locations && locations, std::string ref )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

locations	The path-locations to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [5/8]

template<path_range Locations>

hi_export generator< std::filesystem::path > hi::v1::glob ( Locations && locations, std::string_view ref )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

locations	The path-locations to search files in
ref	A relative path pattern to search the path-location

Returns

a generator yielding paths to objects in the path-location that match the pattern.

glob() [6/8]

hi_export generator< std::filesystem::path > hi::v1::glob ( std::filesystem::path pattern )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [7/8]

hi_export generator< std::filesystem::path > hi::v1::glob ( std::string pattern )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

glob() [8/8]

hi_export generator< std::filesystem::path > hi::v1::glob ( std::string_view pattern )

inlinenodiscardnoexcept

Find paths on the filesystem that match the glob pattern.

Parameters

pattern

The pattern to search the filesystem for.

Returns

a generator yielding paths to objects on the filesystem that match the pattern.

log_dir()

std::expected< std::filesystem::path, std::error_code > hi::v1::log_dir ( )

inlinenodiscardnoexcept

Get the full path to the directory where the application should store its log files.

resource_dirs()

generator< std::filesystem::path > hi::v1::resource_dirs ( )

inlinenodiscardnoexcept

The directories to search for resource files.

source_dir()

std::optional< std::filesystem::path > hi::v1::source_dir ( )

inlinenodiscardnoexcept

Get the full path to source code of this executable.

Returns

The path to directory of the source code.

Return values

std::nullopt

The executable is not located in its build directory.

system_font_dirs()

generator< std::filesystem::path > hi::v1::system_font_dirs ( )

inlinenodiscardnoexcept

The directories to search for system font files.

theme_files()

generator< std::filesystem::path > hi::v1::theme_files ( )

inlinenodiscardnoexcept

The directories to search for theme files of the application.