Version: 0.0.8 31-Jan-2006 Sunanda
probe lds/send-server 'get-user-list []
make object! [
status: [0 0 "]
data:
make object! [
user-list: ["gregg" "volker" "sunanda"]
]
]
What comes back is a REBOL object with just two fields: Run it directly from the REBOL.org server:
do http://www.rebol.org/library/public/lds-local.r
That's all it takes.
Issue this call once before you call the service:
do http://www.rebol.org/library/public/lds-local.r
response-data: lds/send-server 'request [parameters]
A Library token is needed if you are doing something at the Member or Owner level.
Getting a token is explained later (see Library Tokens).
A call using a token looks like this:
response-data: lds/send-server/use-token 'request [parameters]
probe lds/send-server 'list-updated-scripts ["zzzzz"]
make object! [
status: [200 0 "non-integer days"]
data: none
]
(zzzzz should be an integer)
probe lds/send-server 'get-script ["xxxx.r"]
make object! [
status: [300 0 "unknown script"]
data: none
]
(xxxx.r is not a script in the Library)
probe lds/send-server 'get-script ["sssss.r"]
make object! [
status: [400 0 "can't connect"]
data: none
]
(You may be offline) To use some LDS requests, you must be a member of the Library.
If you are not a member of the Library, you can join by going here:
http://www.rebol.org/cgi-bin/cgiwrap/rebol/signup.r
LDS needs you to supply a Library token on each call. This identifies who you are in much the same way that a cookie does when you visit the Library using the web interface.
Log on, and visit this page:
http://www.rebol.org/cgi-bin/cgiwrap/rebol/lds-library-tokens.r
Tell it how many tokens you want (one is normally enough -- see multiple tokens below for why you may want more than one) and click "send me tokens" .
The tokens will be emailed to your registered address.
A token looks something like this:
#{00C04C0913E76ECFF780DD73}
Save it as a text file called lds-library-token.txt in the folder from which you execute Library Data services, eg:
write %lds-library-token.txt mold #{00C04C0913E76ECFF780DD73}
The token is now ready for use.
Add the /use-token refinement to each lds/send-server request, eg:
Response-object: lds/send-server/user-token 'token-test ["test my token"]
If you use LDS from more than one location (perhaps on different machines) you need a different token for each location. You can have as many tokens as you want.
Returns a list of all LDS requests and some help on each of them -- a good way to see if you have an out-of-date copy of these notes.
probe lds/send-server 'help none
make object! [
status: [0 0 "]
data:
make object! [
request-list: [
"get-rml-message"
make object! [
authorisation?: false
purpose: {Retrieve a message from the REBOL Mailing list archive}
parameters: "Msgid [integer!]"
response: "Object containing message and control headers"
]
"get-script"
make object! [
[snip]
Retrieve list of activated Library members
("activated" means they have logged on at least once)
probe lds/send-server 'list-users []
make object! [
status: [0 0 "]
data:
make object! [
user-list: ["volker" "gregg" "sunanda"]
]
]
Use these requests to read messages from the Mailing list archive
Retrieve a message from the REBOL Mailing list archive
probe res: lds/send-server 'get-rml-message [237859]The fields in the data object for this request are:
msgs: copy []
res: lds/send-server 'get-rml-message [213498]
forever [
append msgs res/data
if res/data/links/3 = 0 [break] ;; no next-in-thread link
res: lds/send-server 'get-rml-message reduce [res/data/links/3]
]
print ["There were" length? msgs "message(s) in the thread"]
msgs: copy [] res: lds/send-server 'get-rml-message ["latest"]
Sends you back some status information about the Mailing list archive.
probe res: lds/send-server 'get-rml-status []
make object! [
status: [0 0 "]
data:
make object! [
counts: [241337 241337]
threads: [8706]
years: [1980 2000 2001 2002 2003 2004 2005 2024]
]
The fields in the data object for this request are: get-rml-status is most useful for getting the full span of years for a search-rml request....See immediately below.
Sends you back the message ids for all threads that meet your search criteria
The parameter is a single quoted string. It should contain at least one word on which you want to search. It may also contain one or more years.
Contains both the message ids of the messages that matched your search, and some reflected back fields to confirm what has been searched.
An example is
make object! [
status: [0 0 "]
data:
make object! [
target-words: ["apple" "pink" "white"]
search-type: "posts"
span: [2003 2002 2001 2000]
msgids: [207276]
]
]
Using the search-rml request, you can search on all years for which threads exist. This includes some strange ones, such as 1980 and 2024. They exist because we take the date field in the original email's header as correct. and, obviously, in some cases they were not: the sender's ISP or server was badly set up.
We don't have much choice about that. The Mailing list archive started some years after the Mailing list, so we don't have accurate context information to correct the problem.
probe lds/send-server 'search-rml ["async version"]
make object! [
status: [0 0 "]
data:
make object! [
target-words: ["async" "version"]
search-type: "subjects"
msgids: [234122]
]
]
probe lds/send-server 'search-rml ["1960 1961 help me to get a good job 2004 2003"]
make object! [
status: [0 0 "]
data:
make object! [
target-words: ["get" "good" "help" "job" "me"]
search-type: "posts"
span: [2004 2003]
msgids: [230329 230451 ....snipped .....]
]
]
Note that the span contains only the years we could search (we don't have messages from the 1960s), and the target-words does not include the stop words "to" and "a".
Use these requests to search the Script Library, and to download scripts.
Retrieve latest version of a script
Returns the source of the named script
probe lds/send-server 'get-script ["wumpus.r"]
make object! [
status: [0 0 "]
data:
make object! [
script: {REBOL[
Title: "Hunt the Wumpus"
Date: 20-Jul-2003
File:^- %wumpus.r
Purpose: "A REBOL version of a retro text game. Just for fun."
Author: "Gregg Irwin"
EMail: greggirwin@acm.org
Version: 1.0.1
Library: [
level: 'intermediate
platform: 'all
[snip]
If you own a script, and check its download count on the statistics page of REBOL.org: LDS get-script downloads are counted as "Total LDS downloads" .
Returns a list of script names that match the search filter.
probe lds/send-server 'list-scripts-by-filter [domain-xml]
make object! [
status: [0 0 "]
data:
make object! [
script-list: ["json.r" "xmlgen.r" "rblxelparser.r"]
]
]
Returns an object with all the possible filters that can be used with list-scripts-by-filter
The response object has a series of blocks, each represents a possible set of filters, for example
type: [article demo dialect faq function ... ]
means you can filter on type-article type-demo etc
Returns a list of script names that contain the words you asked for
probe lds/send-server 'search-scripts ["decompress"]
make object! [
status: [0 0 "]
data:
make object! [
script-list: ["compress.r" "autoextract.r"]
]
]
The script-list returned is in script relevance order: best matches first.
Returns a list of scripts owned by a given Library member
If the owner name is not recognised, the script-list is returned as an empty block.
probe lds/send-server 'list-scripts-owned-by ["sunanda"]
make object! [
status: [0 0 "]
data:
make object! [
script-list: ["cookie-example.r" "oneliner-chess-board.r"
"oneliner-monty-hall.r"]
Get a list of new or updated scripts in the last [n] days
Lets you find which scripts have been added or updated in the last n days. n is an integer: 1 or more
probe lds/send-server 'list-updated-scripts [15]
make object! [
status: [0 0 "]
data:
make object! [
script-list: ["mtv.r" "mvt.r" "mvs.r"]
]
]
res1: lds/send-server 'list-updated-scripts [31] foreach scr res1/data/script-list [ res2: lds/send-server 'get-script reduce [scr] write to-file scr res2/data/script ]
Use these requests to get archived versions of scripts (each time a script owner updates a script, we put the previous version in the archive. In some cases, the previous versions remain available for download).
REBOL.org usually only shows the latest version of each script. Previous versions may still be available. This request returns a list of all publicly available versions of a script.
probe lds/send-server 'list-archive-versions [demo1.r]
make object! [
status: [0 0 "]
data:
make object! [
archive-versions: [
[7 15-Mar-2004 "Fixed bug in header"]
[12 28-Apr-2004 "Version 2.0 -- supports IOS"]
]
]
]
In the above example, there are two publicly-available versions of the script: 7 and 12. The version number is an internal number to the Library. It will usually be different to the owners' version number in the script itself.
The highest version number show will always be the current live version of the script. Lower numbered entries are back-versions of the script that the owner has left publicly available.
To retrieve an archive version of a script use the request get-archive-version.
Retrieve an archived version of a script (see list-archive-versions for more details)
Get archive version 17 for script demo1.r:
probe res: lds/send-server 'get-archive-version ["demo1.r/17"]
make object! [
status: [0 0 "]
data:
make object! [
script: #{
789CC551C14AC34010BDEF574C03524592565191F46015EB410445C54BE86193
snip
ED800F8DA6768B8BCD39E0D9FE255DA877CE25EAB52D030000
}
]
]
demo1.r has a publicly available version 17, so it has been returned:
Get archive version 14 for script demo1.r:
probe res: lds/send-server 'get-archive-version ["demo1.r/14"]
make object! [
status: [301 "demo1.r" "not available"]
data: none
diagnostics: [41641 33710 0.11]
]
Version 14 of demo1.r is nor publicly available. If you need that exact version, contact the owner and ask them to make it available.
Use this request to either add a new script to the Library; or update an existing script that you own.
Are a dialect with these words: mode, note, and script. Mode and script must always be present. Note is optional.
note "changed error handling" mode check script {rebol [file: %zzz.r .....}
scr: {rebol [] quit}
response-object: lds/send-server/use-token 'contribute-script
compose [mode "check" note "fix error handling" script (scr)]
This example does not send an acceptable script! This is what you'd get back:
Probe response-object
make object! [
status: [210 30 "problems with script"]
data:
make object! [
validation: ["file" "We need a File: field in the REBOL header."
"title" "We need a Title: field in the REBOL header."
"date" {The Date: field in the REBOL header needs to be a valid REBOL
date. (Not none)}
"purpose" "We need a Purpose: string in the REBOL header."]
]
]
Retrieve the documentation for a script, either as HTML or in its editable format
probe res: lds/send-server 'get-script-documentation ["lds-
local.r/editable"]
make object! [
status: [0 0 "]
data:
make object! [
documentation: #{
789CED7D6977DBD6D9E077FF8A1BF6742C69448AE04E2675476BDF74ECC68D9D
E4EDE8B8E7402428210601160045AB99FCF77996BB622129937E9BCE8CCE492C
91C05D9EFBECDBFDC617B1BF08FED0C89369D36BBCFAE6CC7FF5CD43E7D5EBF0
2EF5D32771E5E7BE7817A48FE134C8BE39836F04FD7C330B1FC534F2B38C5E85
[snip]
print decompress res/data/documentation
[h2 Library Data Services
[contents
[asis
Version: 0.0.5
12-Sep-2004
Sunanda
[snip]
If you own a script, and check its download count on the statistics page of REBOL.org: LDS get-script downloads are counted as "Total LDS downloads" .
Use these requests to get information about a script that is only available to the script owner.
Returns the list of scripts that you own. Similar to list-scripts-owned-by, but you identify yourself by using a Library token.
response-object: lds/send-server/use-token 'list-my-scripts []
Returns owner statistics for the script -- only available if you own the script.
response-object: lds/send-server/use-token 'get-script-stats [lds-local.r]
Use these requests to query or retrieve files from packages.
There is a also special LDS utility that makes working with packages easy:
do http://www.rebol.org/library/public/repack.r
Retrieve the header for a package -- i.e. the index to that package.
The package may not exist, or may not be available. See http://www.rebol.org/cgi-bin/cgiwrap/rebol/boiler.r?display=lds-package-dow nloader-help.html for a list of the package error messages
probe res: lds/send-server 'get-package-header ["lds-demo1-package.r"]
make object! [
status: [0 0 "]
data:
make object! [
user-notes: {Run lds-demo1.r under REBOL/View and see if you can
Spot The Developer!}
package-file-list: [
make object! [
file-name: "image1.jpg"
cgi-type: "image/pjpeg"
install-folder: "images/"
file-type: "file"
version: 0.0.4
last-updated: 17-Apr-2004/16:17:19.39+1:00
notes: "
checksum: #{4001620992AE7B6974F159A6D957571CD1558E36}
file-size: 17165
compressed-size: 12573
]
make object! [
file-name: "image2.jpg"
cgi-type: "image/pjpeg"
install-folder: "images/"
file-type: "file"
version: 0.1.0
notes: "
checksum: #{B76028C7C1D1DFFF2584788BEC82B8F7A8B55C07}
file-size: 75276
compressed-size: 39052
]
etc -- one entry per file
This means that the file is itself another package. That probably means that his package requires all the files from that package to be downloaded for a complete installation.
The package header for the current package does not include all the files for the included package. If you are writing a package installer or downloader you may need to take into account file-type:package. If you do, issues include:
Retrieve one file from a package
probe res probe res: lds/send-server 'get-package-file
["lds-demo1-package.r/notes.txt"]
make object! [
status: [0 0 "]
data:
make object! [
file: #{
789C7552D16ED3500C7D8F947F70DF3AD4A06D8C017B63A39B040C101DF0EC24
6E7AD5C48E1CA7617F8FEF6DD6371429B24F7C8E8FEDE4599EDDB5A1DA83096C
0CD5F26C89AD15D50B3898F46779F6BF67D38B81ED087EAE6FBF7F859A0ED44A
snip
074DF93BCF8F8B9881F70EA41B9DFEB6237F9567171F8A7B2A8BCBF3F3AB3CFB
07C289D8E6C6020000
}
]
]
The file as returned is compressed:
decompress res/data/file
{^M
^M
Click to Start^M
(alt-click to stop)^M
^M
^M
^M
^M
Spot the REBOL developer!^M
To save it, and lose all those ^M thingies in a text file, always save the file as binary:
write/binary %notes.txt decompress res/data/file print read %notes.txt Click to Start (alt-click to stop)
Saving the file as binary is always the correct thing to do: the file may be a JPG or executable, or some other non-text format.
A package is a multi-file unit that makes up one contribution to the Library.
From a user's perspective, it is three things:
All the LDS requests for uploading or updating packages will need a Library token.
Again, as with the contribute-script request, there is a mode parameter on every request.
To create a full and usable package, several requests (perhaps many) have to be issued and succeed. If the server or the client fail part-way through, there will be an incomplete or unusable package left on public view.
This is not so different from when a user is uploading files by hand to create a package -- their connection could fail at any point. I just mention in it case LDS clients want to get clever with some restart code.
LDS itself will not be offering any sort of journaling or rollback. It sees and actions individual requests.
Use contribute-script request to upload a new script. Include 'package in the Library header 'type field.
After successfully contributing a new script, various automated mechanisms start telling the world the good news (email notices, RSS feed, "what's new" pages, etc)
So some quick off-the-mark people may be looking at the new package before we've uploaded all the files. Nothing much we can do about that. It's part of the way packages were implemented as a bolt-on.
Use this request to:
Use this request for each of your files that are part of the package.
Use this request for any existing Library scripts that are part of the package.
Use this again to set the package as available . People can now download your new package.
If you later need to change the package, use these steps:
Set the package as unavailable to prevent people accidentally downloading an incomplete or inconsistent package
To add new files or update existing ones
To remove a file from the package
To include additional Library scripts in the package
To remove a Library script from the package.
Use this again to set the package as available . People can now download your updated package.
Use this request to add or update the header details of a package
Are a dialect with four words : mode, script-name and status and user-notes
A data object that normalises the dialect -- if you had any fields missing or with unacceptable values, you can see from the response what we assumed.
A full request looks something like:
lds/send-server/use-token 'update-package-header
[script-name "example-package.r"
mode "update"
status "private"
user-notes "Only works on MACs"
]
(As with all these requests, the order of the keywords in the dialect does not matter)
These following examples stand in for a lot of detailed exposition about error checking and what we do with bad requests.
The data section of the response is the internal, normalised dialect words -- so you can see how LDS-server has interpreted missing or bad data:
probe lds/send-server/use-token 'update-package-header [
script-name "example-package.r"
mode "update"
]
make object! [
status: [300 0 "unknown script"]
data:
make object! [
script-name: "example-package.r"
mode: "update"
status: none
user-notes: none
]
]
Problem: no such script. Expect similar errors for:
probe lds/send-server/use-token 'update-package-header [
script-name "example-package.r"
user-notes "zzz"
]
make object! [
status: [0 0 "]
data:
make object! [
script-name: "example-package.r"
mode: "check"
status: none
user-notes: "zzz"
]
]
Appears to have worked (got a 0 response), but the missing mode was taken as check -- so no changes made.
lds/send-server/use-token 'update-package-header [
script-name "example-package.r"
mode "do it"
user-notes "zzz"
]
make object! [
status: [0 0 "]
data:
make object! [
script-name: "example-package.r"
mode: "check"
status: none
user-notes: "zzz"
]
]
Mode is bad (not check or update ) -- treated as its safest value, check . Again, no update.
probe lds/send-server/use-token 'update-package-header [
script-name "example-package.r"
mode "update"
user-notes "zzz"
]
make object! [
status: [0 0 "]
data:
make object! [
script-name: "example-package.r"
mode: "update"
status: none
user-notes: "zzz"
]
]
This one worked. It updated the user notes, but did not change the status (because none was specified).
lds/send-server/use-token 'update-package-header [
script-name "example-package.r"
mode "update"
status "confused"
]
make object! [
status: [0 0 "]
data:
make object! [
script-name: "example-package.r"
mode: "update"
status: "private"
user-notes: none
]
]
This one worked, but may not have done what you expected. There was a status, but it was a bad value (neither private or public ) we normalised it to private that being the safest value. The user notes remain unchanged.
probe lds/send-server/use-token 'update-package-header [
script-name "example-package.r"
mode "update"
status "public"
user-notes "
]
make object! [
status: [0 0 "]
data:
make object! [
script-name: "example-package.r"
mode: "update"
status: "public"
user-notes: "linux only"
]
]
Changes the status to public and sets the user notes to "
Use this to add or update details of a file in the package
Are a dialect with these words: mode, script-name, file-name, install-folder, user-notes, version, contents, and checksum. Mode, script-name and file-name must always be present
probe lds/send-server/use-token 'upload-package-file
[script-name "example-package.r"
mode "update"
file-name "image-1.jpg"
install-folder "images/"
user-notes "Photo of Fluffy Bunny"
version "0.0.5"
contents #{...binary field...}
checksum #checksum/secure of contents (to detect in-flight damage)
]
Uploads a new file (or completely replaces the details of an existing one)
lds/send-server/use-token 'upload-package-file
[script-name "example-package.r"
mode "update"
file-name "image-1.jpg"
install-folder "my/images/"
user-notes "Better Photo of Fluffy Bunny"
version "1.0.5"
]
Will change the install-folder, user-notes and version
lds/send-server/use-token 'upload-package-file
[script-name "example-package.r"
file-name "image-1.jpg"
mode "update"
user-notes "Even better Photo of Fluffy Bunny"
]
Will change just the user notes.
Upload-package-file returns the normalised dialect, but the contents field is set to [omitted] -- no point sending back a 5meg file, or however large the file is.
Use this to include an existing Library script in the package. Note that you don't upload the script (after all, we already have it). You just tell us to make it part of the package.
Are a dialect with these words: mode, script-name, file-name, install-folder, library-script-name.
lds/send-server/use-token 'include-script-in-package
[script-name "example-package.r"
mode "update"
library-script-name: "convert-base.r"
install-folder "lib-scripts/"
]
Use this to remove a file you have uploaded to a package.
Are a dialect with these words: mode, script-name, file-name, and install-folder.
lds/send-server/use-token 'remove-file-from-package
[script-name "example-package.r"
mode "update"
install-folder: "
file-name "image-1.jpg"
]
image-1.jpg will not be a part of the package after this request is run. (Note: this does not mean it was a part of the package before; but, if it was, it isn't now)
Use this to remove a Library script from the package.
Are a dialect with these words: mode, script-name, file-name, install-folder, library-script-name.
lds/send-server/use-token 'remove-script-from-package
[script-name "example-package.r"
mode "update"
install-folder: "
Library-script-name "convert-base.r"
]
/convert-base.r will not be a part of the package after this request is run. (Note: this does not mean it was a part of the package before; but, if it was, it isn't now)
Retrieves the raw data used to generate the Library's RSS feed.
You can subscribe to the Library's RSS feed by visiting get RSS feed.
Alternatively, you can used this LDS request to retrieve the same data as a REBOL object. In addition, there are some extra fields not supplied to the RSS readers.
has these fields:
Has these useful fields
Is a block of objects, one per script included in the RSS feed data.
Is a block of objects, one per included in the RSS feed data.
Is a block of objects, one per news item included in the RSS feed data. News is the little snippets you can find on the top right of the REBOL.org home page.
probe lds/send-server 'rss-get-feed-data []
Use these requests to work with your Library tokens.
Test if your Library token works:
If the token is valid, you get your text back. If not, you get an error message about the token
response-object: lds/send-server/use-token 'token-test ["any text"]
Cancels your current token. It will never work again.
response-object: lds/send-server/use-token 'token-cancel []
LDS predates LNS by a year, so LNS simply wasn't a possibility.
It would be good to add an LNS interface to the Library. If any one wants to volunteer to help with that, please drop us a feedback message
All validation and verification of requests is done on REBOL.org. Lds-local does no parameter checking -- it simply passes the parameters you supply to REBOL.org.
The lists you get back from LDS are not usually not sorted. Any sequencing is purely accidental, and should not be relied on. LDS provides the data, it is your choice what order to handle or present it.
One exception is the ''search-scripts request. The scripts-list it returns is sorted according to the relevance of the results: best fit first.
Each time you call lds/send-server, it talks to the REBOL.org server. There is a case for caching results as many things do not change that often. It's on the upgrade list.
I've been thinking of adding an XML refinement:
lds/send-server/xml 'help none
So what you get back is an XML page, not a REBOL object. Easy to do, but no point, unless anyone needs it.
end