CUPT_FUNCTIONALSELECTORS(7)

📦
version 2.10.4 · 4 versions
, in ubuntu noble, ubuntu resolute

💖 NAME 💖

cupt_functionselectors — the syntax of functional selectors in the cupt package manager. From the Cupt(7) Miscellaneous Information Manual. ✨

🎯 AIM 🎯

Okay so functional selectors are for fine-grained selection of versions. Standard mechanisms already let you select versions by package name, version string and/or distribution, but functional selectors embed a whole microlanguage to select versions by their various properties. It's giving precision. It's giving main character energy. 👑

✨ SYNTAX ✨

A Functional selector expression (FSE) consists of function name and list of arguments:

'function_name(argument1, argument2, ... argumentN)'

Every argument can be an FSE itself or a string. Arguments are separated by the comma (,). Additional whitespace characters (space, tab, newline) are allowed — and ignored by parser — anywhere except between the function name and the opening bracket. So do not try to separate the function name from its opening bracket, bestie, the parser is not here for that. 🙈

If the argument is a string and contains commas or round brackets, the argument should be quoted by placing the / character around it (/argument/). Slash-core. 🎀

If the function receives no arguments, arguments bracked may be omitted: function_name is an equivalent to function_name(). (Yes, the page says “bracked”. We move. 💀)

The expression argument1 & argument2 & ... & argumentN is a special short form for and(argument1, argument2, ... argumentN). Similarly, the expression argument1 | argument2 | ... | argumentN is a special short form for or(argument1, argument2, ... argumentN). Iconic shorthand behavior. 🔥

🔥 FUNCTION REFERENCE 🔥

🧠 Logic functions

Receive FSEs as arguments.

  • and(fse1, fse2, ... fseN) — argument count: ≥ 1. Returns versions which satisfy all of the fse1..fseN. ✅
  • or(fse1, fse2, ... fseN) — argument count: ≥ 1. Returns versions which satisfy any of the fse1..fseN. 🎉
  • not(fse) — argument count: 1. Returns versions which don't satisfy fse. 🚫
  • xor(fse1, fse2) — argument count: 2. Returns versions which satisfy either fse1 or fse2 but not both. ⚡

📦 Package property functions

  • package:name(regex) — short alias: Pn. Returns versions which package name matches regex. Notes: —. 🌸
  • package:installed() — short alias: Pi. Returns versions which belong to to installed packages. Notes: applies only to binary versions. 🖥️
  • package:automatically-installed() — short alias: Pai. Returns versions which belong to automatically installed packages. Notes: applies only to binary versions. 🤖

🌈 Common version property functions

Apply to source and binary versions. So both sides get the vibe check. 🦋

  • version(regex) — short alias: v. Returns versions which version string matches regex. 🔢
  • maintainer(regex) — short alias: m. Returns versions which maintainer matches regex. 👩‍💻
  • priority(regex) — short alias: p. Returns versions which priority matches regex. ⭐
  • section(regex) — short alias: s. Returns versions which section matches regex. 📚
  • trusted() — short alias: t. Returns versions which come from at least one release with a valid cryptographic signature. 🔐
  • field(field_name, regex) — short alias: f. Returns versions which value¹ of the non-standard (not recognized by Cupt) field field_name matches regex. 📝

¹If the version does not contain a field field_name, its value is assumed being empty string; and it can still match if regular expression matches empty string. So empty-string regex energy is valid here. 🫶

Functions from this family receive one string argument (regex) and return versions which come from at least one release where property (see the following table) matches the regular expression regex.

okay so continuing with the release property functions, bestie, here's the whole vibe: 💖

the columns are Function name, Short alias, and Property, and each bullet is giving exactly that:

  • release:archive — alias: Ra — property: archive
  • release:codename — alias: Rn — property: codename
  • release:component — alias: Rc — property: component
  • release:version — alias: Rv — property: version
  • release:vendor — alias: Ro — property: vendor
  • release:origin — alias: Ru — property: origin (base URI)

Binary version property functions ✨

these functions? they apply only to binary versions, no cap. 💅

the columns are Function name and arguments, Short alias, and Returns versions which..., so here's the tea:

  • source-package(regex) — alias: sp — returns versions which source package matches regex
  • source-version(regex) — alias: sv — returns versions which source version string matches regex
  • essential() — alias: e — returns versions which have 'Essential' flag set
  • important() — alias: (none) — returns versions which have 'Important' flag set
  • installed() — alias: i — returns versions which are installed in the system
  • description(regex) — alias: d — returns versions which description matches regex
  • provides(regex) — alias: o — returns versions which provides at least one virtual package which matches regex

Source version property functions 🌸

these apply only to source versions, bestie. 🫶

  • uploaders(regex) — alias: u — returns versions which have at least one uploader which matches regex

Binary relation functions 💅

these apply only to binary versions, periodt.

forward dependencies 🔥

Functions from this family receive one FSE-argument (fse) and return all versions which satisfy the dependency of type relation type for fse (see the following table).

