mod_slurp.lua

The Slurp Module for Corona SDK allows you to walk a list of URLs and get the first one with content. Skipping unresponsive endpoints, or network related site errors.

Preflight

Download Slurp!

Add the Slurp Module mod_slurp.lua to your Corona SDK project.

local Slurp = require('mod_slurp')

Usage

Using Slurp is pretty simple; you provide the module with a list of URLs and it will go through each one until it receives valid data. This can be useful for checking busy or unresponsive network endpoints.

There are only a handful of Slurp API methods:

---

Slurp:new( init_tbl )

Create a new Slurp instance.

Returns

A new Slurp instance.

Init Table

Key	Description	Default	Required
urls	A table array of URL strings to walk	nil	Yes
method	The default method that will be called on network events	"GET"	No
timeout	Amount of time in milliseconds before moving to the next URL	5000	No
onSuccess	The callback method when content has been captured	nil	No
onFailed	The callback when a URL fails to connect	nil	No
onError	The callback when a network error occurs	nil	No
onDone	The callback for when the queue has been emptied	nil	No
options	A table of options that mimics the network.request options	nil	No
debug	Show process debugging output in the console	false	No

Callback Parameters

onSuccess( content, url, status )

Name	Description	Type
content	The content that was found	String
url	The URL where it came from	String
status	The HTTP status code returned	Number

local onSuccess = function( content, url, status )
  print( content )
end

---

onFailed( url, status )

Name	Description	Type
url	The URL that failed	String
status	The HTTP status code returned	Number

local onFailed = function( url, status )
  print( status )
end

---

onError( url )

Name	Description	Type
url	The URL that threw the network error	String

local onError = function( url )
  print( "Error on " .. url )
end

---

onDone()

Called when the Slurp process is finished, whether content was found or not.

local onDone = function()
  print( "Done" )
end

---

Example

--== Load Slurp Module
local Slurp = require('mod_slurp')

--== Gather URLs
urls =
{
  'somemisplacedtext', --< not a url, fail
  'http://www.err4Borked.com', --< doesnt exist, fail
  'https://coronium.io', --< no cert on https, fail
  'http://www.coronium.io:9000', --< timeout, fail
  'https://www.google.com', --< Success! (99.9% of the time)
  'https://www.yahoo.com' --< won't fire unless Google is down
}

--== Create Network Callbacks
local onSuccess = function( content, url, status )
  print("SUCCESS")
  print( status )
  print( url )
  print( string.sub( content, 1, 500 ) ) --< trim for demo
end

local onFailed = function( url, status )
  print("FAILED")
  print( status )
  print( url )
end

local onError = function( url )
  print("ERROR")
  print( url )
end

local onDone = function()
  print("ALL DONE")
end

--== Create a new Slurp instance
local s = Slurp:new({
  urls = urls, -- Table array of URLs
  onSuccess = onSuccess, -- The callback on success
  onFailed = onFailed, -- The callback when no valid data is found
  onError = onError, -- A network error occurred
  onDone = onDone, -- The queue has finished running
  debug = true -- Show debug output in the console
})

--== Run the Slurp instance
-- Results are returned in the
-- network callback functions
s:run()

---

slurp:run()

Starts running the Slurp process, checking sites for connectivity and results. You can run this anytime after giving the queue at least one URL.

Returns

Events through the callback methods passed in when the instance was created (see :new() above).

Parameters

None

Example

...

--Create and set up the instance
local s = Slurp:new( ... )

--Run the instance
s:run()

---

slurp:cancel()

While Slurp generally handles its own life-cycle, in situations where you need a full-stop, you can use this method.

Returns

Nothing

Parameters

None

Example

...

--Halt the Slurp instance from anymore processing.
s:cancel()

---

slurp:count()

The current amount of entries left in the Slurp queue.

Returns

A Number

Parameters

None

Example

...

--Get the current queue count
local q_cnt = s:count()

---

Summary Notes

Once you put together the URL queue, as in the example above, and set up the callbacks, we run the queue. By default, once the first successful result is found, Slurp stops processing that instance and triggers the supplied onSuccess callback, if any.

Timeouts are not based on the normal network timeout, but an actual timer instance. This provides more flexibility in moving through your queue. For instance, instead of waiting N seconds for the network timeout, you can decide to move on to the next URL at any amount of time of your choosing. This can be adjusted when creating a new Slurp instance.

If Slurp runs into network or http errors, it will skip to the next URL in the queue, if any. The timeout is disregarded in these cases.

Visit the Corona Labs forums with any questions.

---