The most important aspect of URI's to understand is that URI's - * and URL's are not strings. URI's are complex data structures that - * encapsulate many pieces of information. The string version of a - * URI is the serialized representation of that data structure. This - * string serialization is used to provide a human readable - * representation and a means to transport the data over the network - * where it can then be parsed back into its' component parts.
- * - *URI's fall into one of three categories: - *
The query and fragment parts are optional.
- * - *This class supports both non-hierarchical and hierarchical URI's
- * - *This class is intended to be used "as-is" for the vast majority - * of common URI's. However, if your application requires a custom - * URI syntax (e.g. custom query syntax or special handling of - * non-hierarchical URI's), this class can be fully subclassed. If you - * intended to subclass URI, please see the source code for complete - * documation on protected members and protected fuctions.
- * - * @langversion ActionScript 3.0 - * @playerversion Flash 9.0 - */ - public class URI - { - // Here we define which characters must be escaped for each - // URI part. The characters that must be escaped for each - // part differ depending on what would cause ambiguous parsing. - // RFC 3986 sec. 2.4 states that characters should only be - // encoded when they would conflict with subcomponent delimiters. - // We don't want to over-do the escaping. We only want to escape - // the minimum needed to prevent parsing problems. - - // space and % must be escaped in all cases. '%' is the delimiter - // for escaped characters. - public static const URImustEscape:String = " %"; - - // Baseline of what characters must be escaped - public static const URIbaselineEscape:String = URImustEscape + ":?#/@"; - - // Characters that must be escaped in the part part. - public static const URIpathEscape:String = URImustEscape + "?#"; - - // Characters that must be escaped in the query part, if setting - // the query as a whole string. If the query is set by - // name/value, URIqueryPartEscape is used instead. - public static const URIqueryEscape:String = URImustEscape + "#"; - - // This is what each name/value pair must escape "&=" as well - // so they don't conflict with the "param=value¶m2=value2" - // syntax. - public static const URIqueryPartEscape:String = URImustEscape + "#&="; - - // Non-hierarchical URI's can have query and fragment parts, but - // we also want to prevent '/' otherwise it might end up looking - // like a hierarchical URI to the parser. - public static const URInonHierEscape:String = URImustEscape + "?#/"; - - // Baseline uninitialized setting for the URI scheme. - public static const UNKNOWN_SCHEME:String = "unknown"; - - // The following bitmaps are used for performance enhanced - // character escaping. - - // Baseline characters that need to be escaped. Many parts use - // this. - protected static const URIbaselineExcludedBitmap:URIEncodingBitmap = - new URIEncodingBitmap(URIbaselineEscape); - - // Scheme escaping bitmap - protected static const URIschemeExcludedBitmap:URIEncodingBitmap = - URIbaselineExcludedBitmap; - - // User/pass escaping bitmap - protected static const URIuserpassExcludedBitmap:URIEncodingBitmap = - URIbaselineExcludedBitmap; - - // Authority escaping bitmap - protected static const URIauthorityExcludedBitmap:URIEncodingBitmap = - URIbaselineExcludedBitmap; - - // Port escaping bitmap - protected static const URIportExludedBitmap:URIEncodingBitmap = - URIbaselineExcludedBitmap; - - // Path escaping bitmap - protected static const URIpathExcludedBitmap:URIEncodingBitmap = - new URIEncodingBitmap(URIpathEscape); - - // Query (whole) escaping bitmap - protected static const URIqueryExcludedBitmap:URIEncodingBitmap = - new URIEncodingBitmap(URIqueryEscape); - - // Query (individual parts) escaping bitmap - protected static const URIqueryPartExcludedBitmap:URIEncodingBitmap = - new URIEncodingBitmap(URIqueryPartEscape); - - // Fragments are the last part in the URI. They only need to - // escape space, '#', and '%'. Turns out that is what query - // uses too. - protected static const URIfragmentExcludedBitmap:URIEncodingBitmap = - URIqueryExcludedBitmap; - - // Characters that need to be escaped in the non-hierarchical part - protected static const URInonHierexcludedBitmap:URIEncodingBitmap = - new URIEncodingBitmap(URInonHierEscape); - - // Values used by getRelation() - public static const NOT_RELATED:int = 0; - public static const CHILD:int = 1; - public static const EQUAL:int = 2; - public static const PARENT:int = 3; - - //------------------------------------------------------------------- - // protected class members - //------------------------------------------------------------------- - protected var _valid:Boolean = false; - protected var _relative:Boolean = false; - protected var _scheme:String = ""; - protected var _authority:String = ""; - protected var _username:String = ""; - protected var _password:String = ""; - protected var _port:String = ""; - protected var _path:String = ""; - protected var _query:String = ""; - protected var _fragment:String = ""; - protected var _nonHierarchical:String = ""; - protected static var _resolver:IURIResolver = null; - - - /** - * URI Constructor. If no string is given, this will initialize - * this URI object to a blank URI. - */ - public function URI(uri:String = null) : void - { - if (uri == null) - initialize(); - else - constructURI(uri); - } - - - /** - * @private - * Method that loads the URI from the given string. - */ - protected function constructURI(uri:String) : Boolean - { - if (!parseURI(uri)) - _valid = false; - - return isValid(); - } - - - /** - * @private Private initializiation. - */ - protected function initialize() : void - { - _valid = false; - _relative = false; - - _scheme = UNKNOWN_SCHEME; - _authority = ""; - _username = ""; - _password = ""; - _port = ""; - _path = ""; - _query = ""; - _fragment = ""; - - _nonHierarchical = ""; - } - - /** - * @private Accessor to explicitly set/get the hierarchical - * state of the URI. - */ - protected function set hierState(state:Boolean) : void - { - if (state) - { - // Clear the non-hierarchical data - _nonHierarchical = ""; - - // Also set the state vars while we are at it - if (_scheme == "" || _scheme == UNKNOWN_SCHEME) - _relative = true; - else - _relative = false; - - if (_authority.length == 0 && _path.length == 0) - _valid = false; - else - _valid = true; - } - else - { - // Clear the hierarchical data - _authority = ""; - _username = ""; - _password = ""; - _port = ""; - _path = ""; - - _relative = false; - - if (_scheme == "" || _scheme == UNKNOWN_SCHEME) - _valid = false; - else - _valid = true; - } - } - protected function get hierState() : Boolean - { - return (_nonHierarchical.length == 0); - } - - - /** - * @private Functions that performs some basic consistency validation. - */ - protected function validateURI() : Boolean - { - // Check the scheme - if (isAbsolute()) - { - if (_scheme.length <= 1 || _scheme == UNKNOWN_SCHEME) - { - // we probably parsed a C:\ type path or no scheme - return false; - } - else if (verifyAlpha(_scheme) == false) - return false; // Scheme contains bad characters - } - - if (hierState) - { - if (_path.search('\\') != -1) - return false; // local path - else if (isRelative() == false && _scheme == UNKNOWN_SCHEME) - return false; // It's an absolute URI, but it has a bad scheme - } - else - { - if (_nonHierarchical.search('\\') != -1) - return false; // some kind of local path - } - - // Looks like it's ok. - return true; - } - - - /** - * @private - * - * Given a URI in string format, parse that sucker into its basic - * components and assign them to this object. A URI is of the form: - *The URI specification allows for authentication - * credentials to be embedded in the URI as such:
- * - *http://user:passwd@host/path/to/file.htm
- * - *When setting this value, the string - * given is assumed to be unescaped. When retrieving this - * value, the resulting string is unescaped.
- */ - public function get username() : String - { - return URI.unescapeChars(_username); - } - public function set username(usernameStr:String) : void - { - _username = URI.fastEscapeChars(usernameStr, URI.URIuserpassExcludedBitmap); - - // Only hierarchical URI's can have a username. - this.hierState = true; - } - - - /** - * The password of the URI. Similar to username. - * @see URI.username - */ - public function get password() : String - { - return URI.unescapeChars(_password); - } - public function set password(passwordStr:String) : void - { - _password = URI.fastEscapeChars(passwordStr, - URI.URIuserpassExcludedBitmap); - - // Only hierarchical URI's can have a password. - this.hierState = true; - } - - - /** - * The host port number. Only valid for hierarchical URI's. If - * the URI is relative, this will be an empty string. URI's can - * contain the port number of the remote host: - * - *http://site.com:8080/index.htm
- */ - public function get port() : String - { - return URI.unescapeChars(_port); - } - public function set port(portStr:String) : void - { - _port = URI.escapeChars(portStr); - - // Only hierarchical URI's can have a port. - this.hierState = true; - } - - - /** - * The path portion of the URI. Only valid for hierarchical - * URI's. When setting this value, the string - * given is assumed to be unescaped. When retrieving this - * value, the resulting string is unescaped. - * - *The path portion can be in one of two formats. 1) an absolute - * path, or 2) a relative path. An absolute path starts with a - * slash ('/'), a relative path does not.
- * - *An absolute path may look like:
- *A relative path may look like:
- *Paths can be absolute or relative. Note that this not the same as - * an absolute or relative URI. An absolute URI can only have absolute - * paths. For example:
- * - *This absolute URI has an absolute path of "/path/to/file.htm".
- * - *Relative URI's can have either absolute paths or relative paths. - * All of the following relative URI's are valid:
- * - *This accessor should only be used if a custom query syntax - * is used. This URI class supports the common "param=value" - * style query syntax via the get/setQueryValue() and - * get/setQueryByMap() functions. Those functions should be used - * instead if the common syntax is being used. - * - *
The URI RFC does not specify any particular - * syntax for the query part of a URI. It is intended to allow - * any format that can be agreed upon by the two communicating hosts. - * However, most systems have standardized on the typical CGI - * format:
- * - *This class has specific support for this query syntax
- * - *This common query format is an array of name/value - * pairs with its own syntax that is different from the overall URI - * syntax. The query has its own escaping logic. For a query part - * to be properly escaped and unescaped, it must be split into its - * component parts. This accessor escapes/unescapes the entire query - * part without regard for it's component parts. This has the - * possibliity of leaving the query string in an ambiguious state in - * regards to its syntax. If the contents of the query part are - * important, it is recommended that get/setQueryValue() or - * get/setQueryByMap() are used instead.
- * - * If a different query syntax is being used, a subclass of URI - * can be created to handle that specific syntax. - * - * @see URI.getQueryValue, URI.getQueryByMap - */ - public function get query() : String - { - return URI.unescapeChars(_query); - } - public function set query(queryStr:String) : void - { - _query = URI.fastEscapeChars(queryStr, URI.URIqueryExcludedBitmap); - - // both hierarchical and non-hierarchical URI's can - // have a query. Do not set the hierState. - } - - /** - * Accessor to the raw query data. If you are using a custom query - * syntax, this accessor can be used to get and set the query part - * directly with no escaping/unescaping. This should ONLY be used - * if your application logic is handling custom query logic and - * handling the proper escaping of the query part. - */ - public function get queryRaw() : String - { - return _query; - } - public function set queryRaw(queryStr:String) : void - { - _query = queryStr; - } - - - /** - * The fragment (anchor) portion of the URI. This is valid for - * both hierarchical and non-hierarchical URI's. - */ - public function get fragment() : String - { - return URI.unescapeChars(_fragment); - } - public function set fragment(fragmentStr:String) : void - { - _fragment = URI.fastEscapeChars(fragmentStr, URIfragmentExcludedBitmap); - - // both hierarchical and non-hierarchical URI's can - // have a fragment. Do not set the hierState. - } - - - /** - * The non-hierarchical part of the URI. For example, if - * this URI object represents "mailto:somebody@company.com", - * this will contain "somebody@company.com". This is valid only - * for non-hierarchical URI's. - */ - public function get nonHierarchical() : String - { - return URI.unescapeChars(_nonHierarchical); - } - public function set nonHierarchical(nonHier:String) : void - { - _nonHierarchical = URI.fastEscapeChars(nonHier, URInonHierexcludedBitmap); - - // This is a non-hierarchical URI. - this.hierState = false; - } - - - /** - * Quick shorthand accessor to set the parts of this URI. - * The given parts are assumed to be in unescaped form. If - * the URI is non-hierarchical (e.g. mailto:) you will need - * to call SetScheme() and SetNonHierarchical(). - */ - public function setParts(schemeStr:String, authorityStr:String, - portStr:String, pathStr:String, queryStr:String, - fragmentStr:String) : void - { - this.scheme = schemeStr; - this.authority = authorityStr; - this.port = portStr; - this.path = pathStr; - this.query = queryStr; - this.fragment = fragmentStr; - - hierState = true; - } - - - /** - * URI escapes the given character string. This is similar in function - * to the global encodeURIComponent() function in ActionScript, but is - * slightly different in regards to which characters get escaped. This - * escapes the characters specified in the URIbaselineExluded set (see class - * static members). This is needed for this class to work properly. - * - *If a different set of characters need to be used for the escaping, - * you may use fastEscapeChars() and specify a custom URIEncodingBitmap - * that contains the characters your application needs escaped.
- * - *Never pass a full URI to this function. A URI can only be properly - * escaped/unescaped when split into its component parts (see RFC 3986 - * section 2.4). This is due to the fact that the URI component separators - * could be characters that would normally need to be escaped.
- * - * @param unescaped character string to be escaped. - * - * @return escaped character string - * - * @see encodeURIComponent - * @see fastEscapeChars - */ - static public function escapeChars(unescaped:String) : String - { - // This uses the excluded set by default. - return fastEscapeChars(unescaped, URI.URIbaselineExcludedBitmap); - } - - - /** - * Unescape any URI escaped characters in the given character - * string. - * - *Never pass a full URI to this function. A URI can only be properly - * escaped/unescaped when split into its component parts (see RFC 3986 - * section 2.4). This is due to the fact that the URI component separators - * could be characters that would normally need to be escaped.
- * - * @param escaped the escaped string to be unescaped. - * - * @return unescaped string. - */ - static public function unescapeChars(escaped:String /*, onlyHighASCII:Boolean = false*/) : String - { - // We can just use the default AS function. It seems to - // decode everything correctly - var unescaped:String; - unescaped = decodeURIComponent(escaped); - return unescaped; - } - - /** - * Performance focused function that escapes the given character - * string using the given URIEncodingBitmap as the rule for what - * characters need to be escaped. This function is used by this - * class and can be used externally to this class to perform - * escaping on custom character sets. - * - *Never pass a full URI to this function. A URI can only be properly - * escaped/unescaped when split into its component parts (see RFC 3986 - * section 2.4). This is due to the fact that the URI component separators - * could be characters that would normally need to be escaped.
- * - * @param unescaped the unescaped string to be escaped - * @param bitmap the set of characters that need to be escaped - * - * @return the escaped string. - */ - static public function fastEscapeChars(unescaped:String, bitmap:URIEncodingBitmap) : String - { - var escaped:String = ""; - var c:String; - var x:int, i:int; - - for (i = 0; i < unescaped.length; i++) - { - c = unescaped.charAt(i); - - x = bitmap.ShouldEscape(c); - if (x) - { - c = x.toString(16); - if (c.length == 1) - c = "0" + c; - - c = "%" + c; - c = c.toUpperCase(); - } - - escaped += c; - } - - return escaped; - } - - - /** - * Is this URI of a particular scheme type? For example, - * passing "http" to a URI object that represents the URI - * "http://site.com/" would return true. - * - * @param scheme scheme to check for - * - * @return true if this URI object is of the given type, false - * otherwise. - */ - public function isOfType(scheme:String) : Boolean - { - // Schemes are never case sensitive. Ignore case. - scheme = scheme.toLowerCase(); - return (this._scheme == scheme); - } - - - /** - * Get the value for the specified named in the query part. This - * assumes the query part of the URI is in the common - * "name1=value1&name2=value2" syntax. Do not call this function - * if you are using a custom query syntax. - * - * @param name name of the query value to get. - * - * @return the value of the query name, empty string if the - * query name does not exist. - */ - public function getQueryValue(name:String) : String - { - var map:Object; - var item:String; - var value:String; - - map = getQueryByMap(); - - for (item in map) - { - if (item == name) - { - value = map[item]; - return value; - } - } - - // Didn't find the specified key - return new String(""); - } - - - /** - * Set the given value on the given query name. If the given name - * does not exist, it will automatically add this name/value pair - * to the query. If null is passed as the value, it will remove - * the given item from the query. - * - *This automatically escapes any characters that may conflict with - * the query syntax so that they are "safe" within the query. The - * strings passed are assumed to be literal unescaped name and value.
- * - * @param name name of the query value to set - * @param value value of the query item to set. If null, this will - * force the removal of this item from the query. - */ - public function setQueryValue(name:String, value:String) : void - { - var map:Object; - - map = getQueryByMap(); - - // If the key doesn't exist yet, this will create a new pair in - // the map. If it does exist, this will overwrite the previous - // value, which is what we want. - map[name] = value; - - setQueryByMap(map); - } - - - /** - * Get the query of the URI in an Object class that allows for easy - * access to the query data via Object accessors. For example: - * - *Sometimes URI's are constructed by hand using strings outside - * this class. In those cases, it is unlikely the URI has been - * properly escaped. This function forcefully escapes this URI - * by unescaping each part and then re-escaping it. If the URI - * did not have any escaping, the first unescape will do nothing - * and then the re-escape will properly escape everything. If - * the URI was already escaped, the unescape and re-escape will - * essentally be a no-op. This provides a safe way to make sure - * a URI is in the proper escaped form.
- */ - public function forceEscape() : void - { - // The accessors for each of the members will unescape - // and then re-escape as we get and assign them. - - // Handle the parts that are common for both hierarchical - // and non-hierarchical URI's - this.scheme = this.scheme; - this.setQueryByMap(this.getQueryByMap()); - this.fragment = this.fragment; - - if (isHierarchical()) - { - this.authority = this.authority; - this.path = this.path; - this.port = this.port; - this.username = this.username; - this.password = this.password; - } - else - { - this.nonHierarchical = this.nonHierarchical; - } - } - - - /** - * Does this URI point to a resource of the given file type? - * Given a file extension (or just a file name, this will strip the - * extension), check to see if this URI points to a file of that - * type. - * - * @param extension string that contains a file extension with or - * without a dot ("html" and ".html" are both valid), or a file - * name with an extension (e.g. "index.html"). - * - * @return true if this URI points to a resource with the same file - * file extension as the extension provided, false otherwise. - */ - public function isOfFileType(extension:String) : Boolean - { - var thisExtension:String; - var index:int; - - index = extension.lastIndexOf("."); - if (index != -1) - { - // Strip the extension - extension = extension.substr(index + 1); - } - else - { - // The caller passed something without a dot in it. We - // will assume that it is just a plain extension (e.g. "html"). - // What they passed is exactly what we want - } - - thisExtension = getExtension(true); - - if (thisExtension == "") - return false; - - // Compare the extensions ignoring case - if (compareStr(thisExtension, extension, false) == 0) - return true; - else - return false; - } - - - /** - * Get the ".xyz" file extension from the filename in the URI. - * For example, if we have the following URI: - * - *This will return ".html".
- * - * @param minusDot If true, this will strip the dot from the extension. - * If true, the above example would have returned "html". - * - * @return the file extension - */ - public function getExtension(minusDot:Boolean = false) : String - { - var filename:String = getFilename(); - var extension:String; - var index:int; - - if (filename == "") - return String(""); - - index = filename.lastIndexOf("."); - - // If it doesn't have an extension, or if it is a "hidden" file, - // it doesn't have an extension. Hidden files on unix start with - // a dot (e.g. ".login"). - if (index == -1 || index == 0) - return String(""); - - extension = filename.substr(index); - - // If the caller does not want the dot, remove it. - if (minusDot && extension.charAt(0) == ".") - extension = extension.substr(1); - - return extension; - } - - /** - * Quick function to retrieve the file name off the end of a URI. - * - *For example, if the URI is:
- *this function will return "file.html".
- * - * @param minusExtension true if the file extension should be stripped - * - * @return the file name. If this URI is a directory, the return - * value will be empty string. - */ - public function getFilename(minusExtension:Boolean = false) : String - { - if (isDirectory()) - return String(""); - - var pathStr:String = this.path; - var filename:String; - var index:int; - - // Find the last path separator. - index = pathStr.lastIndexOf("/"); - - if (index != -1) - filename = pathStr.substr(index + 1); - else - filename = pathStr; - - if (minusExtension) - { - // The caller has requested that the extension be removed - index = filename.lastIndexOf("."); - - if (index != -1) - filename = filename.substr(0, index); - } - - return filename; - } - - - /** - * @private - * Helper function to compare strings. - * - * @return true if the two strings are identical, false otherwise. - */ - static protected function compareStr(str1:String, str2:String, - sensitive:Boolean = true) : Boolean - { - if (sensitive == false) - { - str1 = str1.toLowerCase(); - str2 = str2.toLowerCase(); - } - - return (str1 == str2) - } - - /** - * Based on the type of this URI (http, ftp, etc.) get - * the default port used for that protocol. This is - * just intended to be a helper function for the most - * common cases. - */ - public function getDefaultPort() : String - { - if (_scheme == "http") - return String("80"); - else if (_scheme == "ftp") - return String("21"); - else if (_scheme == "file") - return String(""); - else if (_scheme == "sftp") - return String("22"); // ssh standard port - else - { - // Don't know the port for this URI type - return String(""); - } - } - - /** - * @private - * - * This resolves the given URI if the application has a - * resolver interface defined. This function does not - * modify the passed in URI and returns a new URI. - */ - static protected function resolve(uri:URI) : URI - { - var copy:URI = new URI(); - copy.copyURI(uri); - - if (_resolver != null) - { - // A resolver class has been registered. Call it. - return _resolver.resolve(copy); - } - else - { - // No resolver. Nothing to do, but we don't - // want to reuse the one passed in. - return copy; - } - } - - /** - * Accessor to set and get the resolver object used by all URI - * objects to dynamically resolve URI's before comparison. - */ - static public function set resolver(resolver:IURIResolver) : void - { - _resolver = resolver; - } - static public function get resolver() : IURIResolver - { - return _resolver; - } - - /** - * Given another URI, return this URI object's relation to the one given. - * URI's can have 1 of 4 possible relationships. They can be unrelated, - * equal, parent, or a child of the given URI. - * - * @param uri URI to compare this URI object to. - * @param caseSensitive true if the URI comparison should be done - * taking case into account, false if the comparison should be - * performed case insensitive. - * - * @return URI.NOT_RELATED, URI.CHILD, URI.PARENT, or URI.EQUAL - */ - public function getRelation(uri:URI, caseSensitive:Boolean = true) : int - { - // Give the app a chance to resolve these URI's before we compare them. - var thisURI:URI = URI.resolve(this); - var thatURI:URI = URI.resolve(uri); - - if (thisURI.isRelative() || thatURI.isRelative()) - { - // You cannot compare relative URI's due to their lack of context. - // You could have two relative URI's that look like: - // ../../images/ - // ../../images/marketing/logo.gif - // These may appear related, but you have no overall context - // from which to make the comparison. The first URI could be - // from one site and the other URI could be from another site. - return URI.NOT_RELATED; - } - else if (thisURI.isHierarchical() == false || thatURI.isHierarchical() == false) - { - // One or both of the URI's are non-hierarchical. - if (((thisURI.isHierarchical() == false) && (thatURI.isHierarchical() == true)) || - ((thisURI.isHierarchical() == true) && (thatURI.isHierarchical() == false))) - { - // XOR. One is hierarchical and the other is - // non-hierarchical. They cannot be compared. - return URI.NOT_RELATED; - } - else - { - // They are both non-hierarchical - if (thisURI.scheme != thatURI.scheme) - return URI.NOT_RELATED; - - if (thisURI.nonHierarchical != thatURI.nonHierarchical) - return URI.NOT_RELATED; - - // The two non-hierarcical URI's are equal. - return URI.EQUAL; - } - } - - // Ok, this URI and the one we are being compared to are both - // absolute hierarchical URI's. - - if (thisURI.scheme != thatURI.scheme) - return URI.NOT_RELATED; - - if (thisURI.authority != thatURI.authority) - return URI.NOT_RELATED; - - var thisPort:String = thisURI.port; - var thatPort:String = thatURI.port; - - // Different ports are considered completely different servers. - if (thisPort == "") - thisPort = thisURI.getDefaultPort(); - if (thatPort == "") - thatPort = thatURI.getDefaultPort(); - - // Check to see if the port is the default port. - if (thisPort != thatPort) - return URI.NOT_RELATED; - - if (compareStr(thisURI.path, thatURI.path, caseSensitive)) - return URI.EQUAL; - - // Special case check. If we are here, the scheme, authority, - // and port match, and it is not a relative path, but the - // paths did not match. There is a special case where we - // could have: - // http://something.com/ - // http://something.com - // Technically, these are equal. So lets, check for this case. - var thisPath:String = thisURI.path; - var thatPath:String = thatURI.path; - - if ( (thisPath == "/" || thatPath == "/") && - (thisPath == "" || thatPath == "") ) - { - // We hit the special case. These two are equal. - return URI.EQUAL; - } - - // Ok, the paths do not match, but one path may be a parent/child - // of the other. For example, we may have: - // http://something.com/path/to/homepage/ - // http://something.com/path/to/homepage/images/logo.gif - // In this case, the first is a parent of the second (or the second - // is a child of the first, depending on which you compare to the - // other). To make this comparison, we must split the path into - // its component parts (split the string on the '/' path delimiter). - // We then compare the - var thisParts:Array, thatParts:Array; - var thisPart:String, thatPart:String; - var i:int; - - thisParts = thisPath.split("/"); - thatParts = thatPath.split("/"); - - if (thisParts.length > thatParts.length) - { - thatPart = thatParts[thatParts.length - 1]; - if (thatPart.length > 0) - { - // if the last part is not empty, the passed URI is - // not a directory. There is no way the passed URI - // can be a parent. - return URI.NOT_RELATED; - } - else - { - // Remove the empty trailing part - thatParts.pop(); - } - - // This may be a child of the one passed in - for (i = 0; i < thatParts.length; i++) - { - thisPart = thisParts[i]; - thatPart = thatParts[i]; - - if (compareStr(thisPart, thatPart, caseSensitive) == false) - return URI.NOT_RELATED; - } - - return URI.CHILD; - } - else if (thisParts.length < thatParts.length) - { - thisPart = thisParts[thisParts.length - 1]; - if (thisPart.length > 0) - { - // if the last part is not empty, this URI is not a - // directory. There is no way this object can be - // a parent. - return URI.NOT_RELATED; - } - else - { - // Remove the empty trailing part - thisParts.pop(); - } - - // This may be the parent of the one passed in - for (i = 0; i < thisParts.length; i++) - { - thisPart = thisParts[i]; - thatPart = thatParts[i]; - - if (compareStr(thisPart, thatPart, caseSensitive) == false) - return URI.NOT_RELATED; - } - - return URI.PARENT; - } - else - { - // Both URI's have the same number of path components, but - // it failed the equivelence check above. This means that - // the two URI's are not related. - return URI.NOT_RELATED; - } - - // If we got here, the scheme and authority are the same, - // but the paths pointed to two different locations that - // were in different parts of the file system tree - return URI.NOT_RELATED; - } - - /** - * Given another URI, return the common parent between this one - * and the provided URI. - * - * @param uri the other URI from which to find a common parent - * @para caseSensitive true if this operation should be done - * with case sensitive comparisons. - * - * @return the parent URI if successful, null otherwise. - */ - public function getCommonParent(uri:URI, caseSensitive:Boolean = true) : URI - { - var thisURI:URI = URI.resolve(this); - var thatURI:URI = URI.resolve(uri); - - if(!thisURI.isAbsolute() || !thatURI.isAbsolute() || - thisURI.isHierarchical() == false || - thatURI.isHierarchical() == false) - { - // Both URI's must be absolute hierarchical for this to - // make sense. - return null; - } - - var relation:int = thisURI.getRelation(thatURI); - if (relation == URI.NOT_RELATED) - { - // The given URI is not related to this one. No - // common parent. - return null; - } - - thisURI.chdir("."); - thatURI.chdir("."); - - var strBefore:String, strAfter:String; - do - { - relation = thisURI.getRelation(thatURI, caseSensitive); - if(relation == URI.EQUAL || relation == URI.PARENT) - break; - - // If strBefore and strAfter end up being the same, - // we know we are at the root of the path because - // chdir("..") is doing nothing. - strBefore = thisURI.toString(); - thisURI.chdir(".."); - strAfter = thisURI.toString(); - } - while(strBefore != strAfter); - - return thisURI; - } - - - /** - * This function is used to move around in a URI in a way similar - * to the 'cd' or 'chdir' commands on Unix. These operations are - * completely string based, using the context of the URI to - * determine the position within the path. The heuristics used - * to determine the action are based off Appendix C in RFC 2396. - * - *URI paths that end in '/' are considered paths that point to
- * directories, while paths that do not end in '/' are files. For
- * example, if you execute chdir("d") on the following URI's:
- * 1. http://something.com/a/b/c/ (directory)
- * 2. http://something.com/a/b/c (not directory)
- * you will get:
- * 1. http://something.com/a/b/c/d
- * 2. http://something.com/a/b/d
See RFC 2396, Appendix C for more info.
- * - * @param reference the URI or path to "cd" to. - * @param escape true if the passed reference string should be URI - * escaped before using it. - * - * @return true if the chdir was successful, false otherwise. - */ - public function chdir(reference:String, escape:Boolean = false) : Boolean - { - var uriReference:URI; - var ref:String = reference; - - if (escape) - ref = URI.escapeChars(reference); - - if (ref == "") - { - // NOOP - return true; - } - else if (ref.substr(0, 2) == "//") - { - // Special case. This is an absolute URI but without the scheme. - // Take the scheme from this URI and tack it on. This is - // intended to make working with chdir() a little more - // tolerant. - var final:String = this.scheme + ":" + ref; - - return constructURI(final); - } - else if (ref.charAt(0) == "?") - { - // A relative URI that is just a query part is essentially - // a "./?query". We tack on the "./" here to make the rest - // of our logic work. - ref = "./" + ref; - } - - // Parse the reference passed in as a URI. This way we - // get any query and fragments parsed out as well. - uriReference = new URI(ref); - - if (uriReference.isAbsolute() || - uriReference.isHierarchical() == false) - { - // If the URI given is a full URI, it replaces this one. - copyURI(uriReference); - return true; - } - - - var thisPath:String, thatPath:String; - var thisParts:Array, thatParts:Array; - var thisIsDir:Boolean = false, thatIsDir:Boolean = false; - var thisIsAbs:Boolean = false, thatIsAbs:Boolean = false; - var lastIsDotOperation:Boolean = false; - var curDir:String; - var i:int; - - thisPath = this.path; - thatPath = uriReference.path; - - if (thisPath.length > 0) - thisParts = thisPath.split("/"); - else - thisParts = new Array(); - - if (thatPath.length > 0) - thatParts = thatPath.split("/"); - else - thatParts = new Array(); - - if (thisParts.length > 0 && thisParts[0] == "") - { - thisIsAbs = true; - thisParts.shift(); // pop the first one off the array - } - if (thisParts.length > 0 && thisParts[thisParts.length - 1] == "") - { - thisIsDir = true; - thisParts.pop(); // pop the last one off the array - } - - if (thatParts.length > 0 && thatParts[0] == "") - { - thatIsAbs = true; - thatParts.shift(); // pop the first one off the array - } - if (thatParts.length > 0 && thatParts[thatParts.length - 1] == "") - { - thatIsDir = true; - thatParts.pop(); // pop the last one off the array - } - - if (thatIsAbs) - { - // The reference is an absolute path (starts with a slash). - // It replaces this path wholesale. - this.path = uriReference.path; - - // And it inherits the query and fragment - this.queryRaw = uriReference.queryRaw; - this.fragment = uriReference.fragment; - - return true; - } - else if (thatParts.length == 0 && uriReference.query == "") - { - // The reference must have only been a fragment. Fragments just - // get appended to whatever the current path is. We don't want - // to overwrite any query that may already exist, so this case - // only takes on the new fragment. - this.fragment = uriReference.fragment; - return true; - } - else if (thisIsDir == false && thisParts.length > 0) - { - // This path ends in a file. It goes away no matter what. - thisParts.pop(); - } - - // By default, this assumes the query and fragment of the reference - this.queryRaw = uriReference.queryRaw; - this.fragment = uriReference.fragment; - - // Append the parts of the path from the passed in reference - // to this object's path. - thisParts = thisParts.concat(thatParts); - - for(i = 0; i < thisParts.length; i++) - { - curDir = thisParts[i]; - lastIsDotOperation = false; - - if (curDir == ".") - { - thisParts.splice(i, 1); - i = i - 1; // account for removing this item - lastIsDotOperation = true; - } - else if (curDir == "..") - { - if (i >= 1) - { - if (thisParts[i - 1] == "..") - { - // If the previous is a "..", we must have skipped - // it due to this URI being relative. We can't - // collapse leading ".."s in a relative URI, so - // do nothing. - } - else - { - thisParts.splice(i - 1, 2); - i = i - 2; // move back to account for the 2 we removed - } - } - else - { - // This is the first thing in the path. - - if (isRelative()) - { - // We can't collapse leading ".."s in a relative - // path. Do noting. - } - else - { - // This is an abnormal case. We have dot-dotted up - // past the base of our "file system". This is a - // case where we had a /path/like/this.htm and were - // given a path to chdir to like this: - // ../../../../../../mydir - // Obviously, it has too many ".." and will take us - // up beyond the top of the URI. However, according - // RFC 2396 Appendix C.2, we should try to handle - // these abnormal cases appropriately. In this case, - // we will do what UNIX command lines do if you are - // at the root (/) of the filesystem and execute: - // # cd ../../../../../bin - // Which will put you in /bin. Essentially, the extra - // ".."'s will just get eaten. - - thisParts.splice(i, 1); - i = i - 1; // account for the ".." we just removed - } - } - - lastIsDotOperation = true; - } - } - - var finalPath:String = ""; - - // If the last thing in the path was a "." or "..", then this thing is a - // directory. If the last thing isn't a dot-op, then we don't want to - // blow away any information about the directory (hence the "|=" binary - // assignment). - thatIsDir = thatIsDir || lastIsDotOperation; - - // Reconstruct the path with the abs/dir info we have - finalPath = joinPath(thisParts, thisIsAbs, thatIsDir); - - // Set the path (automatically escaping it) - this.path = finalPath; - - return true; - } - - /** - * @private - * Join an array of path parts back into a URI style path string. - * This is used by the various path logic functions to recombine - * a path. This is different than the standard Array.join() - * function because we need to take into account the starting and - * ending path delimiters if this is an absolute path or a - * directory. - * - * @param parts the Array that contains strings of each path part. - * @param isAbs true if the given path is absolute - * @param isDir true if the given path is a directory - * - * @return the combined path string. - */ - protected function joinPath(parts:Array, isAbs:Boolean, isDir:Boolean) : String - { - var pathStr:String = ""; - var i:int; - - for (i = 0; i < parts.length; i++) - { - if (pathStr.length > 0) - pathStr += "/"; - - pathStr += parts[i]; - } - - // If this path is a directory, tack on the directory delimiter, - // but only if the path contains something. Adding this to an - // empty path would make it "/", which is an absolute path that - // starts at the root. - if (isDir && pathStr.length > 0) - pathStr += "/"; - - if (isAbs) - pathStr = "/" + pathStr; - - return pathStr; - } - - /** - * Given an absolute URI, make this relative URI absolute using - * the given URI as a base. This URI instance must be relative - * and the base_uri must be absolute. - * - * @param base_uri URI to use as the base from which to make - * this relative URI into an absolute URI. - * - * @return true if successful, false otherwise. - */ - public function makeAbsoluteURI(base_uri:URI) : Boolean - { - if (isAbsolute() || base_uri.isRelative()) - { - // This URI needs to be relative, and the base needs to be - // absolute otherwise we won't know what to do! - return false; - } - - // Make a copy of the base URI. We don't want to modify - // the passed URI. - var base:URI = new URI(); - base.copyURI(base_uri); - - // ChDir on the base URI. This will preserve any query - // and fragment we have. - if (base.chdir(toString()) == false) - return false; - - // It worked, so copy the base into this one - copyURI(base); - - return true; - } - - - /** - * Given a URI to use as a base from which this object should be - * relative to, convert this object into a relative URI. For example, - * if you have: - * - *uri1 will have a final value of "../some/file.html"
- * - *Note! This function is brute force. If you have two URI's - * that are completely unrelated, this will still attempt to make - * the relative URI. In that case, you will most likely get a - * relative path that looks something like:
- * - *../../../../../../some/path/to/my/file.html
- * - * @param base_uri the URI from which to make this URI relative - * - * @return true if successful, false if the base_uri and this URI - * are not related, of if error. - */ - public function makeRelativeURI(base_uri:URI, caseSensitive:Boolean = true) : Boolean - { - var base:URI = new URI(); - base.copyURI(base_uri); - - var thisParts:Array, thatParts:Array; - var finalParts:Array = new Array(); - var thisPart:String, thatPart:String, finalPath:String; - var pathStr:String = this.path; - var queryStr:String = this.queryRaw; - var fragmentStr:String = this.fragment; - var i:int; - var diff:Boolean = false; - var isDir:Boolean = false; - - if (isRelative()) - { - // We're already relative. - return true; - } - - if (base.isRelative()) - { - // The base is relative. A relative base doesn't make sense. - return false; - } - - - if ( (isOfType(base_uri.scheme) == false) || - (this.authority != base_uri.authority) ) - { - // The schemes and/or authorities are different. We can't - // make a relative path to something that is completely - // unrelated. - return false; - } - - // Record the state of this URI - isDir = isDirectory(); - - // We are based of the directory of the given URI. We need to - // make sure the URI is pointing to a directory. Changing - // directory to "." will remove any file name if the base is - // not a directory. - base.chdir("."); - - thisParts = pathStr.split("/"); - thatParts = base.path.split("/"); - - if (thisParts.length > 0 && thisParts[0] == "") - thisParts.shift(); - - if (thisParts.length > 0 && thisParts[thisParts.length - 1] == "") - { - isDir = true; - thisParts.pop(); - } - - if (thatParts.length > 0 && thatParts[0] == "") - thatParts.shift(); - if (thatParts.length > 0 && thatParts[thatParts.length - 1] == "") - thatParts.pop(); - - - // Now that we have the paths split into an array of directories, - // we can compare the two paths. We start from the left of side - // of the path and start comparing. When we either run out of - // directories (one path is longer than the other), or we find - // a directory that is different, we stop. The remaining parts - // of each path is then used to determine the relative path. For - // example, lets say we have: - // path we want to make relative: /a/b/c/d/e.txt - // path to use as base for relative: /a/b/f/ - // - // This loop will start at the left, and remove directories - // until we get a mismatch or run off the end of one of them. - // In this example, the result will be: - // c/d/e.txt - // f - // - // For every part left over in the base path, we prepend a ".." - // to the relative to get the final path: - // ../c/d/e.txt - while(thatParts.length > 0) - { - if (thisParts.length == 0) - { - // we matched all there is to match, we are done. - // This is the case where "this" object is a parent - // path of the given URI. eg: - // this.path = /a/b/ (thisParts) - // base.path = /a/b/c/d/e/ (thatParts) - break; - } - - thisPart = thisParts[0]; - thatPart = thatParts[0]; - - if (compareStr(thisPart, thatPart, caseSensitive)) - { - thisParts.shift(); - thatParts.shift(); - } - else - break; - } - - // If there are any path info left from the base URI, that means - // **this** object is above the given URI in the file tree. For - // each part left over in the given URI, we need to move up one - // directory to get where we are. - var dotdot:String = ".."; - for (i = 0; i < thatParts.length; i++) - { - finalParts.push(dotdot); - } - - // Append the parts of this URI to any dot-dot's we have - finalParts = finalParts.concat(thisParts); - - // Join the parts back into a path - finalPath = joinPath(finalParts, false /* not absolute */, isDir); - - if (finalPath.length == 0) - { - // The two URI's are exactly the same. The proper relative - // path is: - finalPath = "./"; - } - - // Set the parts of the URI, preserving the original query and - // fragment parts. - setParts("", "", "", finalPath, queryStr, fragmentStr); - - return true; - } - - /** - * Given a string, convert it to a URI. The string could be a - * full URI that is improperly escaped, a malformed URI (e.g. - * missing a protocol like "www.something.com"), a relative URI, - * or any variation there of. - * - *The intention of this function is to take anything that a - * user might manually enter as a URI/URL and try to determine what - * they mean. This function differs from the URI constructor in - * that it makes some assumptions to make it easy to import user - * entered URI data.
- * - *This function is intended to be a helper function. - * It is not all-knowning and will probably make mistakes - * when attempting to parse a string of unknown origin. If - * your applicaiton is receiving input from the user, your - * application should already have a good idea what the user - * should be entering, and your application should be - * pre-processing the user's input to make sure it is well formed - * before passing it to this function.
- * - *It is assumed that the string given to this function is - * something the user may have manually entered. Given this, - * the URI string is probably unescaped or improperly escaped. - * This function will attempt to properly escape the URI by - * using forceEscape(). The result is that a toString() call - * on a URI that was created from unknownToURI() may not match - * the input string due to the difference in escaping.
- * - * @param unknown a potental URI string that should be parsed - * and loaded into this object. - * @param defaultScheme if it is determined that the passed string - * looks like a URI, but it is missing the scheme part, this - * string will be used as the missing scheme. - * - * @return true if the given string was successfully parsed into - * a valid URI object, false otherwise. - */ - public function unknownToURI(unknown:String, defaultScheme:String = "http") : Boolean - { - var temp:String; - - if (unknown.length == 0) - { - this.initialize(); - return false; - } - - // Some users love the backslash key. Fix it. - unknown = unknown.replace(/\\/g, "/"); - - // Check for any obviously missing scheme. - if (unknown.length >= 2) - { - temp = unknown.substr(0, 2); - if (temp == "//") - unknown = defaultScheme + ":" + unknown; - } - - if (unknown.length >= 3) - { - temp = unknown.substr(0, 3); - if (temp == "://") - unknown = defaultScheme + unknown; - } - - // Try parsing it as a normal URI - var uri:URI = new URI(unknown); - - if (uri.isHierarchical() == false) - { - if (uri.scheme == UNKNOWN_SCHEME) - { - this.initialize(); - return false; - } - - // It's a non-hierarchical URI - copyURI(uri); - forceEscape(); - return true; - } - else if ((uri.scheme != UNKNOWN_SCHEME) && - (uri.scheme.length > 0)) - { - if ( (uri.authority.length > 0) || - (uri.scheme == "file") ) - { - // file://... URI - copyURI(uri); - forceEscape(); // ensure proper escaping - return true; - } - else if (uri.authority.length == 0 && uri.path.length == 0) - { - // It's is an incomplete URI (eg "http://") - - setParts(uri.scheme, "", "", "", "", ""); - return false; - } - } - else - { - // Possible relative URI. We can only detect relative URI's - // that start with "." or "..". If it starts with something - // else, the parsing is ambiguous. - var path:String = uri.path; - - if (path == ".." || path == "." || - (path.length >= 3 && path.substr(0, 3) == "../") || - (path.length >= 2 && path.substr(0, 2) == "./") ) - { - // This is a relative URI. - copyURI(uri); - forceEscape(); - return true; - } - } - - // Ok, it looks like we are just a normal URI missing the scheme. Tack - // on the scheme. - uri = new URI(defaultScheme + "://" + unknown); - - // Check to see if we are good now - if (uri.scheme.length > 0 && uri.authority.length > 0) - { - // It was just missing the scheme. - copyURI(uri); - forceEscape(); // Make sure we are properly encoded. - return true; - } - - // don't know what this is - this.initialize(); - return false; - } - - } // end URI class -} // end package \ No newline at end of file