Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Packages Create Namespaces

Internal Packages

MathWorks® reserves the use of packages named internal for utility functions used by internal MATLAB® code. Functions that belong to an internal package are intended for MathWorks use only. Using functions or classes that belong to an internal package is strongly discouraged. These functions and classes are not guaranteed to work in a consistent manner from one release to the next. Any of these functions and classes might be removed from the MATLAB software in any subsequent release without notice and without documentation in the product release notes.

Package Folders

Packages are special folders that can contain class folders, function and class definition files, and other packages. Packages define the scope of the contents of the package folder (that is, a namespace within which names must be unique). This means function and class names need to be unique only within the package. Using a package provides a means to organize classes and functions and to select names for these components that other packages can reuse.

    Note:   Packages are not supported for classes created prior to MATLAB Version 7.6 (i.e., classes that do not use classdef).

Package folders always begin with the + character. For example,

+mypack
+mypack/pkfcn.m % a package function
+mypack/@myClass % class folder in a package

The top-level package folder's parent folder must be on the MATLAB path.

Listing the Contents of a Package

List the contents of a package using the help command:

help event
Contents of event:

EventData                      - event.EVENTDATA    Base class for event data 
PropertyEvent                  - event.PROPERTYEVENT    Event data for object property events
listener                       - event.LISTENER    Listener object
proplistener                   - event.PROPLISTENER    Listener object for property events

You can also use the what command:

what event
Classes in directory Y:xxx\matlab\toolbox\matlab\lang\+event

EventData      PropertyEvent  listener       proplistener  

Referencing Package Members Within Packages

All references to packages, functions, and classes in the package must use the package name prefix, unless you import the package. (See Importing Classes.) For example, call a package function with this syntax:

z = mypack.pkfcn(x,y);

Note that definitions do not use the package prefix. For example, the function definition line of the pkfcn.m function would include only the function name:

function z = pkfcn(x,y)

Similarly, a package class would be defined with only the class name:

classdef myClass

but would be called with the package prefix:

obj = mypack.myClass(arg1,arg2,...);

Calling class methods does not require the package name because you have an instance of the class:

obj.myMethod(arg) or 
myMethod(obj,arg)

A static method requires the full class name:

mypack.myClass.stMethod(arg)

Referencing Package Members from Outside the Package

Because functions, classes, and other packages contained in a package are scoped to that package, to reference any of the package members, you must prefix the package name to the member name, separated by a dot. For example, the following statement creates an instance of myClass, which is contained in mypack package.

obj = mypack.myClass;

Accessing Class Members — Various Scenarios

This section shows you how to access various package members from outside a package. Suppose you have a package mypack with the following contents:

+mypack
+mypack/myfcn.m
+mypack/@myfirstclass
+mypack/@myfirstclass/myfcn.m
+mypack/@myfirstclass/otherfcn.m
+mypack/@myfirstclass/myfirstclass.m
+mypack/@mysecondclass
+mypack/@mysecondclass/mysecondclass.m
+mypack/+mysubpack
+mypack/+mysubpack/myfcn.m

Invoke the myfcn function in mypack:

mypack.myfcn(arg)

Create an instance of each class in mypack:

obj1 = mypack.myfirstclass;
obj2 = mypack.mysecondclass(arg);

Invoke the myfcn function in mysubpack:

mypack.mysubpack.myfcn(arg1,arg2);

If mypack.myfirstclass has a method called myfcn, it is called as any method call on an object:

obj = mypack.myfirstclass;
myfcn(obj,arg);

If mypack.myfirstclass has a property called MyProp, it can be assigned using dot notation and the object:

obj = mypack.myfirstclass;
obj.MyProp = some_value;

Packages and the MATLAB Path

You cannot add package folders to the MATLAB path, but you must add the package's parent folder to the path. Even if a package folder is the current folder, its parent folder must still be on the MATLAB path or the package members are not accessible.

Package members remain scoped to the package even if the package folder is the current folder. You must, therefore, always refer to the package members using the package name.

Package folders do not shadow other package folders that are positioned later on the path, unlike classes, which do shadow other classes.

Resolving Redundant Names

Suppose a package and a class have the same name. For example:

fldr1/+foo
fldr2/@foo/foo.m

A call to which foo returns the path to the executable class constructor:

>> which foo
fldr2/@foo/foo.m

A function and a package can have the same name. However, a package name by itself is not an identifier so if a redundant name occurs alone, it identifies the function. Executing a package name alone returns an error.

Package Functions vs. Static Methods

In cases where a package and a class have the same name, a static method takes precedence over a package function. For example:

fldr1/+foo/bar.m % bar is a function in package foo
fldr2/@foo/bar.m % bar is a static method of class foo

A call to which foo.bar returns the path to the static method:

>> which foo.bar
fldr2/@foo/bar.m

In cases where a path folder contains both package and class folders with the same name, the class static method takes precedence over the package method:

fldr1/@foo/bar.m % bar is a static method of class foo
fldr1/+foo/bar.m % bar is a function in package foo

A call to which foo.bar returns the path to the static method:

>> which foo.bar
fldr1/@foo/bar.m
Was this topic helpful?