Interfaces for use by flox. More...

Namespaces
namespace	command
	Executable command helpers, argument parsers, etc.

namespace	parse
	Interfaces used to parse various `pkgdb` constructs.

namespace	pkgdb
	Interfaces for caching package metadata in SQLite3 databases.

namespace	search
	Interfaces used to search for packages in flakes.

Classes
class	EvalCommand
	Evaluate a `nix` expression with `flox` extensions. More...

class	FilteredLogger
	Custom `nix::Logger` implementation used to filter some messages. More...

class	FlakePackage
	A flox::Package implementation which are pulled from evaluation of a `nix` flake. More...

class	FlakeRegistry
	A registry containing `FloxFlakeInput` members. More...

class	FloxException

class	FloxFlake

class	FloxFlakeInput
	A simple flox::RegistryInput that opens a `nix` evaluator for a flake. More...

class	FloxFlakeInputFactory
	A factory for flox::FloxFlakeInput objects. More...

struct	InputPreferences
	Preferences associated with a registry input. More...

class	NixEvalException
	A `nix::EvalError` was encountered. More...

class	NixState
	Runtime state containing a `nix` store connection and a `nix` evaluator. More...

class	NixStoreMixin
	Mixin which provides a lazy handle to a `nix` store connection. More...

class	Package
	Abstract representation of a "package", analogous to a Nix ‘derivation’. More...

class	RawPackage
	The simplest ‘Package’ implementation comprised of raw values. More...

struct	RegistryInput
	Preferences associated with a named registry input. More...

class	RegistryInputFactory
	The simplest flox::RegistryInput factory which just copies inputs. More...

struct	RegistryRaw
	A set of user inputs used to set input preferences during search and resolution. More...

class	ReplCommand
	Run an interactive `nix` REPL with extensions. More...

Concepts
concept	input_preferences_typename
	Restricts types to those which are derived from flox::InputPreferences.

concept	registry_input_factory
	Restricts types to those which can construct flox::RegistryInput values.

Typedefs
using	AttrPath = std::vector< std::string >
	A list of key names addressing a location in a nested JSON-like object.

using	AttrPathGlob = std::vector< std::optional< std::string > >
	An attribute path which may contain `null` members to represent globs.

using	MaybeCursor = std::shared_ptr< nix::eval_cache::AttrCursor >
	A `std::shared_ptr<nix::eval_cache::AttrCursor>` which may be `nullptr`.

using	Cursor = nix::ref< nix::eval_cache::AttrCursor >
	A non-`nullptr` `std::shared_ptr<nix::eval_cache::AttrCursor>`.

using	System = std::string
	A system pair indicating architecture and platform.

Enumerations
enum	error_category { EC_OKAY = 0 , EC_FAILURE = 1 , EC_FLOX_EXCEPTION = 100 , EC_INVALID_ARG , EC_INVALID_MANIFEST_DESCRIPTOR , EC_INVALID_PKG_QUERY_ARG , EC_INVALID_REGISTRY , EC_INVALID_MANIFEST_FILE , EC_NIX , EC_NIX_EVAL , EC_NIX_LOCK_FLAKE , EC_PACKAGE_INIT , EC_PARSE_MANIFEST_DESCRIPTOR_RAW , EC_PARSE_RESOLVED , EC_PARSE_SEARCH_QUERY , EC_PKG_DB , EC_SQLITE3 , EC_JSON , EC_TOML_TO_JSON , EC_YAML_TO_JSON , EC_INVALID_LOCKFILE , EC_INVALID_HASH , EC_RESOLUTION_FAILURE , EC_ENVIRONMENT_MIXIN }

enum	subtree_type { ST_NONE = 0 , ST_LEGACY = 1 , ST_PACKAGES = 2 }
	A top level key in a `nix` flake.

Functions
void	to_json (nlohmann::json &jto, const FloxException &err)
	Convert a flox::FloxException to a JSON object.

void	forceTrivialValue (nix::EvalState &state, nix::Value &value, const nix::PosIdx pos=nix::noPos)
	Evaluate trivial thunks to values. This has no effect on non-thunks and non-trivial values.

nix::FlakeRef	valueToFlakeRef (nix::EvalState &state, nix::Value &value, const nix::PosIdx pos=nix::noPos, const std::string &errorMsg="while parsing flake reference")
	Convert a `nix::Value` attribute set or string into a `nix::FlakeRef`.

static bool	shouldANSI ()
	determine if we should use ANSI escape sequences.

