Swap transformCaretLower and transformCaretUpper

[philderbeast]

Related to #11490 but only adds more explanation and doctest examples for the caret version transforming functions. Add subsections to the modification section, range-preserving and range-relaxing modifications.

Note

I find the function names, transformCaretUpper and transformCaretLower, a bit generic and would have preferred removeCaretUpper and removeCaretLower. There are already removeUpperBound and removeLowerBound functions.

QA Notes

For running doctests locally:

$ make doctest-install # one time only for the current system GHC compiler
$ cd Cabal-syntax
$ cabal doctest --allow-newer=False

For building the haddocks locally:

$ cabal haddock Cabal-syntax

---

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).

[philderbeast]

@Mikolaj and @geekosaur, bootstrap jobs are timing out. They work locally for me.

$ python3 bootstrap/bootstrap.py -d bootstrap/linux-9.10.2.json fetch
...
Bootstrap sources saved to /home/.../cabal/bootstrap-sources.tar.gz
...

[Mikolaj]

It looks like a network and/or Hackage outage. Let me restart anyway...

[Mikolaj]

... and it worked! :)

[philderbeast]

Thanks @Mikolaj. I restarted the failing bootstrap jobs 3 times before I asked. Good to see it working again.

[Bodigrim]

Documentation is great, but as I mentioned in #11490 (comment) I think the implementations should not be swapped.

[geekosaur]

TBH that's why I've been keeping quiet about this PR; not being familiar with the exact usage of these functions, I suspected but wasn't sure if that was the intent.

[philderbeast]

I think the implementations should not be swapped.

@Bodigrim, I've undone the swap.

[mergify]

Merge Queue Status

Rule: default

---

• ✅ Entered queue — 2026-02-24 19:45 UTC
• ✅ Checks passed · on draft merge queue: embarking master (9da6ff6) and #11491 together #11519
• ✅ Merged — 2026-02-24 21:39 UTC · at 4e98d4f9a3d1542a3718ae1e7195358058156456

This pull request spent 1 hour 53 minutes 42 seconds in the queue, including 1 hour 42 minutes 57 seconds running CI.

Required conditions to merge

• #approved-reviews-by >= 2 [🛡 GitHub branch protection]
  • Swap transformCaretLower and transformCaretUpper #11491
• #changes-requested-reviews-by = 0 [🛡 GitHub branch protection]
  • Swap transformCaretLower and transformCaretUpper #11491
• #review-threads-unresolved = 0 [🛡 GitHub branch protection]
  • Swap transformCaretLower and transformCaretUpper #11491
• any of [🛡 GitHub branch protection]:
  • check-success = Doctest Cabal
  • check-neutral = Doctest Cabal
  • check-skipped = Doctest Cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Meta checks
  • check-neutral = Meta checks
  • check-skipped = Meta checks
• any of [🛡 GitHub branch protection]:
  • check-success = docs/readthedocs.org:cabal
  • check-neutral = docs/readthedocs.org:cabal
  • check-skipped = docs/readthedocs.org:cabal
• any of [🛡 GitHub branch protection]:
  • check-success = Validate post job
  • check-neutral = Validate post job
  • check-skipped = Validate post job
• any of [🛡 GitHub branch protection]:
  • check-success = fourmolu
  • check-neutral = fourmolu
  • check-skipped = fourmolu
• any of [🛡 GitHub branch protection]:
  • check-success = hlint
  • check-neutral = hlint
  • check-skipped = hlint
• any of [🛡 GitHub branch protection]:
  • check-success = Bootstrap post job
  • check-neutral = Bootstrap post job
  • check-skipped = Bootstrap post job
• any of [🛡 GitHub branch protection]:
  • check-success = whitespace
  • check-neutral = whitespace
  • check-skipped = whitespace
• any of [🛡 GitHub branch protection]:
  • check-success = Check sdist post job
  • check-neutral = Check sdist post job
  • check-skipped = Check sdist post job
• any of [🛡 GitHub branch protection]:
  • check-success = Changelogs
  • check-neutral = Changelogs
  • check-skipped = Changelogs