URI (library)

04Jul2011 Comments
Off Categories:File

Overview

Summary

Handles URI and path conversion, including detection and resolution of relative paths

Contents

Overview
URI Instance
Static methods

Concept

Problem

JSFL's support for managing file paths is pretty limited:

  • file references must be in the URI format "file:///c|path%20to/file.txt"
  • relative paths such as "sibling.jsfl" or "../parent.jsfl" are not recognised
  • FLfile's conversion functions are limited in their functionality and choosy about their input

The end result is that referencing and accessing files in JSFL is highly inflexible, with laborious, absolute URIs being the norm, and file management generally being a bit of a pain.

Solution

xJSFL provides a single do-it-all class for URI management, the URI class. URIs can:

The URI static methods and URI instance handle the conversion of paths, URIs and token to and from URIs and paths in xJSFL, as well as some other power-features.

Its usability features are:

  • toPath and toURI take URIs, full paths, partial paths or even xJSFL folder {tokens}
  • Paths and URIs are tidied
  • Windows paths are returned using (perfectly valid) forward slashes
  • Long paths (>260 characters) throw an error (where Flash would fail silently)

Structurally, it can:

  • convert to and from registered folder {tokens}
  • combine a relative and absolute URI to create a new absolute URIs
  • work out common branch folders, or retarget existing URIs to new folders

Finally, and most importantly, it can

  • Resolve absolute URIs from relative paths, relative to the calling location

All this functionality essentially means you can throw just about anything at the URI class and it will give you back a solid URI to work with. See the section on URI juggling for more information.

Caveats

Note that there is a small overhead with using relative paths.

Internally, xJSFL has to jump through some hoops to determine the running files, and then has to parse out their locations. If you are building performance-sensitive code, be sure to:

  • keep calls passing relative paths to a minimum
  • define absolute URIs that Flash can use as soon as possible