nix::Logger *	makeFilteredLogger (bool printBuildLogs)
	Create a custom `nix::Logger` which ignores some messages.

void	initNix ()
	Perform one time `nix` global runtime setup.

void	from_json (const nlohmann::json &jfrom, RawPackage &pkg)
	Convert a JSON object to a flox::RawPackage.

void	to_json (nlohmann::json &jto, const flox::RawPackage &pkg)
	Convert a flox::RawPackage to a JSON object.

void	from_json (const nlohmann::json &jfrom, RegistryInput &rip)
	Convert a JSON object to a flox::RegistryInput.

void	to_json (nlohmann::json &jto, const RegistryInput &rip)
	Convert a flox::RegistryInput to a JSON object.

void	from_json (const nlohmann::json &jfrom, RegistryRaw &reg)
	Convert a JSON object to a flox::RegistryRaw.

void	to_json (nlohmann::json &jto, const RegistryRaw &reg)
	Convert a flox::RegistryRaw to a JSON object.

void	from_json (const nlohmann::json &jfrom, InputPreferences &prefs)
	Convert a JSON object to an flox::InputPreferences.

void	to_json (nlohmann::json &jto, const InputPreferences &prefs)
	Convert an flox::InputPreferences to a JSON object.

RegistryRaw	lockRegistry (const RegistryRaw &unlocked, const nix::ref< nix::Store > &store=NixStoreMixin().getStore())
	Lock an unlocked registry.

RegistryRaw	getGARegistry ()
	Get a hard coded registry for use with `flox`'s GA release.

bool	isSQLiteDb (const std::string &dbPath)
	Detect if a path is a SQLite3 database file.

nix::FlakeRef	parseFlakeRef (const std::string &flakeRef)
	Parse a flake reference from either a JSON attrset or URI string.

nlohmann::json	parseOrReadJSONObject (const std::string &jsonOrPath)
	Parse a JSON object from an inline string or a path to a JSON file.

nlohmann::json	readAndCoerceJSON (const std::filesystem::path &path)
	Read a file and coerce its contents to JSON based on its extension.

std::vector< std::string >	splitAttrPath (std::string_view path)
	Split an attribute path string.

bool	isUInt (std::string_view str)
	Is the string @str a positive natural number?

bool	hasPrefix (std::string_view prefix, std::string_view str)
	Does the string @str have the prefix prefix?

std::string &	ltrim (std::string &str)
	trim from start ( in place ).

std::string &	rtrim (std::string &str)
	trim from end ( in place ).

std::string &	trim (std::string &str)
	trim from both ends ( in place ).

std::string	ltrim_copy (std::string_view str)
	trim from start ( copying ).

std::string	rtrim_copy (std::string_view str)
	trim from end ( copying ).

std::string	trim_copy (std::string_view str)
	trim from both ends ( copying ).

std::string	extract_json_errmsg (nlohmann::json::exception &err)
	Extract the user-friendly portion of a nlohmann::json::exception.

std::string	displayableGlobbedPath (const AttrPathGlob &attrs)
	Convert a AttrPathGlob to a string for display.

	NLOHMANN_JSON_SERIALIZE_ENUM (subtree_type, { { ST_NONE, nullptr }, { ST_LEGACY, "legacyPackages" }, { ST_PACKAGES, "packages" } }) struct Subtree
	A strongly typed wrapper over an attribute path subtree name, which is the first element of an attribute path.

void	from_json (const nlohmann::json &jfrom, Subtree &subtree)
	Convert a JSON string to a flox::Subtree.

void	to_json (nlohmann::json &jto, const Subtree &subtree)
	Convert a flox::Subtree to a JSON string.

static const std::vector< std::string > &	getDefaultSystems ()
	Systems to resolve/search in.

static const std::vector< std::string > &	getDefaultSubtrees ()
	‘flake’ subtrees to resolve/search in.

nlohmann::json	tomlToJSON (std::string_view toml)
	Convert a TOML string to JSON.

nlohmann::json	yamlToJSON (std::string_view yaml)
	Convert a YAML string to JSON.

template<typename Exception = FloxException>
static void	assertIsJSONObject (const nlohmann::json &value, const std::string &who="JSON value")
	Assert that a JSON value is an object, or throw an exception.

template<typename T >
std::vector< T >	merge_vectors (const std::vector< T > &lower, const std::vector< T > &higher)
	Merge two std::vector containers by putting all elements of the higher prioirty vector first, then appending the deduplicated keys of the lower priortity vector.

