Internet library syntax discussion

LiveCode Builder is a language for extending LiveCode's capabilities, creating new object types as Widgets, and libraries that access lower-level APIs in OSes, applications, and DLLs.

Moderators: LCMark, LCfraser

trevordevore
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 1005
Joined: Sat Apr 08, 2006 3:06 pm
Location: Overland Park, Kansas
Contact:

Internet library syntax discussion

Post by trevordevore » Fri Jun 05, 2015 3:58 pm

I would like to start a discussion on features and syntax for the internet library that will be written in LCB at some point. My goal is to flesh out the features and syntax that developers need ahead of time in order to speed things along when it comes time to actually write the library. In this day and age, the internet library is one of the most important aspects of a development tool. I want to help make sure that the internet library in LiveCode is top notch. This first post is what I've come up with so far. I'm interested in other thoughts and approaches as well.

First, here is a list of things I've wanted in an internet library API over the years.
  • Send any type of HTTP request. HEAD is the obvious one missing from libURL. PATCH is also missing but I've never had to use that myself.
  • Define status callbacks on a per-request basis. Any request with a callback becomes asynchronous.
  • If a callback is defined, all progress and completion information is sent to the defined callback. All error reporting is sent to the callback as well, not in the result right after the call.
  • Define headers on a per-request basis. No global httpHeaders property.
  • Allow the developer to associate an id with a request so that it can be associated with other data structures in callbacks. Sometimes the URL being used is the exact same for multiple requests and the only thing that changes is the data being sent along with the request.
  • Each request should be identified using a unique id rather than the URL itself. No errors about a url already being loaded.
Personally I don't think I would ever use the synchronous versions except when testing something. It seems more friendly to have both the async/sync capabilities.

I've been thinking about syntax for interacting with a server and here is what I like the most so far:

Code: Select all

send [METHOD] request to url [URL] [with headers HEADERS] [with data DATA] [with callback CALLBACK] [with id ID]
Here are some examples:

Code: Select all

-- Synchronous call which defaults to GET
send request to url tURL

-- Asynchronous GET request
send GET request to url tURL with callback "MyCallback"

-- Synchronous PUT request with custom headers and data sent to the server.
send PUT request to url tURL with headers tHeaders with data tData

-- Asynchronous POST  request with custom headers and data sent to the server.
send POST request to url tURL with data tData with callback "MyCallback"

-- Async HEAD request
send HEAD request to url tURL with callback "MyCallback"

-- Async DELETE request
send DELETE request to url tURL with callback "MyCallback"

-- Pass along a parameter that associates this request with something in our app
-- Also group the URLs using different callbacks.
send GET request to URL tURL1 with callback "CallbackCategory1" with id 2500
send GET request to URL tURL2 with callback "CallbackCategory1" with id 2501
send GET request to URL tURL3 with callback "CallbackCategory2"
Trevor DeVore
ScreenSteps - https://www.screensteps.com

LiveCode Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode
LiveCode Builder Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode-builder

SparkOut
Posts: 2839
Joined: Sun Sep 23, 2007 4:58 pm

Re: Internet library syntax discussion

Post by SparkOut » Fri Jun 05, 2015 7:11 pm

I like the generalisation, but I'm not a fan of "send get request" or "send post request" . I think "get url" and "post tData to url" are much more natural and in keeping with the LC language paradigm.

I've always felt subconsciously that anything involving "send" is either a time based thing, or is bending the natural order and flow of things. I don't like it the same way BASIC coders don't like GOTO. Just me.

trevordevore
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 1005
Joined: Sat Apr 08, 2006 3:06 pm
Location: Overland Park, Kansas
Contact:

Re: Internet library syntax discussion

Post by trevordevore » Fri Jun 05, 2015 7:19 pm

SparkOut wrote:I like the generalisation, but I'm not a fan of "send get request" or "send post request" . I think "get url" and "post tData to url" are much more natural and in keeping with the LC language paradigm.
<send request> may not be the best syntax but I do think it would be better to have a root syntax (like <send request>) that all URL operations build off of. I was amazed at how many people had no idea you could use <put ... into URL tURL> to make a PUT request. The same for <delete URL tURL>. And what would HEAD look like? <head to URL≥? I don't think the syntax is really expressive of what is actually being done. Also look at <get url> and <put url into ...> Both make a GET request to the server. I think that is more confusing.

<post to url> works for me but I don't care for <delete URL tURL> because you don't really delete a URL. You are sending a request to the server to delete something.
Trevor DeVore
ScreenSteps - https://www.screensteps.com

LiveCode Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode
LiveCode Builder Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode-builder

trevordevore
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 1005
Joined: Sat Apr 08, 2006 3:06 pm
Location: Overland Park, Kansas
Contact:

