Public, Private - Upper Case, Lower Case:

Question

New to GoLang, coming from Delphi, C++ :

First time I tried to create my own package in Go, I followed all the instructions about how to lay out the workspace, etc, but I kept on getting a compiler error:

./myPackage.go:52: undefined: myFunc

After poking around a bit I discovered that the public access modifier in Go is achieved simply by declaring a function in upper case. Great.

But when I started experimenting with the container classes - List for starters, I discovered I had to declare a List reference return value like this:

func GetFactors(value *int64) *list.List {...

*list is in lower case.

Same when I declared a local reference to a list - I had to use:

l := list.New()

Again, lower case for list.

So, I'm confused. What is the rule? The list calls and references are obviously public, or I wouldn't be able to call/use them - so why are they in lower case?

Solution 1

In this case, list is the name of the package, which you are importing via import "container/list", and its public members are upper case, like List.

The rule is that public functions, types, etc., should be upper case.

You can alias imported packages however you want, but by default it is just the name of the last part of the package path--in this case, list.

Update: It's not the last part of the package path. It's the actual package name (which is often the same thing).

Solution 2

Note: starting Go 1.5 (Q2/Q3 2015), you will get "protected" import as well (named "internal")!

See Go 1.4 doc:

Go's package system makes it easy to structure programs into components with clean boundaries, but there are only two forms of access: local (unexported) and global (exported).
Sometimes one wishes to have components that are not exported, for instance to avoid acquiring clients of interfaces to code that is part of a public repository but not intended for use outside the program to which it belongs.

The Go language does not have the power to enforce this distinction, but as of Go 1.4 the go command introduces a mechanism to define "internal" packages that may not be imported by packages outside the source subtree in which they reside.

To create such a package, place it in a directory named internal or in a subdirectory of a directory named internal.
When the go command sees an import of a package with internal in its path, it verifies that the package doing the import is within the tree rooted at the parent of the internal directory.
For example, a package .../a/b/c/internal/d/e/f can be imported only by code in the directory tree rooted at .../a/b/c.
It cannot be imported by code in .../a/b/g or in any other repository.

For Go 1.4, the internal package mechanism is enforced for the main Go repository;
from 1.5 and onward it will be enforced for any repository.

Solution 3

Note: the Go Spec for package name don't mention that a package name is always in lowercase.
It only state that its name is represented by an identifier, which is composed of a collection of "letter".

This thread does clarify:

Package names can be anything, you can start them with an uppercase letter if you want to.
But the convention is all lowercase, which I guess saves you the hassle of typing an uppercase letter.

The uppercase/lowercase exportability isn't really relevant to packages since you can't have a private package.

Once you know that, it is easier to recognize:

• list.New() for a constructor (always at the package level, to build an initialized instance of a type), like os.NewFile(),
• list.List for a struct type of the package list (the other struct type of that same package being list.Element).

Comments

[VonC]

Note that starting Go 1.5, you will get semi-public methods as well (in "internal" package): exported within the current project, not for external projects. See my answer below

[Vector]

Got it - thanks. What got me confused most was list.New() - which looks like a call on the list type, in C++ for example - if so it would have to be public. So you're saying that it's really a reference to the package and New() is a self standing function in that package that automatically returns a *List reference because that's what New() does in the list package. Makes sense. Also clears up something that was confusing me in the docs.

[Eve Freeman]

Yep. The docs are actually great for exploring--function names click through to the source, which is actually sometimes more useful to read than the docs. :) golang.org/src/pkg/container/list/list.go?s=1662:1678#L52

[Vector]

Still finding my way around the docs - but starting to find them very useful - your answer will help me a lot. Go is a deceiving - it looks like C/C++ but it's actually VERY different.

[Shimmy Weitzhandler]

I'm unfamiliar with the protection levels in Java, but in C# there is protected to expose member to inheritances only, and internal to expose member to local package. I think a member should be hidden at all, not validated before access.