Package organization

24

9

When writing a Mathematica package Foo, with functions f1, f2 and f3, one can use the template:

BeginPackage["Foo`"];

f1::usage = "f1[] ....";

f2::usage = "f2[] ....";

Begin["`Private`"];

f1[]:= code for f1

f2[]:= code for f2

f3[]:= code for f3 (not visible as only in the private context)

End[];

EndPackage[];

What I do not like is when your package is growing, there can be a long "distance" (not fitting in your text editor) between "f1::usage" and the actual f1 code. This is error prone concerning coherence between doc and code. So I would like to group common stuff together.

My question is:

Is it possible and is it a good practice (without side effect) to group things like below?

BeginPackage["Foo`"];

Begin["`Private`"];

Foo`f1::usage = "f1[] ....";

Foo`f1[]:= code for f1

...

Foo`f2::usage = "f2[] ....";

Foo`f2[]:= code for f2

...

f3[]:= code for f3 (private as before)

End[]

EndPackage[];

Picaud Vincent

Posted 2016-09-05T10:12:20.253

Reputation: 2 241

Wohoo, It is the first time I use stackexchange.com, thank you Kuba and Szabolcs and others for your instantaneous answer! – Picaud Vincent – 2016-09-05T10:21:43.510

Welcome to Mathematica.SE! I suggest the following: 1) As you receive help, try to give it too, by answering questions in your area of expertise. 2) Take the tour! 3) When you see good questions and answers, vote them up by clicking the gray triangles, because the credibility of the system is based on the reputation gained by users sharing their knowledge. Also, please remember to accept the answer, if any, that solves your problem, by clicking the checkmark sign!

– Michael E2 – 2016-09-05T10:40:28.087

Thank you. I will do it and have to read the "how to" concerning stackexchange.com. – Picaud Vincent – 2016-09-05T10:50:46.293

For what its worth this is implicitly explained in (29325). This is a welcome Q&A however as it is a point worth highlighting.

– Mr.Wizard – 2016-09-05T15:20:04.647

Answers

20

The key point is not to set the usage message between BeginPackage and Begin["`Private`"], but just to mention the symbol.

A better way to do this would be:

BeginPackage["Foo`"];

f1
f2

Begin["`Private`"];

f1::usage = "f1[] ....";
f1[]:= code for f1

f2::usage = "f2[] ....";
f2[]:= code for f2

f3[]:= code for f3 (not visible as only in the private context)

End[];

EndPackage[];

Whatever you mention there will be a public symbol (f1, f2). What you don't mention will not be public (f3). That's because after the BeginPackage, $Context will be Foo`, meaning that new symbols are created there. $Context controls where new symbols are created. After the Begin["`Private`"], $Context is changed, but Foo` is still in $ContextPath. $ContextPath controls where Mathematica should look for symbol names. It only creates a new symbol if it didn't find the name in $ContextPath.

You could use the explicit context for every definition, but personally I don't like this because it keeps repeating the name of the context, thus making it difficult to change in the future. It is also good to point out that you'd only need to use an explicit context when mentioning the symbol for the first time. I.e. this would be sufficient (though potentially confusing):

Foo`f1::usage = "f1[] ....";

f1[]:= code for f1

It is good practice to use different naming conventions for public and non-public symbols. Public ones are preferably capitalized. This will also help in catching errors such as not making a symbol public.

Szabolcs

Posted 2016-09-05T10:12:20.253

Reputation: 213 047

18

It is possible, your code works. I don't see any downsides which aren't a matter of taste.

I like to keep usages next to definitions too. But I hate using full names, you can just mention symbols in a proper place to create them in appropriate context.

BeginPackage["Foo`"];

  f1; f2; 

Begin["`Private`"];

  f1::usage = "f1[] ....";

  f1[]:= code for f1



  f2::usage = "f2[] ....";

  f2[]:= code for f2



  f3[]:= code for f3

End[]

EndPackage[];

?Foo`*

?f1

enter image description here

Kuba

Posted 2016-09-05T10:12:20.253

Reputation: 129 207

3

Reading the answers I just realized that the logic can be pushed a little bit further. If we want to group "everything" together, the following might be a possible solution (with the inconvenience of some repetitions of the Foo` context)

BeginPackage["Foo`"];

Begin["`Private`"];

(*-------*)

Foo`f1;

f1::usage="f1[] ....";

f1[]:=code for f1

(*-------*)

Foo`f2;

f2::usage="f2[] ....";

f2[]:=code for f2

(*-------*)

f3[]:=code for f3

(*-------*)

End[]

EndPackage[];

Picaud Vincent

Posted 2016-09-05T10:12:20.253

Reputation: 2 241

2Or just Foo`f1::usage.... – Kuba – 2016-09-06T05:19:53.260

3The advantage of listing public symbols at the start of the package as in other answers is that it makes it easier to spot whether one forgot to make a symbol public. A matter of taste. – Bruno Le Floch – 2016-09-06T15:16:06.840