From 57ccea261ee85685723c1b5ad1f0e1ec6593aab8 Mon Sep 17 00:00:00 2001 From: nucular Date: Sat, 5 Mar 2016 19:39:12 +0100 Subject: [PATCH] Fixed some documentation and raised errors --- doc/api/sfxr.html | 69 ++++++++++++++++++++++++++++--------------- doc/index.html | 69 ++++++++++++++++++++++++++++--------------- sfxr.lua | 74 +++++++++++++++++++++++++++-------------------- 3 files changed, 135 insertions(+), 77 deletions(-) diff --git a/doc/api/sfxr.html b/doc/api/sfxr.html index 7ecacca..9b5e6cf 100644 --- a/doc/api/sfxr.html +++ b/doc/api/sfxr.html @@ -113,7 +113,7 @@ self.waveform - (WAVEFORM) The base wave form + The base wave form (default SQUARE) self.envelope.attack @@ -124,7 +124,7 @@ self.envelope.sustain Sustain time: - Time the sound sustains on its peak volume + Time the sound stays on its peak volume (default 0.0, min 0.0, max 1.0) @@ -272,7 +272,7 @@ Generate the sound to a binary string. - sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, a]]]) + sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, sounddata]]]) Synthesize the sound to a LÖVE SoundData instance. @@ -316,7 +316,7 @@ Generate and export the audio data to a PCM WAVE file. - sfxr.Sound:save (f[, to=true]) + sfxr.Sound:save (f[, minify=true]) Save the sound parameters to a file as a Lua table @@ -325,11 +325,12 @@ sfxr.Sound:saveBinary (f) - Save the sound parameters to a file in the sfxr binary format + Save the sound parameters to a file in the sfxr binary format (version 102) sfxr.Sound:loadBinary (f) - Load the sound parameters from a file in the sfxr binary format + Load the sound parameters from a file in the sfxr binary format + (version 100, 101, 102) @@ -579,7 +580,7 @@ self.waveform
- (WAVEFORM) The base wave form + The base wave form (default SQUARE) @@ -610,7 +611,7 @@
Sustain time: - Time the sound sustains on its peak volume + Time the sound stays on its peak volume (default 0.0, min 0.0, max 1.0) @@ -987,6 +988,8 @@ a generator that yields the sample data when called +

Raises:

+ "invalid sample rate: x", "invalid bit depth: x"

Usage:

@@ -1017,6 +1020,8 @@ +

Raises:

