From cfc96d5df72c77b10cd02cd75c9b0ca84deb8777 Mon Sep 17 00:00:00 2001 From: Tim Holy Date: Mon, 27 Nov 2017 05:34:01 -0600 Subject: [PATCH] Clarify that load and save should not be extended --- README.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 9b29476d..89d540d8 100644 --- a/README.md +++ b/README.md @@ -100,6 +100,7 @@ In your package, write code like the following: ```jl using FileIO +# See important note about scope below function load(f::File{format"PNG"}) open(f) do s skipmagic(s) # skip over the magic bytes @@ -126,7 +127,13 @@ function save(f::File{format"PNG"}, data) end ``` -Note that `load(::File)` and `save(::File)` should close any streams +Note that these are `load` and `save`, **not** `FileIO.load` and `FileIO.save`. +Because a given format might have multiple packages that are capable of reading it, +FileIO will dispatch to these using module-scoping, e.g., `SomePkg.load(args...)`. +Consequently, **packages should define "private" `load` and `save` methods, and +not extend (import) FileIO's**. + +`load(::File)` and `save(::File)` should close any streams they open. (If you use the `do` syntax, this happens for you automatically even if the code inside the `do` scope throws an error.) Conversely, `load(::Stream)` and `save(::Stream)` should not close the