-------------------------------------------------------------------------------
jre-utils v0.7


USAGE
=====

To start, create and initiate the object. It's as simple as this: 

	<cfset jre = CreateObject("component","jre-utils").init()/>


However, you may want to change the default options...

	<cfset jre = CreateObject("component","jre-utils").init
		( DefaultFlags = 'CASE_INSENSITIVE' , BackslashReferences = true )/>

For details on what options are available, see "INIT OPTIONS" section below.



INIT OPTIONS
============

	DefaultFlags
		Comma-delimited list of Regex Pattern flags.
		Default value is "MULTILINE".
		See "REGEX PATTERN FLAGS" for details of available flags.

	IgnoreInvalidFlags
		Boolean value, defaults to false.
		Enable IgnoreInvalidFlags to ignore invalid flags, instead of the 
		default action of throwing an error.

	BackslashReferences
		Boolean value, defaults to false.
		Java references uses $, whilst CF uses \ instead.
		Enable BackslashReferences to allow \ instead of $ in replace values. 

	SetNullGroupsBlank:
		Boolean value, defaults to true
		When returning backreferences (from getGroups or matchGroups):
		if true, any groups with no value are set to empty string;
		if false, they are left as null.



FUNCTIONS
=========

	For complete function reference, see functions.txt

	get( Text , Pattern , [Flags] ) - Array
		Returns an Array containing the matches of Pattern in Text.
		Allows optional comma-delimited list of flags (see "REGEX PATTERN FLAGS")

	replace ( Text , Pattern , Replacement , [Scope] ) - String
		Returns the Text after applying Replacement to match(es) of Pattern.
		Set Scope to "ALL" to apply to all matches, otherwise only first match.
		Replacement can be a standard RegEx replacement string, or the name of
		a callback function to be applied to each match in turn.
		Callback function should accept two arguments, the string match,
		and an optional array of any groups found within the regex.
		
		This is an example callback function that does nothing with the match:
		<cffunction name="CallbackFunction" returntype="String" output="false">
			<cfargument name="Match"  type="String"/>
			<cfargument name="Groups" type="Array" default="#ArrayNew(1)#"/>
		
			<cfreturn Arguments.Match/>
		</cffunction>




REGEX PATTERN FLAGS
===================

The following can be used for the DefaultFlags option or the get() functions:

	UNIX_LINES        Only \n is recognised as a line terminator (\r is not)
	                  Equivalent to (?d) embedded expression.

	CASE_INSENSITIVE  Enables case-insensitive matching, by default only 
	                  for the US-ASCII charset. (See UNICODE_CASE below)
	                  Equivalent to (?i) embedded expression.

	UNICODE_CASE      Allows CASE_INSENSITIVE to also work for Unicode.
	                  Equivalent to (?u) embedded expression.

	COMMENTS          Permits whitespace and single-line comments in the 
	                  regex pattern.
	                  Equivalent to (?x) embedded expression.

	MULTILINE         Enables multiline mode, so ^ and $ also matches
	                  against the start/end of each line. 
	                  By default ^ and $ do not match each line, only
	                  against the entire string.
	                  Equivalent to (?m) embedded expression.

	DOTALL            Enables dotall mode, so the . also matches line 
	                  terminators. By default . excludes line terminators.
	                  Equivalent to (?s) embedded expression.

	CANON_EQ          Enables canonical equivalence. When this flag is 
	                  specified then two characters will be considered to 
	                  match if their full canonical decompositions match.





SUPPORT
=======

For Regular Expression help, use the RegEx mailing list on House of Fusion:
http://www.houseoffusion.com/groups/regex/

The reference sheets on Regular-Expressions.info can be useful:
http://www.regular-expressions.info/reference.html

For support on this project, please visit the project page at Hybridchill:
http://www.hybridchill.com/projects/jre-utils.html




CREDITS
=======

jre-utils project created and maintained by Peter Boughton
http://www.bpsite.net

Much of the original code re-factored from UDFs originally by Ben Nadel
http://www.bennadel.com

Descriptions of Regex Pattern flags adapted from Java documentation:
http://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html




LICENSING
=========

jre-utils is released under the modified BSD license.
(see included bsd-license.txt for details)




-------------------------------------------------------------------------------