Main Content

Packages Create Namespaces

Package Folders

Packages are special folders that can contain class folders, function, and class definition files, and other packages. The names of classes and functions are scoped to the package folder. A package is a namespace within which names must be unique. Function and class names must be unique only within the package. Using a package provides a means to organize classes and functions. Packages also enable you to reuse the names of classes and functions in different packages.

Note

Packages are not supported for classes created before MATLAB® Version 7.6 (that is, 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 parent of the top-level package 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  

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 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.

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 Import Classes.) For example, call this package function:

+mypack/pkfcn.m

With this syntax:

z = mypack.pkfcn(x,y);

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)

Define a package class with only the class name:

classdef myClass

but call it with the package prefix:

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

Calling class methods does not require the package name because you have an object of the class. You can use dot or function notation:

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

A static method requires the full class name, which includes the package name:

mypack.myClass.stMethod(arg)

Referencing Package Members from Outside the Package

Functions, classes, and other packages contained in a package are scoped to that package. To reference any of the package members, 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 that 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 that is in the package mysubpack:

mypack.mysubpack.myFcn(arg1,arg2);

If mypack.MyFirstClass has a method called myFcn, call it like any method call on an object:

obj = mypack.MyFirstClass;
myFcn(obj,arg);

If mypack.MyFirstClass has a property called MyProp, assign it using dot notation and the object:

obj = mypack.MyFirstClass;
obj.MyProp = x;

Packages and the MATLAB Path

You cannot add package folders to the MATLAB path, but you must add the package parent folder to the MATLAB path. Package members are not accessible if the package parent folder is not on the MATLAB path, even if the package folder is the current folder. Making the package folder the current folder is not sufficient to add the package parent folder to the path.

Package members remain scoped to the package. Always refer to the package members using the package name. Alternatively, import the package into the function in which you call the package member, see Import Classes.

Package folders do not shadow other package folders that are positioned later on the path, unlike classes, which do shadow other classes. If two or more packages have the same name, MATLAB treats them all as one package. If redundantly named packages in different path folders define the same function name, then MATLAB finds only one of these functions.

Resolving Redundant Names

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

fldr_1/+foo
fldr_2/@foo/foo.m

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

>> which foo
fldr_2/@foo/foo.m

A function and a package can have the same name. However, a package name by itself is not an identifier. Therefore, 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 package function takes precedence over a static method. For example, path folder fldrA contains a package function and path folder fldrB contains a class static method:

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

A call to which foo.bar returns the path to the package function:

which foo.bar
fldrA\+foo\bar.m  % package function

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

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

A call to which foo.bar returns the path to the package function:

which foo.bar
fldr/+foo/bar.m

If a path folder fldr contains a classdef file foo that defines a static method bar and the same folder contains a package +foo that contains a package function bar.

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

A call to which foo.bar returns the path to the package function:

which foo.bar
fldr/+foo/bar.m 

Related Topics