Replace @import with @require

Author: tecosaur

docs/src/packages.org

@@ -5,7 +5,7 @@ data transformer, one would come across packages that /may/ be needed.
 
 Every possibly desired package could be shoved into the list of dependences, but
 this is a somewhat crude approach. A more granular approach is enabled with two
-macros, ~@addpkg~ and ~@import~.
+macros, ~@addpkg~ and ~@require~.
 
 * Letting DataToolkitBase know about extra packages
 
@@ -16,7 +16,7 @@ macros, ~@addpkg~ and ~@import~.
 * Using extra packages
 
 #+begin_src @docs
-@import
+@require
 #+end_src
 
 * Example
@@ -33,18 +33,45 @@ function __init__()
 end
 
 function load(::DataLoader{:csv}, from::IOStream, ::Type{DataFrame})
-    @import CSV
+    @require CSV
     result = CSV.read(from, DataFrame)
     close(from)
     result
 end
 
 function load(::DataLoader{:delimcsv}, from::IOStream, ::Type{DataFrame})
-    @import DelimitedFiles
+    @require DelimitedFiles
     result = DelimitedFiles.readdlm(from, ',', DataFrame)
     close(from)
     result
 end
 
 end
 #+end_src
+
+Packages that implement loaders with other packages are recommended to use Julia
+1.9's [[https://pkgdocs.julialang.org/dev/creating-packages/#Conditional-loading-of-code-in-packages-(Extensions)][Package Extensions]], together with the ~@requires~ macro and ~invokelatest~ like so:
+
+#+begin_src julia
+# CsvLoaderPkg/src/loader.jl
+function load(::DataLoader{:csv}, from::IOStream, t::Type{DataFrame})
+    @require CSV
+    invokelatest(_load_csv, from, t)
+end
+#+end_src
+
+#+begin_src julia
+# CsvLoaderPkg/ext/csv.jl
+module csv
+
+using CSV
+import CsvLoaderPkg: _load_csv
+
+function _load_csv(from::IOStream, ::Type{DataFrame})
+    result = CSV.read(from, DataFrame)
+    close(from)
+    result
+end
+
+end
+#+end_src

src/DataToolkitBase.jl

@@ -20,7 +20,7 @@ export IdentifierException, UnresolveableIdentifier, AmbiguousIdentifier,
     ReadonlyCollection, TransformerError, UnsatisfyableTransformer,
     OrphanDataSet, InvalidParameterType
 export STACK, DATA_CONFIG_RESERVED_ATTRIBUTES
-export @import, @addpkg, @dataplugin, @advise, @getparam
+export @require, @addpkg, @dataplugin, @advise, @getparam
 
 # For plugin packages
 export PLUGINS, PLUGINS_DOCUMENTATION, DEFAULT_PLUGINS, Plugin,

src/model/errors.jl

@@ -204,7 +204,7 @@ registered by `mod`, and so cannot be loaded.
 # Example occurrence
 
 ```julia-repl
-julia> @import Foo
+julia> @require Foo
 ERROR: UnregisteredPackage: Foo has not been registered by Main, see @addpkg for more information
 Stacktrace: [...]
 ```
@@ -258,7 +258,7 @@ current environment.
 julia> @addpkg Bar "00000000-0000-0000-0000-000000000000"
 Bar [00000000-0000-0000-0000-000000000000]
 
-julia> @import Bar
+julia> @require Bar
 [ Info: Lazy-loading Bar [00000000-0000-0000-0000-000000000001]
 ERROR: MissingPackage: Bar [00000000-0000-0000-0000-000000000001] has been required, but does not seem to be installed.
 Stacktrace: [...]

src/model/globals.jl

@@ -26,11 +26,11 @@ new data collection.
 const DEFAULT_PLUGINS = String[]
 
 """
-The set of packages loaded by each module via `@addpkg`, for import with `@import`.
+The set of packages loaded by each module via `@addpkg`, for import with `@require`.
 
 More specifically, when a module M invokes `@addpkg pkg id` then
 `EXTRA_PACKAGES[M][pkg] = id` is set, and then this information is used
-with `@import` to obtain the package from the root module.
+with `@require` to obtain the package from the root module.
 """
 const EXTRA_PACKAGES = Dict{Module, Dict{Symbol, Base.PkgId}}()