template<typename T >
std::vector< std::optional< T > >	vectorMapOptional (const std::vector< T > &orig)
	Constructs a std::vector<std::optional<T>> from a std::vector<T>.

Variables
static const nix::flake::LockFlags	defaultLockFlags

Detailed Description

Interfaces for use by flox.

< for inline ‘allocValue’, and ‘forceAttrs’.

Typedef Documentation

◆ AttrPathGlob

using flox::AttrPathGlob = typedef std::vector<std::optional<std::string> >

An attribute path which may contain null members to represent globs.

Globs may only appear as the second element representing system.

◆ System

using flox::System = typedef std::string

A system pair indicating architecture and platform.

Examples: x86_64-linux, aarch64-linux, x86_64-darwin, or aarch64-darwin

Enumeration Type Documentation

◆ error_category

enum flox::error_category

Enumerator
EC_OKAY	Indicates success or not an error.
EC_FAILURE	Returned for any exception that doesn't have `getErrorCode()`, i.e. exceptions we haven't wrapped in a custom exception.
EC_FLOX_EXCEPTION	Generic exception emitted by `flox` routines.
EC_INVALID_ARG	A command line argument is invalid.
EC_INVALID_MANIFEST_DESCRIPTOR	A package descriptor in a manifest is invalid.
EC_INVALID_PKG_QUERY_ARG	Errors concerning validity of package query parameters.
EC_INVALID_REGISTRY	A registry has invalid contents.
EC_INVALID_MANIFEST_FILE	The value of ‘manifestPath’ is invalid.
EC_NIX	`nix::Error` that doesn't fall under a more specific `EC_NIX_*` category.
EC_NIX_EVAL	`nix::EvalError`
EC_NIX_LOCK_FLAKE	Exception locking a flake.
EC_PACKAGE_INIT	Exception initializing a flox::FlakePackage.
EC_PARSE_MANIFEST_DESCRIPTOR_RAW	Exception parsing `flox::resolver::ManifestDescriptorRaw` from JSON.
EC_PARSE_RESOLVED	Exception parsing `flox::resolver::Resolved` from JSON.
EC_PARSE_SEARCH_QUERY	Exception parsing flox::search::SearchQuery from JSON.
EC_PKG_DB	For generic exceptions thrown by `flox::pkgdb::*` classes.
EC_SQLITE3	Exceptions thrown by SQLite3.
EC_JSON	Exception parsing/processing JSON.
EC_TOML_TO_JSON	Exception converting TOML to JSON.
EC_YAML_TO_JSON	Exception converting YAML to JSON.
EC_INVALID_LOCKFILE	Exception processing an environment's lockfile.
EC_INVALID_HASH	Invalid hash string.
EC_RESOLUTION_FAILURE	Resolution failure.
EC_ENVIRONMENT_MIXIN	EnvirontMixin exception/misuse.

Function Documentation

◆ assertIsJSONObject()

template<typename Exception = FloxException>

static void flox::assertIsJSONObject	(	const nlohmann::json &	value,
		const std::string &	who = `"JSON value"`
	)

static

Assert that a JSON value is an object, or throw an exception.

The type of exception and an optional path for messages can be provided.

◆ forceTrivialValue()

void flox::forceTrivialValue	(	nix::EvalState &	state,
		nix::Value &	value,
		const nix::PosIdx	pos = `nix::noPos`
	)

Evaluate trivial thunks to values. This has no effect on non-thunks and non-trivial values.

For example, values such as { foo = 1; } may be represented as a thunk, so to process conditional blocks based on type() we must evaluate the thunk to find it's real type first.

◆ getGARegistry()

RegistryRaw flox::getGARegistry ( )

Get a hard coded registry for use with flox's GA release.

This registry contains on nixpkgs input, which is set to github:NixOS/nixpkgs/release-23.05.

◆ hasPrefix()

bool flox::hasPrefix	(	std::string_view	prefix,
		std::string_view	str
	)

Does the string @str have the prefix prefix?

Parameters

prefix	The prefix to check for.
str	String to test.

Returns: true iff str has the prefix prefix.

◆ initNix()

void flox::initNix ( )

Perform one time nix global runtime setup.

You may safely call this function multiple times, after the first invocation it is effectively a no-op.

This replaces the default nix::Logger with a flox::FilteredLogger.

◆ isSQLiteDb()

bool flox::isSQLiteDb ( const std::string & dbPath )

