REBOL/IOS: Creating Filesets

Document Version 1.0
IOS Version 1.0

Contents:

1. Overview
      1.1 Script Headers
      1.2 Running Scripts
2. A Basic Fileset
      2.1 Required User Privileges
3. Create the Simplest Fileset
4. Publishing A File
5. Simple File Uploader
6. Publishing Multiple Files
7. Just for Fun
8. Public Filesets
9. Private Filesets
10. Desktop Filesets

1. Overview

This document describes how to write scripts that create new filesets. A fileset is a collection of tags and files used for organizing, distributing, synchronizing, and controlling files across all IOS servers and clients. Details about filesets can be found in the REBOL/IOS Filesets document.

1.1 Script Headers

All scripts listed below should include a script header of the form:

REBOL [Title: "User Admin" Type: 'link-app]

This title can be changed to further clarify the operation. The type field must be set to allow the script to include the correct environment for the IOS Link client. If you forget to do so, an error will be generated telling you that certain IOS functions do not exist.

1.2 Running Scripts

To run test scripts without publishing them to the desktop, press CTRL-L while in the desktop window and specify the file you want to run.

2. A Basic Fileset

To create a fileset, the NEW-APP command is sent to the server along with a block that specifies the tags and files of the fileset.

The general form of the NEW-APP command is:

send-server new-app [ fileset-name [tags] [files] ]

The fileset-name must be a unique word that identifies the fileset within IOS. The tags block specifies the metadata tags that describe a filesets properties, users, privileges, desktop icons, folders, and more. The files block specifies the file names and file data for the fileset. See REBOL/IOS Filesets for more information about names, tags, and files. Note that the tags and files blocks can be empty.

2.1 Required User Privileges

In order to create a new fileset, a user must have the NEW-APP privilege. This privilege is set by the user administrator using an application like User Admin. By default, most users have the NEW-APP privilege.

3. Create the Simplest Fileset

The script below will create an empty fileset that will only be seen by you.

Note that at least one tag must be specified for the server to create the fileset. In the example below, the USERS tag is set to a block that contains only your user name. As a result, only you will see the fileset. (Which is a good idea if you are going to experiment with filesets like this.)

send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [] ]

If you see the desktop status bar (in the lower right) flash an error message such as "NO", "ERROR", or "HUH?" then you either:

1. Do not have the necessary NEW-APP privilege, or
2. Have an error in your script.
3. The fileset already exists and you do not have the necessary access permissions to modify it. Try another fileset name.

A common error is to forget to put a COMPOSE or REDUCE in front of the fileset block, which would send the unevaluated block to the server.

To verify that the fileset was created, open the registry.r file in the link root directory and look for a new fileset entry near the top of the file. You should see an entry that looks like:

simple [ users: ["carl"] ][ ]

4. Publishing A File

To create a fileset that contains a file, you must specify it in the files block. The example below will create a new fileset that contains an example file.

Note that if the fileset already exists, and you run this script, it will completely replace the prior fileset.

send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [ [%examples/test.r (compress "It worked!")] ] ]

After running this script, you should see the desktop status bar indicate that changes are happening and synchronization is taking place. If you then look in the examples directory (at your link root location) you should see a new test.r file, and its contents should be "It Worked!".

If you don't see the new file, then you made a mistake or you do not have permission. See the discussion in the above section.

Note that you do not need to create the fileset each time you want to add a file. There is also an ADD-FILE command that allows you to add a new file to an existing fileset. It is covered in a separate document.

5. Simple File Uploader

You can expand on the above script by adding code to request a file, read it, then upload it.

file: request-file/only if none? file [quit] ; Build the correct file path: name: second split-path file insert name %examples/ data: compress read/binary file send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [[(name) (data)]] ]

After running this script and observing the file being synchronized, you should find the file in the examples file. That file will now exist across all systems that you use.

6. Publishing Multiple Files

A similar technique can be used to create a fileset that contains multiple files. All you need is to add the additional files to the files block.

This example will create two files:

send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [ [%examples/test1.r (compress "file 1")] [%examples/test2.r (compress "file 2")] ] ]

The script below will publish all files that exist in your local directory.

files: load %./ block: copy [] foreach file files [ if not dir? file [ data: compress read/binary file name: join %examples/ file append/only block reduce [name data] ] ] send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [(block)] ]

Note that the block above is a block of blocks. That's why append/only is used. Don't forget it or you will get a nasty error back from the server.

7. Just for Fun

Here's a script that grabs a couple HTML pages every hour and publishes them. Note that to keep the script simple, only the HTML of the page is fetched.

loop 24 [ send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [ [%examples/page1.r (compress read http://www.rebol.com)] [%examples/page2.r (compress read http://www.rebol.org)] ] ] wait 1:00 ]

A similar script might grab your email every 30 minutes and publish it on IOS so you can now read it from anywhere:

counter: 1 loop 24 [ mailbox: open pop://user:pass@mail.server block: copy [] while [not tail? mailbox] [ append/only block [ join %example/msg counter compress first mailbox ] mailbox: next mailbox counter: counter + 1 ] close mailbox send-server new-app compose/deep [ simple [users: [(user-prefs/name)]] [(block)] ] wait 0:30 ]

This is just an example to help inspire you. Note that this example does not delete your email from the email server, which would cause it to publish the same email messages over again each hour.

8. Public Filesets

Creating a public fileset is not much different than the examples shown above. Instead of specifying a USERS tag, you will want to specify an ACCESS tag to control who gets the rights to modify the fileset:

send-server new-app compose/deep [ simple [access: [properties: rights: change: delete: [(user-prefs/name)]]] [ [%examples/test.r (compress "Everyone gets it!")] ] ]

Upon executing this script, everyone will receive a copy of your new file.

9. Private Filesets

To create a fileset with files that are shared with only a selected set of users:

send-server new-app compose/deep [ simple [ users: ["bob" "ted" "sara" "jane"] access: [properties: rights: change: delete: ["bob"]] [ [%examples/test.r (compress "Everyone gets it!")] ] ]

In this example, only "Bob" is given the right to make changes or deletions.

10. Desktop Filesets

Creating desktop filesets is beyond the scope of this introductory document and will be covered in a separate document on the subject.