[ci skip] Update the Loader class docs

1 files changed, 298 insertions, 233 deletions

diff --git a/user_guide_src/source/libraries/loader.rst b/user_guide_src/source/libraries/loader.rst
index b048f4881..20e1c1d3c 100644
--- a/user_guide_src/source/libraries/loader.rst
+++ b/user_guide_src/source/libraries/loader.rst
@@ -11,337 +11,402 @@ can be libraries (classes) :doc:`View files <../general/views>`,
 .. note:: This class is initialized automatically by the system so there
 	is no need to do it manually.
 
-The following methods are available in this class:
+.. contents::
+  :local:
 
-$this->load->library('class_name', $config, 'object name')
-==========================================================
+.. raw:: html
 
-This method is used to load core classes. Where class_name is the
-name of the class you want to load.
+  <div class="custom-index container"></div>
 
-.. note:: We use the terms "class" and "library" interchangeably.
+Application "Packages"
+======================
 
-For example, if you would like to send email with CodeIgniter, the first
-step is to load the email class within your controller::
+An application package allows for the easy distribution of complete sets
+of resources in a single directory, complete with its own libraries,
+models, helpers, config, and language files. It is recommended that
+these packages be placed in the application/third_party directory. Below
+is a sample map of an package directory.
 
-	$this->load->library('email');
+The following is an example of a directory for an application package
+named "Foo Bar".
 
-Once loaded, the library will be ready for use, using
-$this->email->*some_method*().
+::
 
-Library files can be stored in subdirectories within the main
-"libraries" directory, or within your personal application/libraries
-directory. To load a file located in a subdirectory, simply include the
-path, relative to the "libraries" directory. For example, if you have
-file located at::
+	/application/third_party/foo_bar
 
-	libraries/flavors/Chocolate.php
+	config/
+	helpers/
+	language/
+	libraries/
+	models/
 
-You will load it using::
+Whatever the purpose of the "Foo Bar" application package, it has its
+own config files, helpers, language files, libraries, and models. To use
+these resources in your controllers, you first need to tell the Loader
+that you are going to be loading resources from a package, by adding the
+package path via the ``add_package_path()`` method.
 
-	$this->load->library('flavors/chocolate');
+Package view files
+------------------
 
-You may nest the file in as many subdirectories as you want.
+By Default, package view files paths are set when ``add_package_path()``
+is called. View paths are looped through, and once a match is
+encountered that view is loaded.
 
-Additionally, multiple libraries can be loaded at the same time by
-passing an array of libraries to the load method.
+In this instance, it is possible for view naming collisions within
+packages to occur, and possibly the incorrect package being loaded. To
+ensure against this, set an optional second parameter of FALSE when
+calling ``add_package_path()``.
 
 ::
 
-	$this->load->library(array('email', 'table'));
+	$this->load->add_package_path(APPPATH.'my_app', FALSE);
+	$this->load->view('my_app_index'); // Loads
+	$this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE
 
-Setting options
----------------
+	// Reset things
+	$this->load->remove_package_path(APPPATH.'my_app');
 
-The second (optional) parameter allows you to optionally pass
-configuration setting. You will typically pass these as an array::
+	// Again without the second parameter:
+	$this->load->add_package_path(APPPATH.'my_app');
+	$this->load->view('my_app_index'); // Loads
+	$this->load->view('welcome_message'); // Loads
 
-	$config = array (
-		'mailtype' => 'html',
-		'charset'  => 'utf-8,
-		'priority' => '1'
-	);
+***************
+Class Reference
+***************
 
-	$this->load->library('email', $config);
+.. class:: CI_Loader
 
-Config options can usually also be set via a config file. Each library
-is explained in detail in its own page, so please read the information
-regarding each one you would like to use.
+	.. method:: library($library[, $params = NULL[, $object_name = NULL]])
 
-Please take note, when multiple libraries are supplied in an array for
-the first parameter, each will receive the same parameter information.
+		:param mixed $library: Library name as a string or an array with multiple libraries
+		:param array $params: Optional array of parameters to pass to the loaded library's constructor
+		:param string $object_name: Optional object name to assign the library to
+		:returns: void
 
-Assigning a Library to a different object name
-----------------------------------------------
+		This method is used to load core classes.
 
-If the third (optional) parameter is blank, the library will usually be
-assigned to an object with the same name as the library. For example, if
-the library is named Calendar, it will be assigned to a variable named
-$this->calendar.
+		.. note:: We use the terms "class" and "library" interchangeably.
 
