Requirement.h File Reference

Go to the source code of this file.

Typedefs
typedef bool(*	ArbiterRequirementPredicate) (const struct ArbiterSelectedVersion *version, const void *context)
	A predicate used to determine whether the given version suitably satisfies the requirement. More...

Enumerations
enum	ArbiterRequirementStrictness { ArbiterRequirementStrictnessStrict, ArbiterRequirementStrictnessAllowVersionZeroPatches }
	How strict to be in matching compatible versions. More...

Functions
ArbiterRequirement *	ArbiterCreateRequirementAny (void)
	Creates a requirement which will match any version. More...
ArbiterRequirement *	ArbiterCreateRequirementAtLeast (const struct ArbiterSemanticVersion *version)
	Creates a requirement which will match versions not less than the specified version. More...
ArbiterRequirement *	ArbiterCreateRequirementCompatibleWith (const struct ArbiterSemanticVersion *version, ArbiterRequirementStrictness strictness)
	Creates a requirement which will match versions that are "compatible with" the given version, according to Semantic Versioning rules about backwards compatibility. More...
ArbiterRequirement *	ArbiterCreateRequirementCompound (const ArbiterRequirement *const *requirements, size_t count)
	Creates a compound requirement that evaluates each of a list of requirements. More...
ArbiterRequirement *	ArbiterCreateRequirementCustom (ArbiterRequirementPredicate predicate, ArbiterUserContext context)
	Creates a requirement which will evaluate a custom predicate whenever a specific version is checked against it. More...
ArbiterRequirement *	ArbiterCreateRequirementExactly (const struct ArbiterSemanticVersion *version)
	Creates a requirement which will only match the specified version, including any prerelease version and build metadata. More...
ArbiterRequirement *	ArbiterCreateRequirementPrioritized (const ArbiterRequirement *baseRequirement, int priorityIndex)
	Creates a requirement with a custom priority, changing how the base requirement intersects with other requirements in the dependency graph. More...
ArbiterRequirement *	ArbiterCreateRequirementUnversioned (ArbiterUserValue metadata)
	Creates a requirement which only matches against ArbiterSelectedVersions that have metadata equal to metadata. More...
int	ArbiterRequirementPriority (const ArbiterRequirement *requirement)
	Returns the priority of the given requirement. More...
bool	ArbiterRequirementSatisfiedBy (const ArbiterRequirement *requirement, const struct ArbiterSelectedVersion *version)
	Determines whether the given requirement is satisfied by the given version. More...

Typedef Documentation

ArbiterRequirementPredicate

typedef bool(* ArbiterRequirementPredicate) (const struct ArbiterSelectedVersion *version, const void *context)

A predicate used to determine whether the given version suitably satisfies the requirement.

Definition at line 47 of file Requirement.h.

Enumeration Type Documentation

ArbiterRequirementStrictness

enum ArbiterRequirementStrictness

How strict to be in matching compatible versions.

Enumerator
ArbiterRequirementStrictnessStrict	Determine compatibility according to a strict interpretation of SemVer.
ArbiterRequirementStrictnessAllowVersionZeroPatches	According to SemVer, technically all 0.y.z releases can break backwards compatibility, meaning that minor and patch versions have to match exactly in order to be "compatible.". This looser variant permits newer patch versions, which is probably closer to what the user wants.

Definition at line 20 of file Requirement.h.

Function Documentation

ArbiterCreateRequirementAny()

ArbiterRequirement* ArbiterCreateRequirementAny

(

void

)

Creates a requirement which will match any version.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementAtLeast()

ArbiterRequirement* ArbiterCreateRequirementAtLeast

(

const struct ArbiterSemanticVersion *

version

)

Creates a requirement which will match versions not less than the specified version.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementCompatibleWith()

ArbiterRequirement* ArbiterCreateRequirementCompatibleWith	(	const struct ArbiterSemanticVersion *	version,
		ArbiterRequirementStrictness	strictness
	)

Creates a requirement which will match versions that are "compatible with" the given version, according to Semantic Versioning rules about backwards compatibility.

Exceptions to the SemVer rules can be applied by using a value other than ArbiterRequirementStrictnessStrict for strictness.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementCompound()

ArbiterRequirement* ArbiterCreateRequirementCompound	(	const ArbiterRequirement *const *	requirements,
		size_t	count
	)

Creates a compound requirement that evaluates each of a list of requirements.

All of the requirements must be satisfied for the compound requirement to be satisfied.

The objects in the C array can be safely freed after calling this function.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementCustom()

ArbiterRequirement* ArbiterCreateRequirementCustom	(	ArbiterRequirementPredicate	predicate,
		ArbiterUserContext	context
	)

Creates a requirement which will evaluate a custom predicate whenever a specific version is checked against it.

The predicate may be invoked many times during dependency resolution, so it should not take a long time to complete.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementExactly()

ArbiterRequirement* ArbiterCreateRequirementExactly

(

const struct ArbiterSemanticVersion *

version

)

Creates a requirement which will only match the specified version, including any prerelease version and build metadata.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementPrioritized()

ArbiterRequirement* ArbiterCreateRequirementPrioritized	(	const ArbiterRequirement *	baseRequirement,
		int	priorityIndex
	)

Creates a requirement with a custom priority, changing how the base requirement intersects with other requirements in the dependency graph.

Normally, if two requirements A and B are found for the same project in the graph, they are intersected to create a requirement which satisfies both A and B. If no intersection is possible, dependency resolution fails.

Priorities short-circuit this intersection process. If requirement A has a lower priority index (meaning that it is higher priority) than requirement B: requirement A will be used, requirement B will be discarded, and no intersection will be performed.

This can lead to surprising behavior that violates users' expectations, but is nonetheless occasionally useful. For example, users sometimes want to be able to specify a particular version to use which lies outside of any semantic versioning scheme (e.g., an arbitrary branch or local checkout), in which case it makes sense to disable some semantic version requirements in the dependency graph.

Note: prioritized requirements may be used to filter the list of available versions, even if they are lower priority than the default and may get discarded. This means that requirements should avoid rejecting valid versions for the project being considered, or else an unsatisfiable constraints error may result.

baseRequirement - A requirement specifying which versions will satisfy the new requirement. Must not be NULL. priorityIndex - A "priority index" for the new requirement. Lower numbers indicate higher priority (just like setpriority() on Unix). Requirements without an explicit priority set are assumed to have priority index 0, meaning negative priorities will override the default and positive priorities will be overridden by the default.

The returned requirement must be freed with ArbiterFree().

ArbiterCreateRequirementUnversioned()

ArbiterRequirement* ArbiterCreateRequirementUnversioned

(

ArbiterUserValue

metadata

)

Creates a requirement which only matches against ArbiterSelectedVersions that have metadata equal to metadata.

The returned requirement must be freed with ArbiterFree().

ArbiterRequirementPriority()

int ArbiterRequirementPriority

(

const ArbiterRequirement *

requirement

)

Returns the priority of the given requirement.

See ArbiterCreateRequirementPrioritized() for more information.

ArbiterRequirementSatisfiedBy()

bool ArbiterRequirementSatisfiedBy	(	const ArbiterRequirement *	requirement,
		const struct ArbiterSelectedVersion *	version
	)

Determines whether the given requirement is satisfied by the given version.