Detect if a path is a SQLite3 database file.

Parameters

dbPath Absolute path.

Returns: true iff path is a SQLite3 database file.

◆ isUInt()

bool flox::isUInt ( std::string_view str )

Is the string @str a positive natural number?

Parameters

str	String to test.

Returns: true iff str is a stringized unsigned integer.

◆ merge_vectors()

template<typename T >

std::vector< T > flox::merge_vectors	(	const std::vector< T > &	lower,
		const std::vector< T > &	higher
	)

Merge two std::vector containers by putting all elements of the higher prioirty vector first, then appending the deduplicated keys of the lower priortity vector.

Parameters

lower	The lower priority std::vector.
higher	The higher priority std::vector.

Returns: The merged std::vector.

◆ NLOHMANN_JSON_SERIALIZE_ENUM()

flox::NLOHMANN_JSON_SERIALIZE_ENUM	(	subtree_type	,
		{ { ST_NONE, nullptr }, { ST_LEGACY, "legacyPackages" }, { ST_PACKAGES, "packages" } }
	)

A strongly typed wrapper over an attribute path subtree name, which is the first element of an attribute path.

Construct a flox::Subtree from a string.

Parse a string into a flox::Subtree.

Convert a flox::Subtree to a string.

Implicitly convert a flox::Subtree to a string.

Compare two flox::Subtree for equality.

Compare two flox::Subtree for inequality.

Compare with a flox::subtree_type for equality.

Compare with a flox::subtree_type for inequality.

◆ parseFlakeRef()

nix::FlakeRef flox::parseFlakeRef ( const std::string & flakeRef )

Parse a flake reference from either a JSON attrset or URI string.

Parameters

flakeRef JSON or URI string representing a nix flake reference.

Returns: Parsed flake reference object.

◆ parseOrReadJSONObject()

nlohmann::json flox::parseOrReadJSONObject ( const std::string & jsonOrPath )

Parse a JSON object from an inline string or a path to a JSON file.

Parameters

jsonOrPath A JSON string or a path to a JSON file.

Returns: A parsed JSON object.

◆ readAndCoerceJSON()

nlohmann::json flox::readAndCoerceJSON ( const std::filesystem::path & path )

Read a file and coerce its contents to JSON based on its extension.

Files with the extension .json are parsed directly. Files with the extension .yaml or .yml are converted to JSON from YAML. Files with the extension .toml are converted to JSON from TOML.

◆ shouldANSI()

static bool flox::shouldANSI ( )

static

determine if we should use ANSI escape sequences.

This is a copy of nix::shouldANSI with the addition of checking the NOCOLOR environment variable ( nix::shouldANSI only checks NO_COLOR ).

◆ splitAttrPath()

std::vector< std::string > flox::splitAttrPath ( std::string_view path )

Split an attribute path string.

Handles quoted strings and escapes.

Variable Documentation

◆ defaultLockFlags

const nix::flake::LockFlags flox::defaultLockFlags

static

Initial value:

= {
  .recreateLockFile = false 
  ,
  .updateLockFile = false,
  .writeLockFile  = false,
  .useRegistries  = std::nullopt 
  ,
  .applyNixConfig = false 
  ,
  .allowUnlocked = true 
  ,
  .commitLockFile = false 
  ,
  .referenceLockFilePath = std::nullopt 
  ,
  .outputLockFilePath = std::nullopt 
  ,
  .inputOverrides = {} 
  ,
  .inputUpdates = {} 
}

Default flags used when locking flakes.

Disable updateLockFile and read existing lockfiles directly.
Disable writeLockFile to avoid writing generated lockfiles to the filesystem; this will only occur if there is no existing lockfile.

Namespaces

Classes

Concepts

Typedefs

Enumerations

Functions

Variables

Detailed Description

Typedef Documentation

◆ AttrPathGlob

◆ System

Enumeration Type Documentation

◆ error_category

Function Documentation

◆ assertIsJSONObject()

◆ forceTrivialValue()

◆ getGARegistry()

◆ hasPrefix()

◆ initNix()

◆ isSQLiteDb()

◆ isUInt()

◆ merge_vectors()

◆ NLOHMANN_JSON_SERIALIZE_ENUM()

◆ parseFlakeRef()

◆ parseOrReadJSONObject()

◆ readAndCoerceJSON()

◆ shouldANSI()

◆ splitAttrPath()

Variable Documentation

◆ defaultLockFlags