URI-formatted strings (file:///) always bypass parsing. Otherwise the library kicks in, so make sure to create an absolute URI as soon as possible!

Usage

Using static methods

Often, you'll just want to create a URI to use, and you can simply use some string concatenation, like so:

var uri = xjsfl.uri + 'user/jsfl/functions.txt'; // file:///E|/Projects/xJSFL/user/jsfl/functions.jsfl

With the URI class, you can use URI.toURI to create a URI that's aware of your current location:

var uri = URI.toURI('functions.txt'); // file:///E|/Projects/xJSFL/user/jsfl/functions.jsfl

Or, you could use a token to create the URI:

var uri = URI.toURI('{user}/jsfl/functions.txt'); // file:///E|/Projects/xJSFL/user/jsfl/functions.jsfl

The URI class has a whole host of other useful URI management and manipulation functions as well, for example:

URI.getName(uri);      // functions.jsfl
URI.getExtension(uri); // jsfl
URI.getFolder(uri);    // file:///E|/Projects/xJSFL/user/jsfl/

URI instance

URI instances can be used where you need more flexibility with a single URI, as it has various properties that can be read to return the components of the uri, for example:

// create the URI instance
	var uri = new URI('functions.jsfl');

// test the URI properties
	uri.name           // functions.jsfl
	uri.extension      // jsfl
	uri.folder         // file:///E|/Projects/xJSFL/user/jsfl/
	uri.type           // file

Location-aware classes

Note that all of the file-related classes and methods in xJSFL are location-aware. That is, you can pass in a relative path, and it will be converted internally so that Flash can work with an absolute URI straight off the bat. Therefore, you usually don't need to create an absolute URI (unless you have a specific reason to) when working with files local to the script you're working in, for example:

var file     = new File('some file.txt');
var template = new Template('../assets/templates/text/output.txt', data);
var logger   = new Logger(template, '../temp/logs/log.txt');

Developing your own location-aware functions and classes

Overview

The mechanism for creating location-aware classes relies on the internal call stack of currently running functions, to determine location of the initial call.

When a function in JSFL is called, it is added to an internal Array, and when that function calls some code, that function is added as well, and so on, and so on. This stack stores the snippet of JSFL, the URI and the line number of the calling code, and this information is used inside the URI class to determine the URI of calling functions by navigating the stack, and grabbing the correct URI:

// E:/Projects/xJSFL/dev/folder 1/a.jsfl
function a(){ b(); }

// E:/Projects/xJSFL/dev/folder 2/b.jsfl
function b(){ c(); }

// E:/Projects/xJSFL/dev/folder 3/c.jsfl
function c(){ inspect(Utils.getStack()); }

// E:/Projects/xJSFL/dev/test.jsfl
a();
Inspect: Array (depth:4, objects:4, values:20, time:0.0 seconds)
--------------------------------------------------------------------------------
array => Array
	[0] => Object
		 line: 36
		 code: "c()"
		 file: "c.jsfl"
		 path: "E:/Projects/xJSFL/dev/folder 3/"
		 uri: "file:///E|/Projects/xJSFL/dev/folder 3/c.jsfl"
	[1] => Object
		 line: 31
		 code: "b()"
		 file: "b.jsfl"
		 path: "E:/Projects/xJSFL/dev/folder 2/"
		 uri: "file:///E|/Projects/xJSFL/dev/folder 2/b.jsfl"
	[2] => Object
		 line: 26
		 code: "a()"
		 file: "a.jsfl"
		 path: "E:/Projects/xJSFL/dev/folder 1/"
		 uri: "file:///E|/Projects/xJSFL/dev/folder 1/a.jsfl"
	[3] => Object
		 line: 39
		 code: ""
		 file: "test.jsfl"
		 path: "E:/Projects/xJSFL/dev/"
		 uri: "file:///E|/Projects/xJSFL/dev/test.jsfl"

Working example

Take this file in location A; it's at index 0 in the call stack. It then calls a function loaded from a file in a completely different folder, location B:

// location: xJSFL/user/jsfl/test.jsfl
test('test.jsfl');
This code in location B is now at index 1 in the call stack, but needs to know the location of the calling script at index 0.

Doing this is simple; the URI instance and URI.toURI() function both accept a second context parameter, which is used to determine which index of stack to grab. In this case, it is simple a number that says how many steps away the calling function is from the current function. In the following example, it's one, so we pass 1 as the context parameter when we create the URI:

// location: xJSFL/user/jsfl/libraries/functions.jsfl
	function test(path)
	{
		var thatURI = new URI(path, 1); // context is 1, as this function is 1 step away from the calling code
		var thisURI = new URI();        // an empty URI grabs the current file URI

		trace('Calling path:  ' + thatURI.path);
		trace('Function path: ' + thisURI.path);
	}

The results are that the script in location B can correctly calculate the absolute path from a variable passed from location A:

Calling path:  E:/Projects/xJSFL/user/jsfl/test.jsfl
Function path: E:/Projects/xJSFL/user/jsfl/libraries/functions.jsfl

URI Instance

Instantiatable class that can be used to easily create and manipulate URI strings

URI(pathOrURI, context)

URI Constructor

Parameters:

  • pathOrURI String A token, path or URI-formatted string
  • context String An optional uri or path context, from which to start the URI
  • context File An optional File from which to start the URI
  • context Folder An optional Folder from which to start the URI
  • context Number An optional stack-function index, the location of which to derive the URI from

The following example creates a URI instance referencing a relative file:

var URI = new URI('path/to/file.jsfl');
trace(uri);
file:///E|/Projects/xJSFL/user/jsfl/path/to/file.jsfl
The context parameter can be used when you want to reference the file from another location, in this case a folder URI: 
var folder      = fl.configURI;
var file        = 'path/to/file.jsfl';
var uri         = new URI(file, folder);
trace(uri);
file:///F|/Users/Dave%20Stewart/AppData/Local/Adobe/Flash%20CS4/en/Configuration/path/to/file.jsfl

Note that if you want to create your own functions or classes that instantiate or build URIs from passed-in parameters, you'll need to see the section on developing your own location-aware functions and classes.

Properties

uri

The file:/// URI of the URI instance (casting the URI object to a String gives the same result)

  • Type: String
  • Access: Read/write

The following example traces the uri's URI

var uri = new URI('some file.jsfl');
trace(uri.uri); // same as trace(uri);;
file:///E|/Projects/xJSFL/user/jsfl/some%20file.jsfl

path

The platform-specific path of the file or folder referred to by the URI instance

  • Type: String
  • Access: Read

The following example traces teh uri's path (in path format):

var uri = new URI('some file.jsfl');
trace(uri.path);
E:/Projects/xJSFL/user/jsfl/some file.jsfl

folder

The folder path URI to the URI instance

  • Type: String
  • Access: Read

The following example traces the uri's folder (in URI format):

var uri = new URI('some file.jsfl');
trace(uri.folder);
file:///E|/Projects/xJSFL/user/jsfl/

name

The name of the file or folder referred to by the URI instance

  • Type: String
  • Access: Read

The following example traces the uri's file name:

var uri = new URI('some file.jsfl');
trace(uri.name);
some file.jsfl

extension

The name of the file or folder referred to by the URI instance

  • Type: String
  • Access: Read

The following example traces the uri's extension:

var uri = new URI('some file.jsfl');
trace(uri.extension);
txt

type

The type of the URI, 'file' or 'folder'

  • Type: String
  • Access: Read

The following example traces the uri's type:

var uri = new URI('some file.jsfl');
trace(uri.type);
file

Methods

getParent()

The parent folder of the file or folder referred to by the URI instance

Returns:

  •   URI The parent URI

The following example inspects the uri's parent URI:

var uri = new URI('some file.jsfl');
inspect(uri.getParent());
Inspect: Unknown (depth:4, objects:0, values:6, time:0.0 seconds)
--------------------------------------------------------------------------------
object => Unknown
	 uri: "file:///E|/Projects/xJSFL/user/jsfl/"
	 folder: "file:///E|/Projects/xJSFL/user/jsfl/"
	 name: "jsfl"
	 extension: ""
	 path: "E:/Projects/xJSFL/user/jsfl/"
	 type: "folder"

pathTo(pathOrURI)

Returns a new URI that resolves to the target path or URI

Parameters:

  • pathOrURI String The target URI, such as '../../'

Returns:

  •   URI The new URI

The following example traces the relative path from uriA to uriB:

var uriA = new URI('E:/Projects/xJSFL/user/jsfl/some file.jsfl');
var uriB = new URI('E:/Projects/xJSFL/assets/text/some other file.txt');
trace(uriA.pathTo(uriB));
../../assets/text/some%20other%20file.txt

toString()

The URI string of the URI instance

Returns:

  •   String The string of the URI, i.e. file://path/to/file.txt

The URI instance toString() method simply traces the internal URI, thus the URI instance can be used anywhere a URI-formatted string is expected.

The following example traces the uri as a string:

var uri = new URI('some file.jsfl');
trace(uri);
file:///E|/Projects/xJSFL/user/jsfl/some%20file.jsfl

Static methods

A host of static utility functions that can be used to manipulate paths or URIs

Creation functions

Creates URIs or paths from a wide variety of sources

toURI(pathOrURI, context, checkLength)

Create a valid URI from virtually any URI or path

Parameters:

  • pathOrURI String A token, path or URI-formatted string
  • pathOrURI Boolean A Boolean, to get the current file
  • context String An optional uri or path context, from which to start the URI
  • context File An optional File from which to start the URI
  • context Folder An optional Folder from which to start the URI
  • context Number An optional stack-function index, the location of which to derive the URI from
  • checkLength Boolean An optional Boolean, to test resulting URIs are not longer than the 260 characters allowed for most FLfile operations. Defaults to true

Returns:

  •   String An absolute URI

URI.toURI() is the engine behind xJSFL's URI juggling, converting a wide variety of paths, relative paths, fragments and tokens to return absolute URIs that Flash can process. It:

  • Converts paths to URIs (or simply returns tidied URIs)
  • Automatically (or manually) resolves relative paths - to the calling file, or a supplied context
  • Resolves // to the xJSFL root folder
  • Expands registered {placeholder} variables such as:
    • {xjsfl} - the xJSFL/ folder
    • {core} - the xJSFL/core/ folder
    • {modules} - the xJSFL/modules/ folder
    • {user} - the xJSFL/user/ folder
    • {flash} - the user's Flash Configuration/ folder
    • {swf} - the user's Flash Configuration/WindowSWF/ folder
  • Tidies badly-formatted paths
  • Throws errors for paths that are too long (FLfile has a 260 character limit)

URI.toURI() has a couple of shortcuts to get the current URI.

The following example returns the URI of the currently-running script:

trace(URI.toURI(true));		// gets the currently-running script's URI
trace(URI.toURI(''));		// gets the currently-running script's folder URI
file:///E|/Projects/xJSFL/user/jsfl/test.jsfl
file:///E|/Projects/xJSFL/user/jsfl/

The following example creates URIs from various sources:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'pc drive   ' : 'E:/windows/drive/path/to/file.txt',
	'mac drive  ' : 'Macintosh HD:/drive/path/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'sibling    ' : 'sibling.txt',
	'child      ' : 'path/to/child.txt',
	'parent     ' : '../parent.txt',
	'grandparent' : '../../grandparent.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt',
	'mixed      ' : 'c:/path/to/../file.txt',
	'untidy     ' : 'c:/path\\to\\../file.txt',
};

