Names and Namespaces

If cards are data atoms, then namespaces are collections or containers of those data atoms.  We will wait to explore how multiple namespaces might relate and interact at a later point as we look at how they can be used in systems architecture and to implement networks of interlinked data.  To facilitate linking to other systems, the logic of card names is available as a gem. For now we will confine ourselves to a single collection and internal relationships.

A simple name/card has only one part, lets start there.  That means the name doesn't have any joint characters in it.  One part means the name only links to the one card it names.  We will use plus (+) for the joint character throughout, although some designers may prefer to use slash (/) because of the good analogy to file system an web paths.  Because the name is how a single item is identified in a collection, one of the most important issues is what makes one name equal to another.  That could be simply comparing the name strings, but that's not particularly friendly for users.  Programmers sometimes want to require identifiers to match exactly and put restrictions on what strings are valid names, but in this system we want it to be easy to refer to the same thing in different ways.  To make this work, any name string can be translated to a canonical version of the name called a key, and if two names have the same key, they will refer to the same card.

In simple terms it breaks the name up into words, singularizes simple plurals, makes the words all lower case and joins them with underscore (_).  Most punctuation and symbols are considered just like a space or underscore and are stripped off the ends and reduced to only one underscore between words.  There are only a few exceptions to this the joint character (+) and slash (/) aren't allowed in simple names, and the name gem can be configured to add additional banned characters or use an alternate joint.  The other exception is asterisk (*) which is treated like an ordinary letter and included in the words of a key.  Later we will see how this special character is used to define special sets of system cards used to help implement advanced features.

Now we can address non-simple names, ones with more than one simple part.  You can think of the name as just an array of parts, but there's a bit more that happens when you name a card.  Consider the cardname A+B+C, it has three parts, but let's look at what cards are related.  The card A+B+C is composed of two parts, A+B and C, thetn A+B is A and B, so A+B+C, A+B, A, B and C are each cards that are parts of A+B+C.  If any of them don't exist when A+B+C is created, they will get created then.  Note that B+C is not involved at all, and won't be created with A+B+C.

Finally, there is a concept of relative or contextual names.  When a name has variable or missing parts it doesn't actually refer to a specific card but can be evaluated in a particular context.  We'll dig into this further when discussing linking and inclusion, but the simplest case is when one card has a relative link to a to another.  Consider the card A linking to the relative name +B+C.  The link would go to A+B+C.  The card B+C is still not involved, just the relative name +B+C, which doesn't point to anything without a context card.

Although not mentioned specifically, name handling is a little English centric.  You may have noticed the mention of singular form, mainly an English language transformation, but nothing else is limiting.  It uses generalized character classes so it can keep all the word characters and fold all the special characters away in key processing.  Soon, cards will have a language, maybe the name and content would share a single language unless we can think of a use case to split them.  That means a single deck can include cards in many languages making it truely multilingual.  Adding support for giving names and content a language is almost trivial, and that is all that will be added to the card core code.  It demonstrates the power of the architecture that the details of how different languages are presented and organized are implemented like much of the system, as modular components that extend the core architecture.  It makes them easy to modify and extend from an evolving reference implementation.  The initual support for multilingual sites might be a bit primative, but it won't take updates to the core representation of cards beyond the basic data to represent the language for the main card attributes.  The projects with active communities in many languages will be able to push the UX in downstream module changes.