From 89043b80c999dd11dc9515bbe8912afc6592fdf1 Mon Sep 17 00:00:00 2001
From: Spencer Russell <spencer.f.russell@gmail.com>
Date: Mon, 11 Aug 2014 17:34:21 -0400
Subject: [PATCH] deprecates af_open in favor of AudioIO.open

---
 notes/file_api.md    | 16 ++++++++--------
 src/sndfile.jl       | 15 +++++++++++----
 test/test_AudioIO.jl |  4 ++--
 3 files changed, 21 insertions(+), 14 deletions(-)

diff --git a/notes/file_api.md b/notes/file_api.md
index f484f93..009fb4f 100644
--- a/notes/file_api.md
+++ b/notes/file_api.md
@@ -55,13 +55,13 @@ IOStream API
 Separate Open Function API
 --------------------------
 
-* users use an explicit `af_open` function to open sound files
-* `af_open` takes mode arguments just like the regular julia `open` function
-* `af_open` returns a AudioFile instance.
+* users use an explicit `AudioIO.open` function to open sound files
+* `AudioIO.open` takes mode arguments just like the regular julia `open` function
+* `AudioIO.open` returns a AudioFile instance.
 
 ### Play a file through the speakers
 
-    sndfile = af_open("myfile.wav")
+    sndfile = AudioIO.open("myfile.wav")
     play(sndfile)
     close(sndfile)
 
@@ -71,7 +71,7 @@ or
 
 ### Use a file as input to an AudioNode for processing
 
-    sndfile = af_open("myfile.wav")
+    sndfile = AudioIO.open("myfile.wav")
     # FilePlayer also can take a string filename for convenience
     node = FilePlayer(sndfile)
     mixer = AudioMixer([node])
@@ -79,20 +79,20 @@ or
 
 ### Read a file into an array
 
-    sndfile = af_open("myfile.wav")
+    sndfile = AudioIO.open("myfile.wav")
     vec = read(sndfile) # takes an optional arg for number of frames to read
     close(sndfile)
 
 ###  Write an array into a file
 
-    sndfile = af_open("myfile.wav", "w") #TODO: need to specify format
+    sndfile = AudioIO.open("myfile.wav", "w") #TODO: need to specify format
     vec = rand(Float32, 441000) # 10 seconds of noise
     write(sndfile, vec)
     close(sndfile)
 
 ###  Write the output of an AudioNode to a file
 
-    sndfile = af_open("myfile.wav", "w") #TODO: need to specify format
+    sndfile = AudioIO.open("myfile.wav", "w") #TODO: need to specify format
     node = SinOsc(440)
     write(sndfile, node, 44100) # record 1 second, optional block_size
     # note that write() can handle sample depth conversions, and render() is
diff --git a/src/sndfile.jl b/src/sndfile.jl
index 7664614..afcb325 100644
--- a/src/sndfile.jl
+++ b/src/sndfile.jl
@@ -37,7 +37,9 @@ type AudioFile
     sfinfo::SF_INFO
 end
 
-function af_open(path::String, mode::String = "r",
+# AudioIO.open is part of the public API, but is not exported so that it
+# doesn't conflict with Base.open
+function open(path::String, mode::String = "r",
             sampleRate::Integer = 44100, channels::Integer = 1,
             format::Integer = 0)
     @assert channels <= 2
@@ -76,12 +78,17 @@ function Base.close(file::AudioFile)
     end
 end
 
-function af_open(f::Function, args...)
-    file = af_open(args...)
+function open(f::Function, args...)
+    file = AudioIO.open(args...)
     f(file)
     close(file)
 end
 
+function af_open(args...)
+    warn("af_open is deprecated, please use AudioIO.open instead")
+    AudioIO.open(args...)
+end
+
 # TODO: we should implement a general read(node::AudioNode) that pulls data
 # through an arbitrary render chain and returns the result as a vector
 function Base.read(file::AudioFile, nframes::Integer, dtype::Type)
@@ -152,7 +159,7 @@ end
 
 typealias FilePlayer AudioNode{FileRenderer}
 FilePlayer(file::AudioFile) = FilePlayer(FileRenderer(file))
-FilePlayer(path::String) = FilePlayer(af_open(path))
+FilePlayer(path::String) = FilePlayer(AudioIO.open(path))
 
 function render(node::FileRenderer, device_input::AudioBuf, info::DeviceInfo)
     @assert node.file.sfinfo.samplerate == info.sample_rate
diff --git a/test/test_AudioIO.jl b/test/test_AudioIO.jl
index 0c65d83..224088f 100644
--- a/test/test_AudioIO.jl
+++ b/test/test_AudioIO.jl
@@ -108,11 +108,11 @@ facts("WAV file write/read") do
     phase = 2 * pi * freq * t
     reference = int16((2 ^ 15 - 1) * sin(phase))
 
-    af_open(fname, "w") do f
+    AudioIO.open(fname, "w") do f
         write(f, reference)
     end
 
-    af_open(fname) do f
+    AudioIO.open(fname) do f
         @fact f.sfinfo.channels => 1
         @fact f.sfinfo.frames => 2 * samplerate
         actual = read(f, 2 * samplerate)