for(var name in sources)
{
	trace(name + ' : ' + URI.toURI(sources[name]));
}
uri         : file:///E|/uri/to/file.txt
pc drive    : file:///E|/windows/drive/path/to/file.txt
mac drive   : file:///Macintosh%20HD/drive/path/to/file.txt
absolute    : file:///E|/absolute/path/to/file.txt
sibling     : file:///E|/Projects/xJSFL/user/jsfl/sibling.txt
child       : file:///E|/Projects/xJSFL/user/jsfl/path/to/child.txt
parent      : file:///E|/Projects/xJSFL/user/parent.txt
grandparent : file:///E|/Projects/xJSFL/grandparent.txt
file        : file:///E|/Projects/xJSFL/user/jsfl/file.txt
folder      : file:///E|/Projects/xJSFL/user/jsfl/folder/
root        : file:///E|/
token       : file:///F|/Users/Dave%20Stewart/AppData/Local/Adobe/Flash%20CS4/en/Configuration/token.txt
folder root : file:///E|/Projects/xJSFL/user/folder%20root.txt
xjsfl root  : file:///E|/Projects/xJSFL/xjsfl%20root.txt
mixed       : file:///c|/path/file.txt
untidy      : file:///c|/path/file.txt

Note that if you want to create your own functions or classes that instantiate or build URIs from passed-in parameters, you'll need to see the section on developing your own location-aware functions and classes.


