10.1. get-rml-message

10.1.1. Example 1 -- get a single message

probe res: lds/send-server 'get-rml-message [237859]

The fields in the data object for this request are:

msgid -- Library Archive identifier for this message. (The Library has two formats for the message id: a number, which is broadly compatible with the message numbers in other archives of the ML, and a code that isn't. Either will work. These two requests return the same message:

probe res: lds/send-server 'get-rml-message [237859]

probe res: lds/send-server 'get-rml-message ["CKLQ"]

author -- slightly munged email address

msgdate -- local date and time of posting. Will usually be a REBOL date!, but may sometimes be a REBOL date! in a string. Use load form data/msgdate to coerce to date!

count/2 -- total messages that are in the word index (ie that you can search on). This number may often be a little lower than count/1: indexing is an async process and lags behind at times. If it is significantly lower, then we may be rebuilding the word index. If so, please be patient

count/3 -- and higher: reserved. we may be adding them later, so don't assume that count/1 = last count

threads block -- Thread information. Currently a block with just 1 number: the total number of threads. But we may add more numbers, so (as above) don't assume that thread/1 = last thread

years block -- information about the years we have indexed. Use this with the search-rml request. Note that there maybe more years (as shown in the example) than you might expect. See search-rml for more details.

get-rml-status is most useful for getting the full span of years for a search-rml request....See immediately below.

10.3. search-rml

Sends you back the message ids for all threads that meet your search criteria

Parameters: A string that has both the words on which you want to search and, optionally, the years you want to search -- see below

Response: Object! -- containing various fields -- see below

10.3.1. Parameter

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.

If the string does not contain any years, the search will be on the subject lines of all posts

If the string does contain one or more years, the search will be on the full text of the posts for those years

10.3.2. Examples of the search parameter:

"help" -- searches for "help" in all subject lines

"help 2005 2004" -- searches for "help" in the full text of all posts whose thread begin in 2004 or 2005

"2001 bunny 2003" -- searches for the word "bunny" in all posts for 2001 and 2003 (yes, there is one result)

target-words -- the words searched were "apple" AND "pink" AND "white". If your original request contained other words, they have been ignored as they are on the stop list

search-type -- the search type was posts meaning we checked the whole of all the posts. The other possibility is subjects, meaning we searched just the subject lines.

span -- we searched the years 2000 through 2003

msgids -- we found one thread meeting the search criteria. 207276 is the message id of the first message in that thread

10.3.4. Searchable years

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.

11.6.2. Example 2: Download new versions of scripts changed in the last 31 days

12. Script Archive requests

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).

12.1. list-archive-versions

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.

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.

12.2. get-archive-version

Retrieve an archived version of a script (see list-archive-versions for more details)

Parameters: script-name/version-number [string] Separate the two parts with a forward slash, eg my-package/file1.txt

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.

13. Update scripts requests

13.1. contribute-script

Use this request to either add a new script to the Library; or update an existing script that you own.

Parameters: simple dialect -- see below

Needs token?: Yes

Response: complex object -- see below

13.1.1. Parameters

Are a dialect with these words: mode, note, and script. Mode and script must always be present. Note is optional.

mode -- can be check or update . check means check that the script is okay, but do not actually add or update it. Use check to play around with this request without actually updating anything. Update means add (the new script) or update (the existing script) if all is well with it.

15.1.4. file-type:package

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:

the included package may be flagged as not available for download

the included package may itself include other packages

there may be loops in the inclusions. Perhaps Package1 includes Package2, and Package2 includes Package1. This should not be interpreted as an error -- it may simple be that both packages require the other one.

15.2. get-package-file

Retrieve one file from a package

Parameters: package-name/file-name [string!] Separate the two parts with a forward slash, eg my-package/file1.txt

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.

16. Package update requests

16.1. Overview before we start

A package is a multi-file unit that makes up one contribution to the Library.

From a user's perspective, it is three things:

A script in the Library with a type header that includes the magic word 'package. This script will be just a dummy -- more like an index card that a real script.

Zero or more uploaded files that make up the package

Zero or more existing scripts from the Library that are included in the package.

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.

mode check will not perform the update -- thus making some testing easier

mode update will be required for an update

16.2. Transaction level support

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.

16.2.1. Step 1: contribute-script

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.