-If you prefer to set your own class names you can pass its value to the
-third parameter::
+		For example, if you would like to send email with CodeIgniter, the first
+		step is to load the email class within your controller::
 
-	$this->load->library('calendar', '', 'my_calendar');
+			$this->load->library('email');
 
-	// Calendar class is now accessed using:
-	$this->my_calendar
+		Once loaded, the library will be ready for use, using ``$this->email``.
 
-Please take note, when multiple libraries are supplied in an array for
-the first parameter, this parameter is discarded.
+		Library files can be stored in subdirectories within the main
+		"libraries" directory, or within your personal *application/libraries*
+		directory. To load a file located in a subdirectory, simply include the
+		path, relative to the "libraries" directory. For example, if you have
+		file located at::
 
-$this->load->driver('parent_name', $config, 'object name')
-==========================================================
+			libraries/flavors/Chocolate.php
 
-This method is used to load driver libraries. Where parent_name is the
-name of the parent class you want to load.
+		You will load it using::
 
-As an example, if you would like to use sessions with CodeIgniter, the first
-step is to load the session driver within your controller::
+			$this->load->library('flavors/chocolate');
 
-	$this->load->driver('session');
+		You may nest the file in as many subdirectories as you want.
 
-Once loaded, the library will be ready for use, using
-$this->session->*some_method*().
+		Additionally, multiple libraries can be loaded at the same time by
+		passing an array of libraries to the load method.
+		::
 
-Driver files must be stored in a subdirectory within the main
-"libraries" directory, or within your personal application/libraries
-directory. The subdirectory must match the parent class name. Read the
-:doc:`Drivers <../general/drivers>` description for details.
+			$this->load->library(array('email', 'table'));
 
-Additionally, multiple driver libraries can be loaded at the same time by
-passing an array of drivers to the load method.
+		Setting options
+		---------------
 
-::
+		The second (optional) parameter allows you to optionally pass
+		configuration setting. You will typically pass these as an array::
 
-	$this->load->driver(array('session', 'cache'));
+			$config = array (
+				'mailtype' => 'html',
+				'charset'  => 'utf-8,
+				'priority' => '1'
+			);
 
-Setting options
----------------
+			$this->load->library('email', $config);
 
-The second (optional) parameter allows you to optionally pass
-configuration settings. You will typically pass these as an array::
+		Config options can usually also be set via a config file. Each library
+		is explained in detail in its own page, so please read the information
+		regarding each one you would like to use.
 
-	$config = array(
-		'sess_driver' => 'cookie',
-		'sess_encrypt_cookie'  => true,
-		'encryption_key' => 'mysecretkey'
-	);
+		Please take note, when multiple libraries are supplied in an array for
+		the first parameter, each will receive the same parameter information.
 
-	$this->load->driver('session', $config);
+		Assigning a Library to a different object name
+		----------------------------------------------
 
-Config options can usually also be set via a config file. Each library
-is explained in detail in its own page, so please read the information
-regarding each one you would like to use.
+		If the third (optional) parameter is blank, the library will usually be
+		assigned to an object with the same name as the library. For example, if
+		the library is named Calendar, it will be assigned to a variable named
+		``$this->calendar``.
 
-Assigning a Driver to a different object name
----------------------------------------------
+		If you prefer to set your own class names you can pass its value to the
+		third parameter::
 
-If the third (optional) parameter is blank, the library will be assigned
-to an object with the same name as the parent class. For example, if
-the library is named Session, it will be assigned to a variable named
-``$this->session``.
+			$this->load->library('calendar', NULL, 'my_calendar');
 
-If you prefer to set your own class names you can pass its value to the
-third parameter::
+			// Calendar class is now accessed using:
+			$this->my_calendar
 
-	$this->load->library('session', '', 'my_session');
+		Please take note, when multiple libraries are supplied in an array for
+		the first parameter, this parameter is discarded.
 
-	// Session class is now accessed using:
-	$this->my_session
+	.. method:: driver($library[, $params = NULL[, $object_name]])
 
-.. note:: Driver libraries may also be loaded with the ``library()`` method,
-	but it is faster to use ``driver()``.
+		:param mixed $library: Library name as a string or an array with multiple libraries
+		:param array $params: Optional array of parameters to pass to the loaded library's constructor
+		:param string $object_name: Optional object name to assign the library to
+		:returns: void
 
-$this->load->view('file_name', $data, TRUE/FALSE)
-=================================================
+		This method is used to load driver libraries, acts very much like the
+		``library()`` method.
 
-This method is used to load your View files. If you haven't read the
-:doc:`Views <../general/views>` section of the user guide it is
-recommended that you do since it shows you how this method is
-typically used.
+		As an example, if you would like to use sessions with CodeIgniter, the first
+		step is to load the session driver within your controller::
 