toPath(pathOrURI, shorten)

Create a valid path from virtually any URI or path, and has the same functionality of URI.toURI()

Parameters:

  • pathOrURI String A token, path or URI-formatted string
  • shorten Boolean An optional Boolean to return a path with {placeholder} variables for registered URIs

Returns:

  •   String An absolute, or shortened path

URI.toPath() is the path-specific counterpart to URI.toURI():

  • Provides the same functionality that URI.toURI() provides
  • Tidies badly-formatted paths
  • Converts Windows backlashes to forward slashes
  • Optionally shortens relevent absolute paths to {token}paths/to/file.txt

The following example creates paths from various sources:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'pc drive   ' : 'E:/windows/drive/path/to/file.txt',
	'mac drive  ' : 'Macintosh HD:/drive/path/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'sibling    ' : 'sibling.txt',
	'child      ' : 'path/to/child.txt',
	'parent     ' : '../parent.txt',
	'grandparent' : '../../grandparent.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt',
	'mixed      ' : 'c:/path/to/../file.txt',
	'untidy     ' : 'c:/path\\to\\../file.txt',
};

for(var name in sources)
{
	trace(name + ' : ' + URI.toPath(sources[name]));
}
uri         : E:/uri/to/file.txt
pc drive    : E:/windows/drive/path/to/file.txt
mac drive   : Macintosh HD/drive/path/to/file.txt
absolute    : E:/absolute/path/to/file.txt
sibling     : E:/Projects/xJSFL/user/jsfl/sibling.txt
child       : E:/Projects/xJSFL/user/jsfl/path/to/child.txt
parent      : E:/Projects/xJSFL/user/parent.txt
grandparent : E:/Projects/xJSFL/grandparent.txt
file        : E:/Projects/xJSFL/user/jsfl/file.txt
folder      : E:/Projects/xJSFL/user/jsfl/folder/
root        : E:/
token       : F:/Users/Dave Stewart/AppData/Local/Adobe/Flash CS4/en/Configuration/token.txt
folder root : E:/Projects/xJSFL/user/folder root.txt
xjsfl root  : E:/Projects/xJSFL/xjsfl root.txt
mixed       : c:/path/file.txt
untidy      : c:/path/file.txt

Conversion functions

