[comment {--- punk::docgen generated from inline doctools comments ---}]
[comment {--- punk::docgen DO NOT EDIT DOCS HERE UNLESS YOU REMOVE THESE COMMENT LINES ---}]
[comment {--- punk::docgen overwrites this file ---}]
[manpage_begin punkshell_module_punk::packagepreference 0 0.1.0]
[copyright "2024"]
[titledesc {punkshell package/module loading}]  [comment {-- Name section and table of contents description --}]
[moddesc {package/module load}]             [comment {-- Description at end of page heading --}]
[require punk::packagepreference]
[keywords module package]
[description]
[para] -
[section Overview]
[para] overview of punk::packagepreference
[subsection Concepts]
[para] -
[subsection dependencies]
[para] packages used by punk::packagepreference
[list_begin itemized]
[item] [package {Tcl 8.6}]
[item] [package {commandstack}]
[list_end]
[section API]
[subsection {Namespace punk::packagepreference::class}]
[para] class definitions
if {[tcl::info::commands [tcl::namespace::current]::interface_sample1] eq ""} {
*** !doctools
[list_begin enumerated]
[list_end] [comment {--- end class enumeration ---}]
}
}
 ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
[subsection {Namespace punk::packagepreference}]
[para] Core API functions for punk::packagepreference
[list_begin definitions]
[call [fun uninstall]]
[para]Return to the previous ::package implementation (This will be the builtin if no other override was present when install was called)
[call [fun install]]
[para]Override ::package builtin (or the current implementation if it has already been renamed/overridden) to check for and prefer lowercase packages/modules
[para](todo - check info loaded and restrict to existing version as determined from dll/so?)
[para]The overriding package command will call whatever implementation was in place before install to do the actual work - once it has modified 'package require' names to lowercase.
[para]This is intended to be in alignment with tip 590 "Recommend lowercase Package Names"
[para] https://core.tcl-lang.org/tips/doc/trunk/tip/590.md
[para]It prevents some loading errors when multiple package versions are available to an interpreter and the latest version is only provided by a lowercased module (.tm file)
[para]A package provided by the standard pkgIndex.tcl mechanism might override a later-versioned package because it may support both upper and lowercased names.
[para]The overriding of ::package only looks at 'package require' calls and preferentially tries the lowercase version (if the package isn't already loaded with either upper or lowercase name)
[para]This comes at some slight cost for packages that are only available with uppercase letters in the name - but at minimal cost for recommended lowercase package names
[para]Return to the standard ::package builtin by calling punk::packagepreference::uninstall
[list_end] [comment {--- end definitions namespace punk::packagepreference ---}]
[subsection {Namespace punk::packagepreference::lib}]
[para] Secondary functions that are part of the API
[list_begin definitions]
[list_end] [comment {--- end definitions namespace punk::packagepreference::lib ---}]
[section Internal]
[subsection {Namespace punk::packagepreference::system}]
[para] Internal functions that are not part of the API
[manpage_end]