-The first parameter is required. It is the name of the view file you
-would like to load.
+			$this->load->driver('session');
 
-.. note:: The .php file extension does not need to be specified unless
-	you use something other than .php.
+		Once loaded, the library will be ready for use, using ``$this->session``.
 
-The second **optional** parameter can take an associative array or an
-object as input, which it runs through the PHP
-`extract() <http://www.php.net/extract>`_ function to convert to variables
-that can be used in your view files. Again, read the
-:doc:`Views <../general/views>` page to learn how this might be useful.
+		Driver files must be stored in a subdirectory within the main
+		"libraries" directory, or within your personal *application/libraries*
+		directory. The subdirectory must match the parent class name. Read the
+		:doc:`Drivers <../general/drivers>` description for details.
 
-The third **optional** parameter lets you change the behavior of the
-method so that it returns data as a string rather than sending it to
-your browser. This can be useful if you want to process the data in some
-way. If you set the parameter to true (boolean) it will return data. The
-default behavior is false, which sends it to your browser. Remember to
-assign it to a variable if you want the data returned::
+		Additionally, multiple driver libraries can be loaded at the same time by
+		passing an array of drivers to the load method.
+		::
 
-	$string = $this->load->view('myfile', '', true);
+			$this->load->driver(array('session', 'cache'));
 
-$this->load->model('model_name');
-==================================
+		Setting options
+		---------------
 
-::
+		The second (optional) parameter allows you to optionally pass
+		configuration settings. You will typically pass these as an array::
 
-	$this->load->model('model_name');
+			$config = array(
+				'sess_driver' => 'cookie',
+				'sess_encrypt_cookie'  => true,
+				'encryption_key' => 'mysecretkey'
+			);
 
+			$this->load->driver('session', $config);
 
-If your model is located in a subdirectory, include the relative path
-from your models directory. For example, if you have a model located at
-application/models/blog/queries.php you'll load it using::
+		Config options can usually also be set via a config file. Each library
+		is explained in detail in its own page, so please read the information
+		regarding each one you would like to use.
 
-	$this->load->model('blog/queries');
+		Assigning a Driver to a different object name
+		---------------------------------------------
 
-If you would like your model assigned to a different object name you can
-specify it via the second parameter of the loading method::
+		If the third (optional) parameter is blank, the library will be assigned
+		to an object with the same name as the parent class. For example, if
+		the library is named Session, it will be assigned to a variable named
+		``$this->session``.
 
-	$this->load->model('model_name', 'fubar');
-	$this->fubar->method();
+		If you prefer to set your own class names you can pass its value to the
+		third parameter::
 
-$this->load->database('options', TRUE/FALSE)
-============================================
+			$this->load->library('session', '', 'my_session');
 
-This method lets you load the database class. The two parameters are
-**optional**. Please see the :doc:`database <../database/index>`
-section for more info.
+			// Session class is now accessed using:
+			$this->my_session
 
-$this->load->vars($array)
-=========================
+	.. method:: view($view[, $vars = array()[, return = FALSE]])
 
-This method takes an associative array as input and generates
-variables using the PHP `extract <http://www.php.net/extract>`_
-method. This method produces the same result as using the second
-parameter of the ``$this->load->view()`` method above. The reason you
-might want to use this method independently is if you would like to
-set some global variables in the constructor of your controller and have
-them become available in any view file loaded from any method. You can
-have multiple calls to this method. The data get cached and merged
-into one array for conversion to variables.
+		:param string $view: View name
+		:param array $vars: An associative array of variables
+		:param bool $return: Whether to return the loaded view
+		:returns: mixed
 
-$this->load->get_var($key)
-==========================
+		This method is used to load your View files. If you haven't read the
+		:doc:`Views <../general/views>` section of the user guide it is
+		recommended that you do since it shows you how this method is
+		typically used.
 
-This method checks the associative array of variables available to
-your views. This is useful if for any reason a var is set in a library
-or another controller method using ``$this->load->vars()``.
+		The first parameter is required. It is the name of the view file you
+		would like to load.
 
-$this->load->get_vars()
-=======================
+		.. note:: The .php file extension does not need to be specified unless
+			you use something other than .php.
 
-This method retrieves all variables available to your views.
+		The second **optional** parameter can take an associative array or an
+		object as input, which it runs through the PHP
+		`extract() <http://www.php.net/extract>`_ function to convert to variables
+		that can be used in your view files. Again, read the
+		:doc:`Views <../general/views>` page to learn how this might be useful.
 
