Mathematica Stack Exchange is a question and answer site for users of Wolfram Mathematica. It only takes a minute to sign up.
Sign up to join this community
What's the difference between these two ways of specifying dependent packages?
Method 1:
BeginPackage["foo`bar`", {"xxx`", "yyy`"}]
Method 2:
BeginPackage["foo`bar`"]
Needs["xxx`"]
Needs["yyy`"]
Do they always have the same effect? Note that these packages may be used in a big collection of packages which have complex interdependency.
While @rcollyer has answered the "what", I feel that this question still deserves an additional answer because no less important is IMO the why.
The first form (contexts in BeginPackage) is called the public import. What this means is that, in addition to making the public symbols of those contexts available for the implementation of your package, you also make them available for the code that loads your package, be it some top-level code or another package. The two typical use cases when you may want to do this are:
The difference between these two scenarios is sometimes blurred.
The second form is called private import, and is recommended for most cases when you import some functions from other packages into yours. Most of the time, you want it this way, since you only use those functions in implementation of your package's functions, and otherwise the end user could not care less what they are.
Technically, the encapsulation is realized by the way how BeginPackage and EndPackage functions manipulate the $ContextPath. What happens is that BeginPackage calls Needs on all contexts indicated in its second argument (which is why the ordering is different, as @rcollyer indicated), so that the corresponding packages are loaded (if necessary) and the contexts added to the $ContextPath in such a way that they will not be removed by EndPackage. OTOH, all the modifications of $ContextPath in the body of the package between BeginPackage and EndPackage are undone by EndPackage, which makes the packages imported by calls to Needs in the package body to be privately imported.
There is one additional subtlety related to the use of BeginPackage, which is not widely known and can be puzzling at first. Consider some package A` , which imports packages B` and C` publicly (in other words, it starts with BeginPackage["A`",{"B`","C`"}]). Imagine that A` has been loaded, but is not on the $ContextPath at the moment (for example, it was privately imported by another package). Then, if you call Needs["A`"], not only will A` be added to the $ContextPath, but also B` and C` .
This is a rather natural behavior when we think about it, but back in the day it took me a while to figure out why calling Needs on a single context brings many contexts to the $ContextPath. What this means is that the public dependencies declared through BeginPackage are cached. This does not happen for private package imports.
A much better and more complete description of these mechanisms can be found in the book of Roman Maeder "Programming in Mathematica", which IMO remains to this day the best reference for package mechanics in Mathematica.
Begin[{$ContextPath}, ...] (or similar) and Needs is either called before it (public import), or within the body (private import). So, that when $ContextPath reverts to its original value, any package loaded privately is removed from the $ContextPath, also.
$\endgroup$
BeginPackage and EndPackage by the top-level code, that's what I think is really important - we are given a great deal of control over encapsulation, which is what I think is a right design.
$\endgroup$
Nov 1, 2012 at 5:26
A little experimentation reveals the differences. Including the packages within BeginPackage:
In[2]:= $ContextPath
BeginPackage["Temp1`", {"Quantum`RealHarmonics`"}];
$ContextPath
a = 5;
EndPackage[]
$ContextPath
(*
Out[2]= {"Cell$$10824`", "System`"}
Out[4]= {"Temp1`", "Quantum`RealHarmonics`", "System`"}
Out[7]= {"Temp1`", "Quantum`RealHarmonics`", "Cell$$10824`", "System`"}
*)
Using Needs after BeginPackage:
In[2]:= $ContextPath
BeginPackage["Temp1`"];
Needs["Quantum`RealHarmonics`"]
$ContextPath
a = 5;
EndPackage[]
$ContextPath
(*
Out[2]= {"Cell$$10826`", "System`"}
Out[5]= {"Quantum`RealHarmonics`", "Temp1`", "System`"}
Out[8]= {"Temp1`", "Cell$$10826`", "System`"}
*)
So, the ordering of the contexts is effected which effects how different symbols are resolved. Additionally, Quantum`RealHarmonics` does not make it into the global $ContextPath once EndPackage is run. The second form will then not pollute the global context, unlike the first.
Note, that while they do not "pollute" the global context, i.e. you cannot refer to them by their unqualified name, they are still loaded and can be referenced by their fully qualified name. For example, Quantum`RealHarmonics`RealHarmonicsMatrix` would work in the second case, but RealHarmonicsMatrix would not after EndPackage[] has executed.
Quantum`RealHarmonics` is a real package in my collection. I picked it at random which, incidentally, loads a package Utilities`Matrix` via the second method (but in the private section) to avoid polluting the global context.
$\endgroup$