Skip to content
This repository has been archived by the owner on Sep 27, 2023. It is now read-only.

Commit

Permalink
doc: package-set.hh
Browse files Browse the repository at this point in the history
  • Loading branch information
@aakropotkin
aakropotkin committed Jul 28, 2023
1 parent 8095557 commit d39cabb
Show file tree
Hide file tree
Showing 2 changed files with 83 additions and 70 deletions.
75 changes: 65 additions & 10 deletions include/flox/package-set.hh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -22,21 +22,46 @@ namespace flox {

/* -------------------------------------------------------------------------- */

/**
* Abstract representation of a package set containing derivation metadata.
* This is used to provide various container like utilities across different
* back-ends ( implementations ) to avoid repeated routines.
*/
class PackageSet {

public:
virtual std::string_view getType() const = 0;
virtual subtree_type getSubtree() const = 0;
virtual std::string_view getSystem() const = 0;
virtual FloxFlakeRef getRef() const = 0;
virtual std::size_t size() = 0;

virtual bool empty() { return this->size() <= 0; }

virtual bool hasRelPath( const std::list<std::string_view> & path ) = 0;

/**
* PackageSet "type" represented as a simple string.
* This is used for error messages and working with abstract @a PackageSet
* references in generic utility functions.
*/
virtual std::string_view getType() const = 0;

/** @return the flake output "subtree" associated with the package set. */
virtual subtree_type getSubtree() const = 0;

/** @return the architecture/platform associated with the package set. */
virtual std::string_view getSystem() const = 0;

/**
* @return For package sets in a `catalog` @a subtree, returns the
* associated `flox` _stability_ associated with the package set.
* For non-catalog package sets, returns @a std::nullopt.
*/
virtual std::optional<std::string_view> getStability() const = 0;

/**
* @return The flake reference associated with the package set indicating
* its source.
*/
virtual FloxFlakeRef getRef() const = 0;

/**
* Packages contained by @a this package set are referred to as being
* "relative" to a `<SUBTREE>.<SYSTEM>[.<STABILITY>]` attribute path prefix.
* @return an list of strings representing the attribute path to the root
* ( _prefix_ ) of the package set.
*/
virtual std::list<std::string_view>
getPrefix() const
{
Expand All @@ -58,10 +83,40 @@ class PackageSet {
}
}

/** @return The number of packages in the package set. */
virtual std::size_t size() = 0;

/** @return true iff the package set has no packages. */
virtual bool empty() { return this->size() <= 0; }

/**
* Predicate which checks to see if the package set has a package at the
* relative path @a path.
* @param path A relative attribute path ( with no subtree, system,
* or stability components ) to search for.
* @return `true` iff the package set has a package at @a path.
*/
virtual bool hasRelPath( const std::list<std::string_view> & path ) = 0;

/**
* Attempts to get package metadata associated with the relative path
* @a path if it exists.
* @param path A relative attribute path ( with no subtree, system,
* or stability components ) to search for.
* @return `nullptr` if the package set does not contain a package at
* @a path, otherwise a pointer to the requested package metadata.
*/
virtual std::shared_ptr<Package> maybeGetRelPath(
const std::list<std::string_view> & path
) = 0;

/**
* Gets package metadata associated with the relative path @a path.
* Throws an error if the package set is missing the requested metadata.
* @param path A relative attribute path ( with no subtree, system,
* or stability components ) to search for.
* @return A non-null pointer to the requested package metadata.
*/
virtual nix::ref<Package>
getRelPath( const std::list<std::string_view> & path )
{
Expand Down
78 changes: 18 additions & 60 deletions include/flox/raw-package-set.hh
View file
Original file line number Diff line number Diff line change
Expand Up @@ -44,15 +44,15 @@ class RawPackageSet : public PackageSet {
subtree_type _subtree;
std::string _system;
std::optional<std::string> _stability;
FloxFlakeRef _ref; /** indicates package set's "source" */
FloxFlakeRef _ref; /** Indicates package set's "source" */

public:

/**
* Constructs an package set associated a flake and attr-path prefix.
* @param pkgs attr-path -> package data.
* @param subtree flake output "subtree" the package set comes from.
* @param system architecture/platform the package set comes from.
* @param subtree Flake output "subtree" the package set comes from.
* @param system Architecture/Platform the package set comes from.
* @param stability `flox` _stability_ category the package set comes from.
* ( optional: `catalog` @a subtree only )
*/
Expand All @@ -72,67 +72,32 @@ class RawPackageSet : public PackageSet {
, _ref( ref )
{}

/**
* PackageSet "type" represented as a simple string.
* This is used for error messages and working with abstract @a PackageSet
* references in generic utility functions.
*/
std::string_view getType() const override { return "raw"; }

/** @return the flake output "subtree" associated with the package set. */
subtree_type getSubtree() const override { return this->_subtree; }

/** @return the architecture/platform associated with the package set. */
std::string_view getSystem() const override { return this->_system; }

/**
* @return the flake reference assocaited with the package set indicating
* its source.
*/
FloxFlakeRef getRef() const override { return this->_ref; }

/**
* @return For package sets in a `catalog` @a subtree, returns the
* associated `flox` _stability_ associated with the package set.
* For non-catalog package sets, returns @a std::nullopt.
*/
std::optional<std::string_view>
getStability() const override
{
if ( this->_stability.has_value() ) { return this->_stability; }
else { return std::nullopt; }
}

/** @return the number of packages in the package set. */
std::size_t size() override { return this->_pkgs.size(); }
/** @return the number of packages in the package set. */
std::size_t size() const { return this->_pkgs.size(); }
/** @return true iff the package set has no packages. */
bool empty() override { return this->_pkgs.empty(); }
/** @return true iff the package set has no packages. */
bool empty() const { return this->_pkgs.empty(); }
std::size_t size() override { return this->_pkgs.size(); }
std::size_t size() const { return this->_pkgs.size(); }
bool empty() override { return this->_pkgs.empty(); }
bool empty() const { return this->_pkgs.empty(); }

/**
* Predicate which checks to see if the package set has a package at the
* relative path @a path.
* @param path a relative attribute path ( with no subtree, system,
* or stability components ) to search for.
* @return true iff the package set has a package at @a path.
*/
bool
hasRelPath( const std::list<std::string_view> & path ) override
{
return this->_pkgs.find( path ) != this->_pkgs.cend();
}

/**
* Attempts to get package metadata associated with the relative path
* @a path if it exists.
* @param path a relative attribute path ( with no subtree, system,
* or stability components ) to search for.
* @return nullptr if the package set does not contain a package at @a path,
* otherwise a pointer to the requested package metadata.
*/
std::shared_ptr<Package>
maybeGetRelPath( const std::list<std::string_view> & path ) override
{
Expand All @@ -147,13 +112,6 @@ class RawPackageSet : public PackageSet {
}
}

/**
* Gets package metadata associated with the relative path @a path.
* Throws an error if the package set is missing the requested metadata.
* @param path a relative attribute path ( with no subtree, system,
* or stability components ) to search for.
* @return a non-null pointer to the requested package metadata.
*/
nix::ref<Package>
getRelPath( const std::list<std::string_view> & path ) override
{
Expand All @@ -164,7 +122,7 @@ class RawPackageSet : public PackageSet {
* Adds package metadata to the package set.
* @a p is assumed to have an attribute path which is consistent
* with @a this package set.
* @param p package metadata to be added.
* @param p Package metadata to be added.
*/
void
addPackage( RawPackage && p )
Expand Down Expand Up @@ -231,7 +189,7 @@ class RawPackageSet : public PackageSet {

/**
* Increment the iterator one position forward.
* @return the incremented iterator.
* @return The incremented iterator.
*/
iterator_impl &
operator++()
Expand All @@ -245,7 +203,7 @@ class RawPackageSet : public PackageSet {

/**
* Increment the iterator one position forward.
* @return the orginal iterator.
* @return The orginal iterator.
*/
iterator_impl
operator++( int )
Expand Down Expand Up @@ -276,9 +234,9 @@ class RawPackageSet : public PackageSet {
return this->_ptr != other._ptr;
}

/** @return a reference to the @a RawPackage at the current position. */
/** @return A reference to the @a RawPackage at the current position. */
reference operator*() const { return * this->_ptr; }
/** @return a pointer to the @a RawPackage at the current position. */
/** @return A pointer to the @a RawPackage at the current position. */
pointer operator->() { return this->_ptr; }

friend iterator;
Expand All @@ -289,24 +247,24 @@ class RawPackageSet : public PackageSet {

/* -------------------------------------------------------------------------- */

/** @return read/write iterator at the beginning of the container. */
/** @return Read/Write iterator at the beginning of the container. */
iterator begin() { return iterator( & this->_pkgs ); }
/** @return sentinel value used to represent the "end" of the container. */
/** @return Sentinel value used to represent the "end" of the container. */
iterator end() { return iterator( & this->_pkgs, this->_pkgs.end() ); }

/** @return read-only iterator at the beginning of the container. */
/** @return Read-only iterator at the beginning of the container. */
const_iterator begin() const { return const_iterator( & this->_pkgs ); }

/** @return sentinel value used to represent the "end" of the container. */
/** @return Sentinel value used to represent the "end" of the container. */
const_iterator
end() const
{
return const_iterator( & this->_pkgs, this->_pkgs.cend() );
}

/** @return read-only iterator at the beginning of the container. */
/** @return Read-only iterator at the beginning of the container. */
const_iterator cbegin() const { return this->begin(); }
/** @return sentinel value used to represent the "end" of the container. */
/** @return Sentinel value used to represent the "end" of the container. */
const_iterator cend() const { return this->end(); }


Expand Down

0 comments on commit d39cabb

Please sign in to comment.