-$this->load->helper('file_name')
-================================
+		The third **optional** parameter lets you change the behavior of the
+		method so that it returns data as a string rather than sending it to
+		your browser. This can be useful if you want to process the data in some
+		way. If you set the parameter to TRUE (boolean) it will return data. The
+		default behavior is FALSE, which sends it to your browser. Remember to
+		assign it to a variable if you want the data returned::
 
-This method loads helper files, where file_name is the name of the
-file, without the _helper.php extension.
+			$string = $this->load->view('myfile', '', TRUE);
 
-$this->load->file('filepath/filename', TRUE/FALSE)
-==================================================
+	.. method:: vars($vars[, $val = ''])
 
-This is a generic file loading method. Supply the filepath and name in
-the first parameter and it will open and read the file. By default the
-data is sent to your browser, just like a View file, but if you set the
-second parameter to true (boolean) it will instead return the data as a
-string.
+		:param mixed $vars: An array of variables or a single variable name
+		:param mixed $val: Optional variable value
+		:returns: void
 
-$this->load->language('file_name')
-==================================
+		This method takes an associative array as input and generates
+		variables using the PHP `extract() <http://www.php.net/extract>`_
+		function. This method produces the same result as using the second
+		parameter of the ``$this->load->view()`` method above. The reason you
+		might want to use this method independently is if you would like to
+		set some global variables in the constructor of your controller and have
+		them become available in any view file loaded from any method. You can
+		have multiple calls to this method. The data get cached and merged
+		into one array for conversion to variables.
 
-This method is an alias of the :doc:`language loading
-method <language>`: ``$this->lang->load()``
+	.. method:: get_var($key)
 
-$this->load->config('file_name')
-================================
+		:param string $key: Variable name key
+		:returns: mixed
 
-This method is an alias of the :doc:`config file loading
-method <config>`: ``$this->config->load()``
+		This method checks the associative array of variables available to
+		your views. This is useful if for any reason a var is set in a library
+		or another controller method using ``$this->load->vars()``.
 
-Application "Packages"
-======================
+	.. method:: get_vars()
 
-An application package allows for the easy distribution of complete sets
-of resources in a single directory, complete with its own libraries,
-models, helpers, config, and language files. It is recommended that
-these packages be placed in the application/third_party directory. Below
-is a sample map of an package directory
+		:returns: array
 
-Sample Package "Foo Bar" Directory Map
-======================================
+		This method retrieves all variables available to your views.
 
-The following is an example of a directory for an application package
-named "Foo Bar".
+	.. method:: model($model[, $name = ''[, $db_conn = FALSE]])
 
-::
+		:param mixed $model: Model name or an array containing multiple models
+		:param string $name: Optional object name to assign the model to
+		:param string $db_conn: Optional database configuration group to load
+		:returns: void
 
-	/application/third_party/foo_bar
+		::
 
-	config/
-	helpers/
-	language/
-	libraries/
-	models/
+			$this->load->model('model_name');
 
-Whatever the purpose of the "Foo Bar" application package, it has its
-own config files, helpers, language files, libraries, and models. To use
-these resources in your controllers, you first need to tell the Loader
-that you are going to be loading resources from a package, by adding the
-package path.
 
-$this->load->add_package_path()
----------------------------------
+		If your model is located in a subdirectory, include the relative path
+		from your models directory. For example, if you have a model located at
+		*application/models/blog/queries.php* you'll load it using::
 
-Adding a package path instructs the Loader class to prepend a given path
-for subsequent requests for resources. As an example, the "Foo Bar"
-application package above has a library named Foo_bar.php. In our
-controller, we'd do the following::
+			$this->load->model('blog/queries');
 
-	$this->load->add_package_path(APPPATH.'third_party/foo_bar/');
-	$this->load->library('foo_bar');
+		If you would like your model assigned to a different object name you can
+		specify it via the second parameter of the loading method::
 
-$this->load->remove_package_path()
-------------------------------------
+			$this->load->model('model_name', 'fubar');
+			$this->fubar->method();
 
-When your controller is finished using resources from an application
-package, and particularly if you have other application packages you
-want to work with, you may wish to remove the package path so the Loader
-no longer looks in that directory for resources. To remove the last path
-added, simply call the method with no parameters.
+	.. method:: database([$params = ''[, $return = FALSE[, $query_builder = NULL]]])
 
-$this->load->remove_package_path()
-------------------------------------
+		:param mixed $params: Database group name or configuration options
+		:param bool $return: Whether to return the loaded database object
+		:param bool $query_builder: Whether to load the Query Builder
+		:returns: mixed
 