Converts existing paths and URIs to paths (note that the conversion functions do not detect and convert relative paths)

asURI(pathOrURI, checkLength)

Perform simple path to URI conversion

Parameters:

  • path String A valid path
  • checkLength Boolean An optional Boolean, to test resulting URIs are not longer than the 260 characters allowed for most FLfile operations. Defaults to true

Returns:

  •   String A URI-formatted string

The following example converts URIs from various sources (note how only correctly-formatted paths are converted):

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'pc drive   ' : 'E:/windows/drive/path/to/file.txt',
	'mac drive  ' : 'Macintosh HD:/drive/path/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'sibling    ' : 'sibling.txt',
	'child      ' : 'path/to/child.txt',
	'parent     ' : '../parent.txt',
	'grandparent' : '../../grandparent.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt',
	'mixed      ' : 'c:/path/to/../file.txt',
	'untidy     ' : 'c:/path\\to\\../file.txt',
};

for(var name in sources)
{
	trace(name + ' : ' + URI.asURI(sources[name]));
}
uri         : file:///E|/uri/to/file.txt
pc drive    : file:///E|/windows/drive/path/to/file.txt
mac drive   : file:///Macintosh%20HD:/drive/path/to/file.txt
absolute    : file:///E|/absolute/path/to/file.txt
sibling     : file:///sibling.txt
child       : file:///path/to/child.txt
parent      : file:///../parent.txt
grandparent : file:///../../grandparent.txt
file        : file:///file.txt
folder      : file:///folder/
root        : file:///E|/
token       : file:///{flash}token.txt
folder root : file:////folder%20root.txt
xjsfl root  : file:////xjsfl%20root.txt
mixed       : file:///c|/path/to/../file.txt
untidy      : file:///c|/path/to/../file.txt

asPath(pathOrURI, shorten)

Perform simple URI to path conversion

Parameters:

  • uri String A valid URI string
  • uri URI A valid URI instance
  • shorten Boolean An optional Boolean to return a path with {placeholder} variables for registered URIs

Returns:

  •   String A path-formatted string

The following example converts paths from various sources (note how only correctly-formatted paths are converted):

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'pc drive   ' : 'E:/windows/drive/path/to/file.txt',
	'mac drive  ' : 'Macintosh HD:/drive/path/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'sibling    ' : 'sibling.txt',
	'child      ' : 'path/to/child.txt',
	'parent     ' : '../parent.txt',
	'grandparent' : '../../grandparent.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt',
	'mixed      ' : 'c:/path/to/../file.txt',
	'untidy     ' : 'c:/path\\to\\../file.txt',
};

for(var name in sources)
{
	trace(name + ' : ' + URI.asPath(sources[name]));
}
uri         : E:/uri/to/file.txt
pc drive    : E:/windows/drive/path/to/file.txt
mac drive   : Macintosh HD:/drive/path/to/file.txt
absolute    : E:/absolute/path/to/file.txt
sibling     : sibling.txt
child       : path/to/child.txt
parent      : ../parent.txt
grandparent : ../../grandparent.txt
file        : file.txt
folder      : folder/
token       : {flash}token.txt
folder root : /folder root.txt
xjsfl root  : //xjsfl root.txt
mixed       : c:/path/to/../file.txt
untidy      : c:/path/to/../file.txt

Testing functions

The following functions test if a path or URI is absolute, relative, a file, folder, etc.

isURI(pathOrURI)

Test if the supplied value is a URI-formatted string

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are URIs:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isURI(sources[name]));
}
uri         : true
absolute    : false
relative    : false
file        : false
folder      : false
root        : false
token       : false
folder root : false
xjsfl root  : false

isPath(pathOrURI)

Test if the supplied value is a path-formatted string, such as c:/path/to/file.txt or /path

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are paths:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isPath(sources[name]));
}
uri         : false
absolute    : true
relative    : true
file        : true
folder      : true
root        : true
token       : true
folder root : true
xjsfl root  : true

isAbsolute(pathOrURI)

Tests if a path or URI is absolute (includes tokens and special xJSFL syntax)

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are absolute:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isAbsolute(sources[name]));
}
uri         : true
absolute    : true
relative    : false
file        : false
folder      : false
root        : true
token       : true
folder root : true
xjsfl root  : true

isRelative(pathOrURI)