+ "invalid sample rate: x", "invalid bit depth: x" @@ -1058,6 +1063,8 @@ the number of written samples (== #tab) +

Raises:

+ "invalid sample rate: x", "invalid bit depth: x" @@ -1099,13 +1106,15 @@ the number of written samples +

Raises:

+ "invalid sample rate: x", "invalid bit depth: x", "invalid endianness: x"
- sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, a]]]) + sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, sounddata]]])
Synthesize the sound to a LÖVE SoundData instance. @@ -1123,10 +1132,10 @@ the bit depth (default 0) -
  • a +
  • sounddata love.sound.SoundData - SoundData instance (will be created if - not passed) + a SoundData instance (will be + created if not passed) (optional)
    • @@ -1141,6 +1150,8 @@ the number of written samples +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x" @@ -1364,7 +1375,8 @@ +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x"
    - sfxr.Sound:save (f[, to=true]) + sfxr.Sound:save (f[, minify=true])
    Save the sound parameters to a file as a Lua table @@ -1395,11 +1409,12 @@ @@ -1421,11 +1436,14 @@ +

    Raises:

    + "incompatible version: x.x.x" @@ -1435,14 +1453,15 @@ sfxr.Sound:saveBinary (f)
    - Save the sound parameters to a file in the sfxr binary format + Save the sound parameters to a file in the sfxr binary format (version 102)

    Parameters:

    @@ -1457,17 +1476,21 @@
    Load the sound parameters from a file in the sfxr binary format + (version 100, 101, 102)

    Parameters:

    +

    Raises:

    + "incompatible version: x", "unexpected file length" @@ -1479,7 +1502,7 @@
    generated by LDoc 1.4.3 -Last updated 2016-03-02 00:35:01 +Last updated 2016-03-05 19:36:51
    diff --git a/doc/index.html b/doc/index.html index 4ee43d5..c0214f9 100644 --- a/doc/index.html +++ b/doc/index.html @@ -113,7 +113,7 @@ self.waveform - (WAVEFORM) The base wave form + The base wave form (default SQUARE) self.envelope.attack @@ -124,7 +124,7 @@ self.envelope.sustain Sustain time: - Time the sound sustains on its peak volume + Time the sound stays on its peak volume (default 0.0, min 0.0, max 1.0) @@ -272,7 +272,7 @@ Generate the sound to a binary string. - sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, a]]]) + sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, sounddata]]]) Synthesize the sound to a LÖVE SoundData instance. @@ -316,7 +316,7 @@ Generate and export the audio data to a PCM WAVE file. - sfxr.Sound:save (f[, to=true]) + sfxr.Sound:save (f[, minify=true]) Save the sound parameters to a file as a Lua table @@ -325,11 +325,12 @@ sfxr.Sound:saveBinary (f) - Save the sound parameters to a file in the sfxr binary format + Save the sound parameters to a file in the sfxr binary format (version 102) sfxr.Sound:loadBinary (f) - Load the sound parameters from a file in the sfxr binary format + Load the sound parameters from a file in the sfxr binary format + (version 100, 101, 102) @@ -579,7 +580,7 @@ self.waveform
    - (WAVEFORM) The base wave form + The base wave form (default SQUARE) @@ -610,7 +611,7 @@
    Sustain time: - Time the sound sustains on its peak volume + Time the sound stays on its peak volume (default 0.0, min 0.0, max 1.0) @@ -987,6 +988,8 @@ a generator that yields the sample data when called +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x"

    Usage:

    @@ -1017,6 +1020,8 @@ +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x" @@ -1058,6 +1063,8 @@ the number of written samples (== #tab) +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x" @@ -1099,13 +1106,15 @@ the number of written samples +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x", "invalid endianness: x"
    - sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, a]]]) + sfxr.Sound:generateSoundData ([rate=44100[, depth=0[, sounddata]]])
    Synthesize the sound to a LÖVE SoundData instance. @@ -1123,10 +1132,10 @@ the bit depth (default 0) -
  • a +
  • sounddata love.sound.SoundData - SoundData instance (will be created if - not passed) + a SoundData instance (will be + created if not passed) (optional)
    • @@ -1141,6 +1150,8 @@ the number of written samples +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x" @@ -1364,7 +1375,8 @@ +

    Raises:

    + "invalid sample rate: x", "invalid bit depth: x"
    - sfxr.Sound:save (f[, to=true]) + sfxr.Sound:save (f[, minify=true])
    Save the sound parameters to a file as a Lua table @@ -1395,11 +1409,12 @@ @@ -1421,11 +1436,14 @@ +

    Raises:

    + "incompatible version: x.x.x" @@ -1435,14 +1453,15 @@ sfxr.Sound:saveBinary (f)
    - Save the sound parameters to a file in the sfxr binary format + Save the sound parameters to a file in the sfxr binary format (version 102)

    Parameters:

    @@ -1457,17 +1476,21 @@
    Load the sound parameters from a file in the sfxr binary format + (version 100, 101, 102)

    Parameters:

    +

    Raises:

    + "incompatible version: x", "unexpected file length" @@ -1479,7 +1502,7 @@
    generated by LDoc 1.4.3 -Last updated 2016-03-02 00:35:01 +Last updated 2016-03-05 19:36:51
    diff --git a/sfxr.lua b/sfxr.lua index 838bfcf..cf30f27 100644 --- a/sfxr.lua +++ b/sfxr.lua @@ -270,7 +270,7 @@ function sfxr.Sound:resetParameters() -- Times to repeat the frequency slide over the course of the envelope -- (*default* 0.0, *min* 0.0, *max* 1.0) self.repeatspeed = 0.0 - --- (@{WAVEFORM|*WAVEFORM*}) The base wave form + --- The base @{WAVEFORM|wave form} (*default* @{WAVEFORM|SQUARE}) self.waveform = sfxr.SQUARE --- Attack time: @@ -278,7 +278,7 @@ function sfxr.Sound:resetParameters() -- (*default* 0.0, *min* 0.0, *max* 1.0) self.envelope.attack = 0.0 --- Sustain time: - -- Time the sound sustains on its peak volume + -- Time the sound stays on its peak volume -- (*default* 0.0, *min* 0.0, *max* 1.0) self.envelope.sustain = 0.3 --- Sustain punch: @@ -415,11 +415,12 @@ end -- @usage for s in sound:generate(44100, 0) do -- -- do something with s -- end +-- @raise "invalid sample rate: x", "invalid bit depth: x" function sfxr.Sound:generate(rate, depth) rate = rate or 44100 depth = depth or 0 - assert(sfxr.SAMPLERATE[rate], "Invalid sample rate: " .. tostring(rate)) - assert(sfxr.BITDEPTH[depth], "Invalid bit depth: " .. tostring(depth)) + assert(sfxr.SAMPLERATE[rate], "invalid sample rate: " .. tostring(rate)) + assert(sfxr.BITDEPTH[depth], "invalid bit depth: " .. tostring(depth)) -- Initialize all locals local fperiod, maxperiod @@ -691,9 +692,10 @@ end -- Does not take any other limits into account, so the returned count might be -- higher than samples actually generated. Still useful though. -- @tparam[opt=44100] SAMPLERATE rate the sample rate +-- @raise "invalid sample rate: x", "invalid bit depth: x" function sfxr.Sound:getEnvelopeLimit(rate) rate = rate or 44100 - assert(sfxr.SAMPLERATE[rate], "Invalid sample rate: " .. tostring(rate)) + assert(sfxr.SAMPLERATE[rate], "invalid sample rate: " .. tostring(rate)) local env_length = { self.envelope.attack^2 * 100000, --- attack @@ -711,11 +713,12 @@ end -- @tparam[opt] {} tab the table to synthesize into -- @treturn {number,...} the table filled with sample data -- @treturn int the number of written samples (== #tab) +-- @raise "invalid sample rate: x", "invalid bit depth: x" function sfxr.Sound:generateTable(rate, depth, tab) rate = rate or 44100 depth = depth or 0 - assert(sfxr.SAMPLERATE[rate], "Invalid sample rate: " .. tostring(rate)) - assert(sfxr.BITDEPTH[depth], "Invalid bit depth: " .. tostring(depth)) + assert(sfxr.SAMPLERATE[rate], "invalid sample rate: " .. tostring(rate)) + assert(sfxr.BITDEPTH[depth], "invalid bit depth: " .. tostring(depth)) -- this could really use table pre-allocation, but Lua doesn't provide that local t = tab or {} @@ -733,12 +736,13 @@ end -- @tparam[opt=0] ENDIANNESS endianness the endianness (ignored when depth == 8) -- @treturn string a binary string of sample data -- @treturn int the number of written samples +-- @raise "invalid sample rate: x", "invalid bit depth: x", "invalid endianness: x" function sfxr.Sound:generateString(rate, depth, endianness) rate = rate or 44100 depth = depth or 16 - assert(sfxr.SAMPLERATE[rate], "Invalid sample rate: " .. tostring(rate)) - assert(sfxr.BITDEPTH[depth] and depth ~= 0, "Invalid bit depth: " .. tostring(depth)) - assert(sfxr.ENDIANNESS[endianness], "Invalid endianness: " .. tostring(endianness)) + assert(sfxr.SAMPLERATE[rate], "invalid sample rate: " .. tostring(rate)) + assert(sfxr.BITDEPTH[depth] and depth ~= 0, "invalid bit depth: " .. tostring(depth)) + assert(sfxr.ENDIANNESS[endianness], "invalid endianness: " .. tostring(endianness)) local s = "" --- buffer for arguments to string.char @@ -778,15 +782,16 @@ end --- Synthesize the sound to a LÖVE SoundData instance. -- @tparam[opt=44100] SAMPLERATE rate the sample rate -- @tparam[opt=0] BITDEPTH depth the bit depth --- @tparam[opt] love.sound.SoundData a SoundData instance (will be created if --- not passed) +-- @tparam[opt] love.sound.SoundData sounddata a SoundData instance (will be +-- created if not passed) -- @treturn love.sound.SoundData a SoundData instance -- @treturn int the number of written samples +-- @raise "invalid sample rate: x", "invalid bit depth: x" function sfxr.Sound:generateSoundData(rate, depth, sounddata) rate = rate or 44100 depth = depth or 0 - assert(sfxr.SAMPLERATE[rate], "Invalid sample rate: " .. tostring(rate)) - assert(sfxr.BITDEPTH[depth] and depth, "Invalid bit depth: " .. tostring(depth)) + assert(sfxr.SAMPLERATE[rate], "invalid sample rate: " .. tostring(rate)) + assert(sfxr.BITDEPTH[depth] and depth, "invalid bit depth: " .. tostring(depth)) local tab, count = self:generateTable(rate, depth) @@ -1110,14 +1115,16 @@ function sfxr.Sound:randomBlip(seed) end --- Generate and export the audio data to a PCM WAVE file. --- @tparam ?string|file|love.filesystem.File f a file path, a Lua file object, a love.filesystem.File instance +-- @tparam ?string|file|love.filesystem.File f a path or file in `wb`-mode +-- (passed files will not be closed) -- @tparam[opt=44100] SAMPLERATE rate the sample rate -- @tparam[opt=0] BITDEPTH depth the bit depth +-- @raise "invalid sample rate: x", "invalid bit depth: x" function sfxr.Sound:exportWAV(f, rate, depth) rate = rate or 44100 depth = depth or 16 - assert(sfxr.SAMPLERATE[rate], "Invalid sample rate: " .. tostring(rate)) - assert(sfxr.BITDEPTH[depth] and depth ~= 0, "Invalid bit depth: " .. tostring(depth)) + assert(sfxr.SAMPLERATE[rate], "invalid sample rate: " .. tostring(rate)) + assert(sfxr.BITDEPTH[depth] and depth ~= 0, "invalid bit depth: " .. tostring(depth)) local close = false if type(f) == "string" then @@ -1216,9 +1223,10 @@ function sfxr.Sound:exportWAV(f, rate, depth) end --- Save the sound parameters to a file as a Lua table --- @tparam ?string|file|love.filesystem.File f a file path, a Lua file object, a love.filesystem.File instance --- @tparam[opt=true] whether to minify the output -function sfxr.Sound:save(f, compressed) +-- @tparam ?string|file|love.filesystem.File f a path or file in `w`-mode +-- (passed files will not be closed) +-- @tparam[opt=true] bool minify whether to minify the output or not +function sfxr.Sound:save(f, minify) local close = false if type(f) == "string" then f = io.open(f, "w") @@ -1243,14 +1251,14 @@ function sfxr.Sound:save(f, compressed) if obj ~= def then local k = table.concat(keys, ".") - if not compressed then + if not minify then code = code .. "\n" .. string.rep(" ", #keys - 1) end code = code .. string.format("%s=%s;", name, obj) end elseif type(obj) == "table" then - local spacing = compressed and "" or "\n" .. string.rep(" ", #keys - 1) + local spacing = minify and "" or "\n" .. string.rep(" ", #keys - 1) code = code .. spacing .. string.format("%s={", name) for k, v in pairs(obj) do @@ -1273,7 +1281,9 @@ function sfxr.Sound:save(f, compressed) end --- Load the sound parameters from a file containing a Lua table --- @tparam ?string|file|love.filesystem.File f a file path, a Lua file object, a love.filesystem.File instance +-- @tparam ?string|file|love.filesystem.File f a path or file in `r`-mode +-- (passed files will not be closed) +-- @raise "incompatible version: x.x.x" function sfxr.Sound:load(f) local close = false if type(f) == "string" then @@ -1290,9 +1300,7 @@ function sfxr.Sound:load(f) local params, version = assert(loadstring(code))() -- check version compatibility - if version > sfxr.VERSION then - error("Incompatible version: " .. tostring(version)) - end + assert(version > sfxr.VERSION, "incompatible version: " .. tostring(version)) self:resetParameters() -- merge the loaded table into the own @@ -1303,8 +1311,9 @@ function sfxr.Sound:load(f) end end ---- Save the sound parameters to a file in the sfxr binary format --- @tparam ?string|file|love.filesystem.File f a file path, a Lua file object, a love.filesystem.File instance +--- Save the sound parameters to a file in the sfxr binary format (version 102) +-- @tparam ?string|file|love.filesystem.File f a path or file in `wb`-mode +-- (passed files will not be closed) function sfxr.Sound:saveBinary(f) local close = false if type(f) == "string" then @@ -1360,7 +1369,10 @@ function sfxr.Sound:saveBinary(f) end --- Load the sound parameters from a file in the sfxr binary format --- @tparam ?string|file|love.filesystem.File f a file path, a Lua file object, a love.filesystem.File instance +-- (version 100, 101, 102) +-- @tparam ?string|file|love.filesystem.File f a path or file in `rb`-mode +-- (passed files will not be closed) +-- @raise "incompatible version: x", "unexpected file length" function sfxr.Sound:loadBinary(f) local close = false if type(f) == "string" then @@ -1394,7 +1406,7 @@ function sfxr.Sound:loadBinary(f) local version = s:byte(off) off = off + 4 if version < 100 or version > 102 then - return nil, "unknown version number "..version + error("incompatible version: " .. tostring(version)) end self.wavetype = s:byte(off) @@ -1435,7 +1447,7 @@ function sfxr.Sound:loadBinary(f) self.change.amount = readFloat() end - assert(off-1 == s:len()) + assert(off-1 == s:len(), "unexpected file length") end return sfxr