Internal URIs

Overview

SCFFLD relies heavily on the concept of an internal URI space as a means for referencing and resolving values and resources needed to build the components of a running system. The URI space is an address space private and internal to the system.

Concepts

An overview of the main internal URI space concepts is given here.

URIs

A URI is simply a string used to reference or identify a value or resource. In SCFFLD, all internal URIs conform to the compound URI format described below. They are called internal URIs because the values to which they refer are resolved internally of the system, as opposed to e.g. http: or file: URLs, which must be resolved externally over the network or from the file system.

Resources

URIs are used to reference resources. A resource may be a simple value (e.g. a string) or something altogether larger, e.g. an image read from a file. SCFFLD provides a standard Resource object type which can be used to wrap the underlying data being referenced, and provides methods for accessing standard representations of that data; however, many URIs resolve to a bare data value.

Compound URIs

SCFFLD uses a compound URI format to describe internal URIs. This format allows URIs to be nested within other URIs, and so allows URI parameter values to be described using other URIs.

The general format of a compound URI is:

scheme:name#fragment+param1=simple+param2@uri:value

Where each of these parts are the following:

Nesting

If a compound URI contains parameter values which themselves are URIs with parameters then it can become ambiguous as to where a nested URI ends and the surrounding URI parameter list continues. For example, in the following URI -

uri:outer+p1@uri:inner+p2=other+p3=thing

... it is not clear whether p2 and p3 belong to uri:inner or uri:outer. When presented like this, the URI parser will assign all trailing parameters to the most recently started (i.e. right-most) URI, but this isn't always what is desired. To solve this problem and to make URIs less ambiguous, the URI format allows parameter values to be wrapped in square brackets so that the beginning and end of parameter values are clearly demarcated. This allows the URI above to be rewritten as -

uri:outer+p1@[uri:inner+p2=other]+p3=thing

... making it clear that p2 belongs to uri:inner, whilst p3 belongs to uri:outer.

Schemes

Each URI scheme provides a different mechanism for resolving resource values from a URI string. Core SCFFLD provides a small number of standard schemes. The SCFFLD app container provides a number of additional schemes, described in the container documentation.

Standard schemes

These are the standard SCFFLD URI schemes.

s:

The s: scheme (short for string scheme) is a conceptually simple scheme which simply returns the name portion of a URI as the URI's referenced value, e.g.:

s:abc => "abc"

The scheme also supports more complex behaviour, allowing the URI name to define a string template whose placeholder values are populated from the URI parameter values. For example (note that URI character escaping is removed for legibility):

s:{abbr}day+abbr=sun => "sunday"

app:

The app: scheme is what is called a file based scheme as it used to reference the contents of a file. In this case, the app: scheme allows any files packaged with the app to be accessed. The scheme interprets the URI name as the path to a file on the app's filesystem; for example:

app:/SCFFLD/config.json

cache:

The cache: scheme is another file based scheme for accessing the app's caches directory location.

local:

This scheme allows values within the app's local storage (i.e. user defaults on iOS) to be referenced by name.

dirmap:

This scheme is used to map separate JSON files located on the app's file system (i.e. packaged with the app) into a configuration data structure. It is useful for organizing large numbers of configurations into separate files, and is used by the default SCFFLD app container configuration for loading pattern and nameds configurations.

Custom schemes

It is possible to add custom URI schemes to a SCFFLD container by registering a scheme name and handler with the container.