Tests if a path or URI is relative (includes tokens and special xJSFL syntax)

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are relative:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isRelative(sources[name]));
}
uri         : false
absolute    : false
relative    : true
file        : true
folder      : true
root        : false
token       : false
folder root : false
xjsfl root  : false

isFile(pathOrURI)

Tests if a path or URI looks like a filename, rather than a folder

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are files:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isFile(sources[name]));
}
uri         : true
absolute    : true
relative    : true
file        : true
folder      : false
root        : false
token       : true
folder root : true
xjsfl root  : true

isFolder(pathOrURI)

Tests if a path or URI looks like a folder, rather than a filename

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are folders:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isFolder(sources[name]));
}
uri         : false
absolute    : false
relative    : false
file        : false
folder      : true
root        : true
token       : false
folder root : false
xjsfl root  : false

isRoot(pathOrURI)

Tests if a path or URI is at the highest folder level it can go

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   Boolean true or false, depending on the result

The following example checks which sources are drive roots:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.isRoot(sources[name]));
}
uri         : false
absolute    : false
relative    : false
file        : false
folder      : false
root        : true
token       : false
folder root : false
xjsfl root  : false

Extraction functions

The following functions extract a property from a path or URI

getName(pathOrURI, removeExtension)

Returns the file or folder name of the item referenced by the path or URI (note names are unescaped)

Parameters:

  • pathOrURI String A vald path or URI
  • removeExtension Boolean An optional Boolean to remove the extension

Returns:

  •   String The file or folder name

The following example gets the file or folder names from various sources:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.getName(sources[name]));
}
uri         : file.txt
absolute    : file.txt
relative    : file.txt
file        : file.txt
folder      : folder
root        : E:
token       : {flash}token.txt
folder root : folder root.txt
xjsfl root  : xjsfl root.txt

getExtension(pathOrURI)

Returns the file extension

Parameters:

  • pathOrURI String A vald path or URI

Returns:

  •   String The file extensions

The following example gets the extensions (if they have them) from various sources:

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.getExtension(sources[name]));
}
uri         : txt
absolute    : txt
relative    : txt
file        : txt
folder      : 
root        : 
token       : txt
folder root : txt
xjsfl root  : txt

getFolder(pathOrURI)

Returns the current folder path of the item referenced by the path or URI

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   String The folder of the path or URI

The following example gets the folder path from various sources (note the subtle difference for the folder uri to getParent())::

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'folder uri ' : 'file:///E|/uri/to/',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.getFolder(sources[name]));
}
uri         : file:///E|/uri/to/
folder uri  : file:///E|/uri/to/
absolute    : E:/absolute/path/to/
relative    : path/to/
file        : 
folder      : folder/
root        : E:/
token       : 
folder root : /
xjsfl root  : //

getParent(pathOrURI)

Returns the parent folder of the item referenced by the path or URI (for folders, this is the parent folder)

Parameters:

  • pathOrURI String A valid path or URI

Returns:

  •   String The folder of the path or URI

The following example gets the parent folder path from various sources (note the subtle difference for the folder uri to getFolder())::

var sources =
{
	'uri        ' : 'file:///E|/uri/to/file.txt',
	'folder uri ' : 'file:///E|/uri/to/',
	'absolute   ' : 'E:/absolute/path/to/file.txt',
	'relative   ' : 'path/to/file.txt',
	'file       ' : 'file.txt',
	'folder     ' : 'folder/',
	'root       ' : 'E:/',
	'token      ' : '{flash}token.txt',
	'folder root' : '/folder root.txt',
	'xjsfl root ' : '//xjsfl root.txt'
};

for(var name in sources)
{
	trace(name + ' : ' + URI.getParent(sources[name]));
}
uri         : file:///E|/uri/to/
folder uri  : file:///E|/uri/
absolute    : E:/absolute/path/to/
relative    : path/to/
file        : 
folder      : 
root        : E:/
token       : 
folder root : /
xjsfl root  : //

getBranch(src, trg)

Resolves the common (branch) path between 2 paths or URIs

Parameters:

  • src String A source path or URI
  • trg String A target path or URI

Returns:

  •   String The common ancestor path or URI

The following example gets the common branch between various sources:

var uriA = 'file:///C|/a/b/c/file.txt';
var uriB = 'file:///C|/a/b/c/d/e/file.txt';
var uriC = 'file:///X|/a/b/c/d/e/f/g/file.txt';

