Skip to content

Commit 2886a42

Browse files
authored
Merge pull request #164 from JuliaIO/teh/README_scope
Clarify that load and save should not be extended
2 parents 4bf7c2e + cfc96d5 commit 2886a42

File tree

1 file changed

+8
-1
lines changed

1 file changed

+8
-1
lines changed

README.md

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,7 @@ In your package, write code like the following:
100100
```jl
101101
using FileIO
102102

103+
# See important note about scope below
103104
function load(f::File{format"PNG"})
104105
open(f) do s
105106
skipmagic(s) # skip over the magic bytes
@@ -126,7 +127,13 @@ function save(f::File{format"PNG"}, data)
126127
end
127128
```
128129

129-
Note that `load(::File)` and `save(::File)` should close any streams
130+
Note that these are `load` and `save`, **not** `FileIO.load` and `FileIO.save`.
131+
Because a given format might have multiple packages that are capable of reading it,
132+
FileIO will dispatch to these using module-scoping, e.g., `SomePkg.load(args...)`.
133+
Consequently, **packages should define "private" `load` and `save` methods, and
134+
not extend (import) FileIO's**.
135+
136+
`load(::File)` and `save(::File)` should close any streams
130137
they open. (If you use the `do` syntax, this happens for you
131138
automatically even if the code inside the `do` scope throws an error.)
132139
Conversely, `load(::Stream)` and `save(::Stream)` should not close the

0 commit comments

Comments
 (0)