16.2.2. Step 2: update-package-header

Use this request to:

optionally, add some header information to the package

set the package as unavailable so people cannot download it while it is incomplete

16.2.3. Step 3: upload-package-file

Use this request for each of your files that are part of the package.

16.2.4. Step 4: include-script-in-package

Use this request for any existing Library scripts that are part of the package.

16.2.5. Step 5: update-package-header again

Use this again to set the package as available . People can now download your new package.

16.3. Steps involved in updating a package

If you later need to change the package, use these steps:

16.3.1. Step 1: update-package-header

Set the package as unavailable to prevent people accidentally downloading an incomplete or inconsistent package

16.3.2. Step 2: upload-package-file

To add new files or update existing ones

16.3.3. Step 3: remove-file-from-package

To remove a file from the package

16.3.4. Step 4 include-script-in-package

To include additional Library scripts in the package

16.3.5. Step 5 remove-script-from-package

To remove a Library script from the package.

16.3.6. Step 6: update-package-header

Use this again to set the package as available . People can now download your updated package.

16.4. update-package-header

Use this request to add or update the header details of a package

Parameters: simple dialect -- see below

Needs token?: Yes

Response: complex object -- see below

16.4.1. Parameters

Are a dialect with four words : mode, script-name and status and user-notes

mode -- can be check or update . As per contribute-script

script-name -- the name of the script. Must be present

status -- sets the available status. Values are private or public

user-notes -- optional notes about the package.

16.4.2. Response

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.

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.

17. Other requests

17.1. rss-get-feed-data

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.

Parameters: none

Response:response object -- see below

17.1.1. response object

has these fields:

generation-info -- an object with useful status details

script-library -- a block with an object for each script included in the feed

mailing-list-archive -- a block with an object for each mailing list thread included in the feed

news -- a block with details of each "news" headline

17.1.2. response object/generation-info

Has these useful fields

rss-test-mode -- should always be false.

timestamp -- precise timestamp for when the RSS feed data was last generated

supply? -- will be generated if your request has triggered the Library into generating a fresh set of RSS feed data; or cached if you are being supplied some slightly older data. Note that cached does not usually mean stale. Even cached data is likely to be very close to real-time accurate.

data-range -- a block with two dates; showing the start and end date of the range for the RSS feed.

timings -- for testing

17.1.3. response object/script-library

Is a block of objects, one per script included in the RSS feed data.

script-name -- the name of the script

link -- the URL to view it

update-type -- updated or new

entry-date -- when the script was added or last updated

title -- from the script's title header

purpose -- from the script's purpose header

version -- from the script's version header

owners -- a block with zero or more Library member's names; these are the members who own (and can thus update) the script

change-note -- a note added when the owner last updated the script to explain why it is changing.

17.1.4. response object/mailing-list-archive

Is a block of objects, one per included in the RSS feed data.

msgid -- the mailing list message id of the first message in the thread

subject -- the subject line of the first message in the thread (note that it is possible for later messages in the same thread to have different subject lines).

new-messages -- a block with two data items per message:

message date -- the date the message was entered into the ML archive

message id -- the message id of the message

There will be an entry (date and message id) in the block for each message in the thread that is included in the RSS feed data:

if this block includes the msgid of the first message in the thread, then this is a new thread;

if it does not, then this is an old thread that has one or more new messages in it.

17.1.5. response object/news

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.

title -- headline

link -- URL for further information

date -- date news item added

content -- text of the information paragraph.

17.1.6. Example

probe lds/send-server 'rss-get-feed-data []

18. Token requests

Use these requests to work with your Library tokens.

18.1. token-test

Test if your Library token works:

Parameters: any text

Token required: yes

Response: Object! -- your text back

If the token is valid, you get your text back. If not, you get an error message about the token

18.1.1. Example:

response-object: lds/send-server/use-token 'token-test ["any text"]

18.2. token-cancel

Cancels your current token. It will never work again.

Parameters: none

Token required: yes

Response: Object! -- status

18.2.1. Example:

response-object: lds/send-server/use-token 'token-cancel []

19. Random points and answers to NAQs (never-asked questions)

19.1. Why not use LNS (Lightweight Network Services)?

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

19.2. Validation and verification

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.

19.3. Sorting

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.

19.4. Caching

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.

19.5. XML

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.