-Or to remove a specific package path, specify the same path previously
-given to add_package_path() for a package.::
+		This method lets you load the database class. The two parameters are
+		**optional**. Please see the :doc:`database <../database/index>`
+		section for more info.
 
-	$this->load->remove_package_path(APPPATH.'third_party/foo_bar/');
+	.. method:: dbforge([$db = NULL[, $return = FALSE]])
 
-Package view files
-------------------
+		:param object $db: Database object
+		:param bool $return: Whether to return the Database Forge instance
+		:returns: mixed
 
-By Default, package view files paths are set when add_package_path()
-is called. View paths are looped through, and once a match is
-encountered that view is loaded.
+		Loads the :doc:`Database Forge <../database/forge>` class, please refer
+		to that manual for more info.
 
-In this instance, it is possible for view naming collisions within
-packages to occur, and possibly the incorrect package being loaded. To
-ensure against this, set an optional second parameter of FALSE when
-calling add_package_path().
+	.. method:: dbutil([$db = NULL[, $return = FALSE]])
 
-::
+		:param object $db: Database object
+		:param bool $return: Whether to return the Database Utilities instance
+		:returns: mixed
 
-	$this->load->add_package_path(APPPATH.'my_app', FALSE);
-	$this->load->view('my_app_index'); // Loads
-	$this->load->view('welcome_message'); // Will not load the default welcome_message b/c the second param to add_package_path is FALSE
+		Loads the :doc:`Database Utilities <../database/utilities>` class, please
+		refer to that manual for more info.
 
-	// Reset things
-	$this->load->remove_package_path(APPPATH.'my_app');
+	.. method:: helper($helpers)
 
-	// Again without the second parameter:
-	$this->load->add_package_path(APPPATH.'my_app');
-	$this->load->view('my_app_index'); // Loads
-	$this->load->view('welcome_message'); // Loads
\ No newline at end of file
+		:param mixed $helpers: Helper name as a string or an array containing multiple helpers
+		:returns: void
+
+		This method loads helper files, where file_name is the name of the
+		file, without the _helper.php extension.
+
+	.. method:: file($path[, $return = FALSE])
+
+		:param string $path: File path
+		:param bool $return: Whether to return the loaded file
+		:returns: mixed
+
+		This is a generic file loading method. Supply the filepath and name in
+		the first parameter and it will open and read the file. By default the
+		data is sent to your browser, just like a View file, but if you set the
+		second parameter to boolean TRUE it will instead return the data as a
+		string.
+
+	.. method:: language($files[, $lang = ''])
+
+		:param mixed $files: Language file name or an array of multiple language files
+		:param string $lang: Language name
+		:returns: void
+
+		This method is an alias of the :doc:`language loading
+		method <language>`: ``$this->lang->load()``.
+
+	.. method:: config($file[, $use_sections = FALSE[, $fail_gracefully = FALSE]])
+
+		:param string $file: Configuration file name
+		:param bool $use_sections: Whether configuration values should be loaded into their own section
+		:param bool $fail_gracefully: Whether to just return FALSE in case of failure
+		:returns: bool
+
+		This method is an alias of the :doc:`config file loading
+		method <config>`: ``$this->config->load()``
+
+	.. method:: add_package_path($path[, $view_cascade = TRUE])
+
+		:param string $path: Path to add
+		:param bool $view_cascade: Whether to use cascading views
+		:returns: void
+
+		Adding a package path instructs the Loader class to prepend a given path
+		for subsequent requests for resources. As an example, the "Foo Bar"
+		application package above has a library named Foo_bar.php. In our
+		controller, we'd do the following::
+
+			$this->load->add_package_path(APPPATH.'third_party/foo_bar/');
+			$this->load->library('foo_bar');
+
+	.. method:: remove_package_path([$path = ''])
+
+		:param string $path: Path to remove
+		:returns: void
+
+		When your controller is finished using resources from an application
+		package, and particularly if you have other application packages you
+		want to work with, you may wish to remove the package path so the Loader
+		no longer looks in that directory for resources. To remove the last path
+		added, simply call the method with no parameters.
+
+		Or to remove a specific package path, specify the same path previously
+		given to ``add_package_path()`` for a package.::
+
+			$this->load->remove_package_path(APPPATH.'third_party/foo_bar/');
+
+	.. method:: get_package_paths([$include_base = TRUE])
+
+		:param bool $include_base: Whether to include BASEPATH
+		:returns: array
+
+		Returns all currently available package paths.
\ No newline at end of file