summaryrefslogtreecommitdiff
path: root/Master/tlpkg/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-03-21 01:02:39 +0000
committerKarl Berry <karl@freefriends.org>2009-03-21 01:02:39 +0000
commit3fa78a698bf6b09190b0d47e36bc9dd496e8da07 (patch)
treead2edaf0742700968a666c31feea664b4c626524 /Master/tlpkg/doc
parent00f237a3453838bbf26f9e9588a8689216c10a6b (diff)
perl symbol exporting guidelines
git-svn-id: svn://tug.org/texlive/trunk@12477 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/doc')
-rw-r--r--Master/tlpkg/doc/coding-style.txt33
1 files changed, 33 insertions, 0 deletions
diff --git a/Master/tlpkg/doc/coding-style.txt b/Master/tlpkg/doc/coding-style.txt
index a6aac4a7211..0cf1a022b87 100644
--- a/Master/tlpkg/doc/coding-style.txt
+++ b/Master/tlpkg/doc/coding-style.txt
@@ -78,3 +78,36 @@ standards' recommendation of putting braces on lines by themselves, thus
eating up precious vertical space. Do not do that.
+* Exporting symbols and keeping namespaces clean.
+
+In general, the only things which should be in @EXPORT are those
+which are needed nearly universally, such as debug and log. Barewords
+like somefunc are preferable to prefixed &somefunc.
+
+In contrast, EXPORT_OK should list all the "public" symbols (but not
+private ones) of a module. It is good to list them in the same order as
+they are defined in the file, since that both makes it obvious where a
+new symbol should be added, and provides a sort of check that all and
+onyl the right symbols are there. The EXPORT symbols need not and
+should not be listed again in EXPORT_OK.
+
+Then, use TeXLive::SomeModule;
+will import all the EXPORT (but not EXPORT_OK) symbols.
+
+If you need to import a few EXPORT_OK's in addition to the EXPORT's
+use TeXLive::SomeModule (:DEFAULT oksym1 oksym2);
+instead of redundantly listing the @EXPORT symbols.
+
+If you only use a symbol once or twice, don't import it at all. Just
+use TeXLive::SomeModule::somesym. This has the advantage that someone
+reading the source will know immediately where it comes from, and that
+it's not local. This is especially useful with $variables, which our
+brains tend to think of as "local".
+
+If you want to import every single EXPORT_OK symbol,
+use TeXLive::SomeModule (/./);
+should do it (I've never actually tried it). This is certainly far
+better than explicitly listing every symbol yet again.
+
+Documentation:
+http://search.cpan.org/~ferreira/Exporter-5.63/lib/Exporter.pm