Re: Internet library syntax discussion

Post by trevordevore » Fri Jun 05, 2015 7:23 pm

SparkOut wrote:I've always felt subconsciously that anything involving "send" is either a time based thing, or is bending the natural order and flow of things. I don't like it the same way BASIC coders don't like GOTO. Just me.
I will also point out that there is already a precedent for using <send request to url>. Look at <send message to application> in the dictionary. I think your point about going out of the natural order and flow of things is appropriate. We are send to contact an outside server|object|application.
Trevor DeVore
ScreenSteps - https://www.screensteps.com

LiveCode Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode
LiveCode Builder Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode-builder

SparkOut
Posts: 2839
Joined: Sun Sep 23, 2007 4:58 pm

Re: Internet library syntax discussion

Post by SparkOut » Fri Jun 05, 2015 7:29 pm

Hmm, I think that <put url into ...> translates to <put someDataWhichHappensToBeTheReturnedStuffFromaGetRequestToUrl into ...> rather than anything to do with PUT requests to http services.
You are right that a root syntax for libUrl equivalents is desirable. I'm happy with get url and post to url as is at the moment. Anything more specific certainly needs a consistent way of making the requests.
I'd be more inclined to avoid send ... request and think towards something like

REQUEST url METHOD <get|post|head|put|delete> [with headers HEADERS] [with data DATA] [with callback CALLBACK] [with id ID]

with a default method of get

trevordevore
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 1005
Joined: Sat Apr 08, 2006 3:06 pm
Location: Overland Park, Kansas
Contact:

Re: Internet library syntax discussion

Post by trevordevore » Fri Jun 05, 2015 7:40 pm

SparkOut wrote:Hmm, I think that <put url into ...> translates to <put someDataWhichHappensToBeTheReturnedStuffFromaGetRequestToUrl into ...> rather than anything to do with PUT requests to http services.
The <put> syntax has some subtle differences which give very different results. My apps interact with REST services so I've used the syntax quite a bit.

<put URL tURL into tVariable> sends a GET request to the server.
<put tVariable into URL tURL> sends a PUT request to the server.
SparkOut wrote:REQUEST url METHOD <get|post|put|delete> [with headers HEADERS] [with data DATA] [with callback CALLBACK] [with id ID] with a default method of get
That could work. I think it would need a bit of a tweak though. If written out it looks like this:

Code: Select all

REQUEST "http://livecode.com" METHOD POST with data DATA with callback CALLBACK
That doesn't look very english-like to me. You could use:

Code: Select all

REQUEST url "http://livecode.com" with method POST with data DATA with callback CALLBACK
I looked at using REQUEST, DOWNLOAD, UPLOAD, etc. while thinking this over. I went with <SEND> because I like how <send post request to URL tURL> reads. The method just slips right in there between <send> and <request>.
Trevor DeVore
ScreenSteps - https://www.screensteps.com

LiveCode Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode
LiveCode Builder Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode-builder

SparkOut
Posts: 2839
Joined: Sun Sep 23, 2007 4:58 pm

Re: Internet library syntax discussion

Post by SparkOut » Fri Jun 05, 2015 7:48 pm

Yeah, if there is a default GET method and the order of optional arguments is flexible then

Code: Select all

REQUEST url "http://livecode.com"
works, with extendability of the statement such as

Code: Select all

REQUEST url "http://livecode.com" with method POST with data DATA with id ID with callback CALLBACK
The returned data would be found in the "it" variable? I'm happy enough with that (I don't like <put request url "http://livecode.com" into tHtmlData>)

trevordevore
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 1005
Joined: Sat Apr 08, 2006 3:06 pm
Location: Overland Park, Kansas
Contact:

Re: Internet library syntax discussion

Post by trevordevore » Fri Jun 05, 2015 7:53 pm

I think returned data could go into <it>. I've never been a big fan of <it> as it confused me to no end when I was trying to learn LiveCode back in the day. I would read code and be like, "Where in the world did this <it> come from?". I've come to terms with it now though :-)
Trevor DeVore
ScreenSteps - https://www.screensteps.com

LiveCode Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode
LiveCode Builder Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode-builder

SparkOut
Posts: 2839
Joined: Sun Sep 23, 2007 4:58 pm

Re: Internet library syntax discussion

Post by SparkOut » Fri Jun 05, 2015 7:58 pm

Where else would it (returned data) go in order to be used apart from <it>?
I am always conscious of the volatility of <it> but have got very used to it.
I still prefer things like

Code: Select all

create card
put it into tNewCardId
set the name of tNewCardId to "New Card"
which is, of course, completely redundant use of a variable. The paradigm, I believe, is to have an "English-like" syntax where you could

Code: Select all

