MATLAB®

Scoping Classes with Packages

Package Directory

Packages are special directories that can contain class directories, functions, and other packages. Packages define a scope (sometimes called a namespace) for the contents of the package directory. 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 can be reused in other packages.

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

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

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

The package directory's parent directory must be on the MATLAB path.

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:

mpack.myClass.stMethod(arg)

Back to Top

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;

Back to Top

Packages and MATLAB^® Path

You cannot add package directories to the MATLAB path, but you must add the package's parent directory to the path. Even if a package directory is the current directory, its parent directory 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 directory is the current directory. You must, therefore, always refer to the package members using the package name.

Package directories do not shadow other package directories 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:

dir1/+foo
dir2/@foo/foo.m

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

>> which foo
dir2/@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:

dir1/+foo/bar.m % bar is a function in package foo
dir2/@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
dir2/@foo/bar.m

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

dir1/@foo/bar.m % bar is a static method of class foo
dir1/+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
dir1/@foo/bar.m

Back to Top

Specifying Class Precedence

Saving and Loading Objects