Merge pull request #55 from MikeInnes/teh/README

Update README for the new UUID & __init__ syntax

Author: MikeInnes

README.md

@@ -1,12 +1,6 @@
-### Note: changes in v0.7
+### Note: this page is for Julia 0.7 and higher
 
-Requires now needs a UUID, and must be called from within your packages `__init__` function. For example:
-
-```julia
-function __init__()
-    @require JSON="682c06a0-de6a-54ab-a142-c8b1cf79cde6" do_stuff()
-end
-```
+For older versions of Julia, see https://github.com/MikeInnes/Requires.jl/blob/5683745f03cbea41f6f053182461173e236fdd94/README.md
 
 # Requires.jl
 
@@ -17,34 +11,85 @@ faster, maybe. It supports specifying glue code in packages which will
 load automatically when a another package is loaded, so that explicit
 dependencies (and long load times) can be avoided.
 
-Usage is as simple as
+Suppose you've written a package called `MyPkg`. `MyPkg` has core functionality that it always provides;
+but suppose you want to provide additional functionality if the `Gadfly` package is also loaded.
+Requires.jl exports a macro, `@require`, that allows you to specify that some code is conditional on having both packages available.
+
+`@require` must be within the [`__init__`](https://docs.julialang.org/en/v1/manual/modules/#Module-initialization-and-precompilation-1) method for your module.
+Here's an example that will create a new method of a function called `myfunction` only when both packages are present:
+
+```julia
+module MyPkg
+
+# lots of code
+
+myfunction(::MyType) = Textual()
+
+function __init__()
+    @require Gadfly="c91e804a-d5a3-530f-b6f0-dfbca275c004" myfunction(::Gadfly.Plot) = Graphical()
+end
+
+end # module
+```
+
+The value in the string is Gadfly's UUID; this information may be obtained
+by finding the package in the registry ([JuliaRegistries](https://github.com/JuliaRegistries/General) for public packages).
+Note that the `Gadfly.Plot` type may not be available when you load `MyPkg`, but `@require`
+handles this situation without trouble.
+
+For larger amounts of code you can use `include` as the argument to the `@require` statement:
 
 ```julia
-media(::MyType) = Textual()
+function __init__()
+    @require Gadfly="c91e804a-d5a3-530f-b6f0-dfbca275c004" include("glue.jl")
+end
+```
+
+and this will trigger the loading and evaluation of `"glue.jl"` in `MyPkg` whenever Gadfly is loaded.
+You can even use
 
-@require Gadfly begin
-  media(::Gadfly.Plot) = Graphical()
+```julia
+function __init__()
+    @require Gadfly="c91e804a-d5a3-530f-b6f0-dfbca275c004" @eval using MyGluePkg
 end
 ```
 
-For larger amounts of code you can also use `@require Package include("glue.jl")`.
-The code wrapped by `@require` will execute as soon as the given package is loaded
-(which may be immediately).
+if you wish to exploit precompilation for the new code.
+
+## Demo
+
+For a complete demo, consider the following file named `"Reqs.jl"`:
 
 ```julia
-julia> using Requires
+module Reqs
 
-julia> @require DataFrames println("foo")
+using Requires
 
-julia> using DataFrames
-foo
+function __init__()
+    @require JSON="682c06a0-de6a-54ab-a142-c8b1cf79cde6" @eval using Colors
+end
 
-julia> @require DataFrames println("bar")
-bar
+end
 ```
 
-Note that the package is not imported by default – you need an explicit `using`
-statement if you want to use the packages names without qualifying them.
+Here's a session that shows how `Colors` is only loaded after you've imported `JSON`:
+
+```julia
+julia> include("Reqs.jl")
+Main.Reqs
+
+julia> using Main.Reqs
+
+julia> Reqs.Colors
+ERROR: UndefVarError: Colors not defined
+
+julia> using JSON
+
+julia> Reqs.Colors
+Colors
+
+julia> Reqs.Colors.RGB(1,0,0)
+RGB{N0f8}(1.0,0.0,0.0)
+```
 
-See [here](https://github.com/one-more-minute/Jewel.jl/blob/b0e8c184f57e8e60c83e1b9ef49511b08c88f16f/src/LightTable/display/objects.jl#L168-L170)
-for some more detailed examples.
+Note that if `Reqs` were a registered package you could replace the first two commands with `using Reqs`.