so like, each bullet is: Function name, Short alias, Relation type. here we go:

  • pre-depends — alias: Ypd — relation type: Pre-Depends
  • depends — alias: Yd — relation type: Depends
  • recommends — alias: Yr — relation type: Recommends
  • suggests — alias: Ys — relation type: Suggests
  • enhances — alias: Ye — relation type: Enhances
  • conflicts — alias: Yc — relation type: Conflicts
  • breaks — alias: Yb — relation type: Breaks
  • replaces — alias: Yrp — relation type: Replaces

reverse dependencies 🌈

Functions from this family receive one FSE-argument (fse) and return all versions for which at least one version from fse satisfies the dependency of type relation type (see the following table).

  • reverse-pre-depends — short alias: YRpd, relation type: Pre-Depends 💖
  • reverse-depends — short alias: YRd, relation type: Depends ✨
  • reverse-recommends — short alias: YRr, relation type: Recommends 🎀
  • reverse-suggests — short alias: YRs, relation type: Suggests 🦋
  • reverse-enhances — short alias: YRe, relation type: Enhances 🌸
  • reverse-conflicts — short alias: YRc, relation type: Conflicts 💅
  • reverse-breaks — short alias: YRb, relation type: Breaks 🫶
  • reverse-replaces — short alias: YRrp, relation type: Replaces 😭

Source relation functions 🧚

forward dependencies 💖

Okay so bestie, these ones are giving source versions only — they take in source versions and return binary versions. No cap. Every function in this fam gets one FSE-argument (fse) and returns all the versions that satisfy the build-time dependency of type relation type for that fse (the table below spills the tea). 💅

  • build-depends — short alias: Zbd, relation type: Build-Depends 🔥
  • build-depends-indep — short alias: Zbdi, relation type: Build-Depends-Indep 🔥
  • build-depends-arch — short alias: (none), relation type: Build-Depends-Arch 🔥
  • build-conflicts — short alias: Zbc, relation type: Build-Conflicts 💀
  • build-conflicts-indep — short alias: Zbci, relation type: Build-Conflicts-Indep 💀
  • build-conflicts-arch — short alias: (none), relation type: Build-Conflicts-Arch 💀

reverse dependencies 💜

Now for the reverse glow-up: these apply only to binary versions and return source versions. Fr fr. Every function here also gets one FSE-argument (fse) and returns all the versions for which at least one version from that fse satisfies the build-dependency of type relation type (again, table below has the tea). 🌈

  • reverse-build-depends — short alias: ZRbd, relation type: Build-Depends 🌈
  • reverse-build-depends-indep — short alias: ZRbdi, relation type: Build-Depends-Indep 🌈
  • reverse-build-depends-arch — short alias: (none), relation type: Build-Depends-Arch 🌈
  • reverse-build-conflicts — short alias: ZRbc, relation type: Build-Conflicts ⭐
  • reverse-build-conflicts-indep — short alias: ZRbci, relation type: Build-Conflicts-Indep ⭐
  • reverse-build-conflicts-arch — short alias: (none), relation type: Build-Conflicts-Arch ⭐

Metafunctions 👑

defining functions 🎀

The function with defines a user function with no parameters that you can use as an FSE-argument in the subexpression. It's giving custom vibes. Here's the syntax:

with(function_name, function_expression, subexpression)
  • function_name — user-defined function name, must start with an underscore (_) 💅
  • function_expression — FSE, function value ✨
  • subexpression — FSE which the defined function can be used in 🦋

This function returns the value of subexpression. Periodt. 👑

recursing 🧚

The function recursive defines a recursive transformation FSE. Lowkey iconic. Syntax:

recursive(subresult_function_name, initial_subresult, iterating_expression)

These are the args, and they're literally everything you need to know bestie 💖:

  • subresult_function_name — a user-defined function name, and no cap it must start with an underscore (_) or it's not valid, periodt
  • initial_subresult — an FSE, the starting value of subresult_function_name
  • subexpression — an FSE that gets computed on every single recurse iteration, and it's the one subresult_function_name is used in

So here's the whole vibe check of how the function actually runs, step by step ✨:

  1. subresult_function_name defined as initial_subresult
  2. the value of iterating_expression is computed
  3. if this value is equal to subresult_function_name() its returned as function result
  4. subresult_function_name redefined as or(subresult_function_name, iterating_expression)
  5. go to step 2

🗺️ mapping

The function fmap applies many functions to the same expression and then combines all their results together — it's giving group project but actually productive 🫶.

So this expression right here:

fmap(fse, function_name_1, ..., function_name_N)

is literally equivalent to:

or(function_name_1(fse), ..., function_name_N(fse))

🎀 Miscellaneous

A few extra icon functions that lowkey do the most 💅:

  • best(fse) — filters out those versions from fse for which there are another version of the same package and higher pin
  • binary-to-source(binary_fse) — converts binary versions, selected by binary_fse, to their corresponding source versions
  • source-to-binary(source_fse) — converts source versions, selected by source_fse, to lists of their corresponding binary versions

And that's a wrap on the whole page, bestie 😭💖 footer check real quick: Eugene V. Lyubimkin holds it down on the left, there's a date stamped in the middle (44date), and it all signs off as Function... in Cupt(7) on the right. Iconic. Go write some selectors, you've got this 🌈👑✨

📦 where this page comes from