trace('> ' + URI.getBranch(uriA, uriB));
trace('> ' + URI.getBranch(uriB, uriC));

var pathA = 'C:/a/b/c/file.txt';
var pathB = 'C:/a/b/c/d/e/file.txt';
var pathC = 'X:/a/b/c/d/e/f/g/file.txt';

trace('> ' + URI.getBranch(pathA, pathB));
trace('> ' + URI.getBranch(pathB, pathC));

> file:///C|/a/b/c/
>

> C:/a/b/c/
>

pathTo(src, trg)

Resolves a path from the Source URI to a target URI, returning a relative path-formatted path

Parameters:

  • src String The source path or URI
  • trg String The target path or URI

Returns:

  •   String The new relative path between the two, or the absolute URI if there's no relationship

The following example gets the path from various sources to each other:

var uriA = 'file:///C|/a/b/c/file.txt';
var uriB = 'file:///C|/a/b/c/d/e/file.txt';
var uriC = 'file:///X|/a/b/c/d/e/f/g/file.txt';

trace('> ' + URI.pathTo(uriA, uriB));
trace('> ' + URI.pathTo(uriB, uriA));
trace('> ' + URI.pathTo(uriB, uriC));

var pathA = 'C:/a/b/c/file.txt';
var pathB = 'C:/a/b/c/d/e/file.txt';
var pathC = 'X:/a/b/c/d/e/f/g/file.txt';

trace('> ' + URI.pathTo(pathA, pathB));
trace('> ' + URI.pathTo(pathB, pathA));
trace('> ' + URI.pathTo(pathB, pathC));
> d/e/file.txt
> ../../file.txt
> X:/a/b/c/d/e/f/g/file.txt

> d/e/file.txt
> ../../file.txt
> X:/a/b/c/d/e/f/g/file.txt

findFolder(pathOrURI, folder)

Returns the path or URI truncated to the supplied folder name or path

Parameters:

  • pathOrURI String A path or URI string
  • pathOrURI URI A URI instance
  • folder String The name or partial name of a folder to find in the path

Returns:

  •   String The new URI or path

The following example gets the absolute path or URI by supplying a folder name to search for, for various sources:

var uri = 'file:///C|/some/long/path/to/file.txt';
var path = 'C:/some/long/path/to/file.txt';

trace(URI.findFolder(uri, 'to'));
trace(URI.findFolder(path, 'to'));
file:///C|/some/long/path/to/
C:/some/long/path/to/

reTarget(src, trg, base)

Re-targets a specified portion of a URI (or URIs) to point at a new folder

Parameters:

  • src String The source path or URI
  • trg String A folder you want to retarget to, from the source base and downwards
  • base String The name or partial name of a folder in the src path or URI you want to branch from

Returns:

  •   String The new path or URI
  •   Array An Array of new paths or URIs

URI.reTarget() is mainly used when copying a tree of files from one folder to another, which need to retain their nested folder structure.

The base parameter is the branch where the source parameter should be "snipped off" and re-attached to the target parameter:

base:   file:///E|/Projects/xJSFL/core/install/

source: file:///E|/Projects/xJSFL/core/install/assets/some/file.txt
                                               ^
                                               1: Cut source at base...
target: file:///C|flash/xJSFL/
                              assets/some/file.txt
                              ^
                              2: ...then attach to target!

The following example demonstrates creating the URIs needed to copy a tree from an xJSFL installation folder to a (threoretical) Flash folder:

var sources =
[
	'file:///E|/Projects/xJSFL/core/install/assets/some/file_1.txt',
	'file:///E|/Projects/xJSFL/core/install/assets/some/file_2.txt',
	'file:///E|/Projects/xJSFL/core/install/assets/some/file_3.txt',
];
var target = 'file:///C|flash/xJSFL/';
var base   = 'file:///E|/Projects/xJSFL/core/install/';

for each(var source in sources)
{
	trace(URI.reTarget(source, target, base));
}
file:///C|flash/xJSFL/assets/some/file_1.txt
file:///C|flash/xJSFL/assets/some/file_2.txt
file:///C|flash/xJSFL/assets/some/file_3.txt

Comments are closed.

© Copyright - xJSFL - Theme Design by Kriesi.at