create card
set the name of it to "New Card"
where <it> naturally follows the English usage.
trevordevore wrote:I looked at using REQUEST, DOWNLOAD, UPLOAD, etc. while thinking this over. I went with <SEND> because I like how <send post request to URL tURL> reads. The method just slips right in there between <send> and <request>.
It reads nicely, but... I'm fussy about <SEND>. Just as there is a value in having <DISPATCH> I think there is a value in having an alternative to (avoiding the use of) <SEND> for new libUrl developments.

SparkOut
Posts: 2839
Joined: Sun Sep 23, 2007 4:58 pm

Re: Internet library syntax discussion

Post by SparkOut » Fri Jun 05, 2015 8:17 pm

What about even

Code: Select all

REQUESTURL "http://livecode.com" with method METHOD [etc]

[edit]I don't like this already[/edit]

But I'd like to know what others think, of the whole discussion.

trevordevore
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 1005
Joined: Sat Apr 08, 2006 3:06 pm
Location: Overland Park, Kansas
Contact:

Re: Internet library syntax discussion

Post by trevordevore » Sat Jun 06, 2015 5:12 pm

SparkOut wrote:Where else would it (returned data) go in order to be used apart from <it>?
I almost completely forgot about this topic regarding <the result> and <it>:

http://forums.livecode.com/viewtopic.php?f=93&t=23649

In it @LCMark discusses how <it> is often used for sideline return values. In the case of requesting a URL you are probably interested in the return value, however so <it> probably isn't the best use. Based on the discussion we had in that thread here are some possibilities for synchronous requests (doesn't apply to async requests):

Code: Select all

request url "http://www.livecode.com" into tReturnedData

Code: Select all

request url "http://www.livecode.com"
put the requested data into tReturnedData
or maybe this:

Code: Select all

put url request "http://livecode.com" with headers tHeaders into tReturnedData
put url post request "http://livecode.com" with headers tHeaders into tReturnedData
SparkOut wrote:The paradigm, I believe, is to have an "English-like" syntax where you could

Code: Select all

create card
set the name of it to "New Card"
where <it> naturally follows the English usage.
Another approach to this would be the following:

Code: Select all

create card
set the name of the new card to "New Card"
Trevor DeVore
ScreenSteps - https://www.screensteps.com

LiveCode Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode
LiveCode Builder Repos - https://github.com/search?q=user%3Atrevordevore+topic:livecode-builder

SparkOut
Posts: 2839
Joined: Sun Sep 23, 2007 4:58 pm

Re: Internet library syntax discussion

Post by SparkOut » Sat Jun 06, 2015 5:31 pm

maybe

Code: Select all

request url "http://www.livecode.com" with method post with data tData with returnvar tReturnedData
or some other designator for the returned value argument.

Although rereading that thread does make it clearer how to conceptualise <request url tUrl into tVar>. I am far happier about that than the idea of <send post request to tUrl...>

Martin Koob
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 256
Joined: Sun May 27, 2007 8:19 pm

Re: Internet library syntax discussion

Post by Martin Koob » Sun Jun 07, 2015 4:10 pm

trevordevore wrote:
SparkOut wrote:Where else would it (returned data) go in order to be used apart from <it>?

or maybe this:

Code: Select all

put url request "http://livecode.com" with headers tHeaders into tReturnedData
put url post request "http://livecode.com" with headers tHeaders into tReturnedData

Just a spectator here on this thread but I like this format the best.

Martin

jacque
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 7214
Joined: Sat Apr 08, 2006 8:31 pm
Location: Minneapolis MN
Contact:

Re: Internet library syntax discussion

Post by jacque » Sun Jun 07, 2015 5:42 pm

Just my 2 cents, the "send" syntax doesn't bother me at all and seems in line with our normal usage of the term. Send is not just for timing, it is also used to send commands to objects.

Code: Select all

send "mouseUp"  to btn 1
To me that seems no different than sending to a server.
Jacqueline Landman Gay | jacque at hyperactivesw dot com
HyperActive Software | http://www.hyperactivesw.com

peter-b
Posts: 182
Joined: Thu Nov 20, 2014 2:14 pm
Location: LiveCode Ltd.

Re: Internet library syntax discussion

Post by peter-b » Mon Jun 08, 2015 9:04 am

This seems like a useful discussion.

Two things:

1. Assume that "it" and "the result" don't exist in LiveCode Builder.

2. Don't forget about PATCH. :wink:

Edit: I've been writing quite a lot of web service interaction stuff in LCB recently and I'd really like to have a good Internet library. Unfortunately we're not quite at the point where it's easy to do things involving asynchronous requests in LCB.
LiveCode Open Source Team — @PeterTBBrett — peter.brett@livecode.com

Post Reply

Return to “LiveCode Builder”