Old - A rose by any other name..

Submitted by Trispis on Sun, 2007-03-11 12:00

NAMING CONVENTIONS

One of the key components of 'standardizing' relates to attribute naming conventions. For example: If you wanted to find all attributes on a given object which contain $commands, you would either:

  • Use grep() to find all attributes whose contents begin with the $ character.
  • or...

  • Name all of your attributes in such a way that their contents are identifiable by that name, and use lattr() to find all attributes identifiable as containing $commands via some component of their attribute name.

If this example is extended to include other attribute types (HELP, UFUN, etc.), it becomes obvious that the latter method (standardized naming) is the preferable approach. And, as you will see in further reading of this document, it becomes THE key component in management of globals. In fact, standardized attribute naming is the crux of the entire WARPEDcore project. By utilizing a functional and intuitive standardized naming convention, it becomes possible to easily manage and coordinate a large number of objects, including those not written expressly under these documented conventions.

The WARPEDcore will use the following naming conventions. And, although these are recommended for all softcoders (simply to provide easy readability in the event someone else might have to sort through your code someday), it is understood that pre-existing style and/or habit may be difficult to circumvent. Therefore, in addition to these recommended conventions, the WARPEDcore also provides a means of documenting pre-existing code and pre-existing attribute naming conventions.

  1. Recommended Procedures -
    1. Name Components: Except in special circumstances which dictate otherwise, attribute names should consist of a set of component item segments joined by a non-alphanumeric delimiting character. In this section, you will find the WARPEDcore recommended procedures.
      NOTE: As stated earlier in this document, the PREFIXes listed below also serve as Official WARPEDcore attribute type identifiers. See also: the 'Adaptation' section below, for details on documenting pre-existing code.
      1. PREFIX: This is the first component of an attribute name and it will identify the attribute's "type" classification ($command, ^listen, user-defined function, @trigger, data, etc.). This component shall be one of the following types. In the list below (repeated here for convenience when using the multi-part document), you will find both the full name (for those who like to spell things out), as well as a corresponding four-digit prefix (for those who like things to line up neatly), for each type. See the section on documentation, further along in this book, for more information on how to document the use of these.
        Type        4dig        For...
        COMMAND     CMND        attributes containing $commands
        LISTEN      LSTN        attributes containing ^listen patterns
        UFUN        UFUN        attributes called via u(), filter(), etc
        TRIGGER     TRIG        non-$command and non-^listen attribs 
                                which should be triggered with @trigger.
        DATA        DATA        attribs which contain data elements or 
                                data structures
        LIST        LIST        attribs which contain delimited lists
        LOCK        LOCK        attributes used in indirect locks
        ZONE        ZONE        zone-specific or zone-related attributes
        HELP        HELP        attributes containing help files
        NOTE        NOTE        attributes containing notes, comments, etc.
        TEMP        TEMP        temporary storage (users should be able to 
                                expect to freely delete these without 
                                disrupting functionality)
        

        NOTE: It is conceivable that an attribute might belong to more than one of the above types. In such situations, it is recommended that the broader category (per the object's purpose) be considered the PREFIX for that attribute (e.g., LOCK`ZONE -- as an object may have numerous locks, but only one zone). Nevertheless, it remains a subjective decision. Think about it in terms of where you want attributes grouped when listed in a default, lexicographical sort.

      2. PRIMARY: This is the second component of an attribute name. If related to a $command or ^listen pattern -- either directly, or indirectly via a support attribute -- it should reflect the originating syntax (CMND`WHO, UFUN`WHO). In situations where no 'input origination' is applicable -- such as automated or timed processes, or general utility functions -- it should reflect the general purpose of the process (UFUN`ALPHASORT).
      3. SECONDARY: This optional component can be used to identify the purpose of individual subprocesses (e.g. UFUN`FINGER``ERROR, TRIG`UPDATE`LOOP, etc.).
      4. TERTIARY: Again, optional. And again, for identifying subprocesses (at this point, numerals might seem likely candidates, such as: TRIG`UPDATE`LOOP`3).
      5. SUFFIX: Finally, an optional suffix may be used to indicate other relevant details (DATA`UPDATE`LOOP`3`VARIABLES, CMND`SET-FACTION`REGEXP, etc.)
    2. Name Delimiters:

      All attribute name components should be separated by the back-tick (`) character.
      Syntax Summary:
      <PREFIX>`<PRIMARY>[`<SECONDARY>][`<TERTIARY>][`<SUFFIX>]

    3. Registers, Globs, and Wildcards -
      1. When using the most basic form of globbing registers ($foo *), it is recommended that the X character be used to indicate the asterisk or 'globbed wildcard' (*) (aka the presence of a single %-register) when two commands or processes have the same basic beginning syntax and one of them has a single glob (e.g., $foo, and $foo *), or when the attribute only accepts one such input (e.g., CMND`FINGER_X, UFUN`FOO_X). (This convention is derived from general mathematics and/or algebra in which x has become the 'default first variable'. And because it is the character which most closely resembles the asterisk, which cannot be used in attribute names. Thus, it seems intuitive not only for basic learning, but also for simplifying a standard. See below for more enhanced conventions.)
      2. In situations where multiple globs or registers are present, this above representation can be expanded to use R0, R1, etc. for %0 (%-register 0), %1 (%-register 1), etc. (respectively). (This is derived from the r() function,... for those wondering why it's not P# for 'Percent'.)
      3. Regular expression -based $commands (where %0 == the entire input) can be potentially troublesome for this type of attribute naming process. Nonetheless, regexp command structure can be indicated by having R0 be the last listed register (derived from the fact that R0 isn't technically complete until all other registers have been completed), or by appending a suffix identifier. For example: CMND`FOO_R1_R2_R0 or CMND`FOO_R1_R2.REGEXP
      4. Furthermore, if it is necessary to distinguish between * and ? -based registers, the above conventions can be further expanded to include: X0, X1, X2, etc. for *-based registers and Q0, Q1, Q2, etc. for ?-based registers (Q for Question mark).
      5. Lastly, note that these variable representations are intended primarily to express what the attribute accepts as input. It is far too difficult and complex to attempt to address and document all possible output combinations -- especially considering the fact that a ufun containing a switch() could easily have options for calling more than a dozen different other ufun's and sending different stuff to each. If you wish to reflect both input and output, your attribute name should reflect that you are doing so (.e.g., UFUN`FOO`IN_R0-R1-R2`OUT_BAR-R0X1_BAZ-R1X2 -- NOTE: Attempting to indicate this much information immediatly crosses the border into excessiveness and is not recommended. Yet, as it is conceivable that an extremely large project might actually need this for clarity, it has been included in this document.)
    4. Other
      1. The underscore (_) should be used for indicating the presence of a literal 'space' (e.g. CMND`FINGER_X) in the syntax of the command.
      2. The hyphen (-) and should be used to indicate other special characters (slash, colon, comma, etc.)
      3. The dot(.) should be used when adding a supplimental name segment for which a new tree branch is either not required or not desired (e.g., &CMND`FINGER_X.NOTE).
  2. Mandatory Procedures - (Mandatory Procedures have been removed, due to new (since the time of the original version of this document) features of Pennmush which make a 'registry thing' unnecessary.)
  3. Adaptation Options

    This section acknowledges the enormous burden of rewriting existing code to comply with the above recommended conventions. Additionally, it also acknowledges the difficulty in changing existing behaviors (old habits are hard to break). Therefore, in order to simplifying the conversion of pre-existing code (and, thus, pre-existing attribute names), personal preference, and/or habitual behavior to WARPEDcore managable structures, the following Adaptation Options have been established (NOTE: Even I, the author of this document, do not *always* use the same standards from one project to another. Ever since I started coding, I've experimented with different ways to benefit from structured attribute naming conventions. Thus, my own coded systems aren't even compatible with each other. Yet, it is out of this experimentation and in direct response to that universal disparity, that I present these conventions... and these Adaptation Options. I may or may not eventually rewrite my existing code using the conventions recommended above, but I will certainly use the Adaptation Options listed herein to make them WARPEDcore managable). The hope here is that rewrites can be reduced to a bare minimum, by simply providing a WARPEDcore compliant documentation of existing attribute naming conventions.

    The following documentation conventions are recommended for adapting existing code or existing coding styles (ref: attribute names) to WARPEDcore managable structures. These conventions are divided into two sections. The first section covers the conventions for identifying general attribute types. The second section covers some special 'personal attributes' which are recommended for all objects which are intended to be registered with the WARPEDcore.

    1. Documentation Attributes (Likely to be rewritten)

      Based on the above list of recommended PREFIX components to denote attribute types, the following documentation conventions are recommended for adapting pre-existing code to WARPEDcore managable structures. In summary, you should provide a ~. attribute for each attribute type relevant to your code (i.e., if you don't have any LIST-type attributes, there is no need to document them). And each attribute should indicate your code's conventions for that attribute type, using the following procedures (derived partially from regular expression syntax).

      1. if you document your code using these conventions, your object should contain an attribute named ~ (a single tilde). The presence of this attribute will indicate you also have other WARPEDcore documentation attribs per the remaining items in this section. And, you may add optional comments in this attribute per the following two guidelines...
        • If your attribute naming conventions comply with the recommendations above, this attrubute's contents should contain at least a tilde (~) as its first character. And, if you use the recommended 4-digit type identifiers, it should be immediately followed by a number 4. Examples:
          • &~ object=~ This package is believed to be WARPEDcore compliant and uses full words for attribute types and other attribute name components.
          • &~ object=~4 This package is believed to be WARPEDcore compliant and uses the 4-digit identifiers for attribute types and other attribute name components.
        • If your attribute naming conventions deviate from those recommended above, ensure that the first character of this attribute's contents IS NOT a tilde (e.g., &~ object=This is an adapted version of some old code I did ages ago. Some of it isn't fully compliant to the WARPEDcore style.)
      2. documentation attributes should begin with ~. (tilde dot) and be followed immediately by one of the aforementioned attribute type identifiers (aka, the recommended PREFIX components).
      3. the attributes should contain the character string YOU used for the respective attrib-type.
      4. if your string is used as a PREFIX and/or is not followed immediately by a dot (.), denote this by adding a comma (,) and a caret (^).
      5. if your string is used as a SUFFIX and/or is not immediately preceeded by a dot (.), denote this by adding a comma (,) and a dollar sign ($).
      6. if you use an inner string (something neither a prefix nor a suffix, yet a consistent character string -- e.g. FINGER.COMMAND.2), denote this by itself (i.e., no comma or other symbol following it, but still denote it).
      7. if you do not consistently use any specific character string, do not denote it at all (don't add the attribute at all).

      Some examples:

      • &~.COMMAND =DO_,^ -- This would indicate that attributes on this object which contain $commands (attributes of type "COMMAND") have a PREFIX element (denoted by the ^) of DO_
      • &~.COMMAND =_CMD,$ -- In this case, COMMAND-type attribs have a SUFFIX component (denoted by the $) of _CMD
      • &~.COMMAND =COMMAND -- In this case, CMND-type attribs (always) contain the string COMMAND in their name, but it is not consistently a prefix or suffix (possibly either, or, or neither).
      • Objects which do not have a consistent procedure for COMMAND-type attribute names, should not have a ~.COMMAND attribute.

      Other examples:

      • &~.TRIGGER =.TRIG,$ -- Just to illustrate a few more... This would indicate that attributes on this object which are of the TRIG-type have a SUFFIX component ($) of .TRIG. NOTE: Even though the four-digit identifier is the same as that recommended (TRIG) and the delimiter used is the same as that recommended (.), it is a SUFFIX, rather than a PREFIX (recommended). Therefore, this documentation is recommended.
      • &~.HELP =HELP_,^ -- This would indicate that attributes on this object containing help files have a PREFIX component (^) of HELP_. NOTE: Even though the four-digit identifier is the recommended one (HELP) and it is a PREFIX (recommended), it uses the underscore (_) as its post-prefix delimiter rather than the recommended dot (.). Therefore, this documentation is recommended.
    2. Personal Attributes (Likely to be rewritten)

      The following is a list of special 'personal attributes' which are recommended to be included - at least as many as are applicable - in all softcode packages, regardless of whether or not you use any of the other aforementioned conventions

      NOTE: Use the single tilde attribute to denote the presence of these special attribs. Do not, however, confuse the presence of these 'personal attributes' with 'being WARPEDcore compliant'. That is, if all you have done is add these attributes for personal reference or credit, then the single tilde attribute's contents' first character should NOT be a tilde. The attributes listed below are for package identification only and bear no relevance whatsoever to overall WARPEDcore compliance.

      • ~.AUTHOR -- to contain the name or preferred identity (or plural, if more than one) of the current author(s) or maintainers(s).
      • ~.AUTHOR.EMAIL -- to contain the email address of the package's author or maintainer
      • ~.AUTHOR.URL -- to list the author's URL (aka webpage), if s/he has one.
      • ~.LICENSE -- to identify the name (e.g., GPL, LGPL, Modified NPL, whatever) or general type (Creative, Public Domain, whatever) of the license applicable to the code.
      • ~.LICENSE.URL -- to list the URL where this code's license can be found (e.g., It's not feasible to attach complete copies of the GNU General Public License to a softcode package. Especially considering the enormous numbers of packages on the net which are increasingly using this license. Thus, a URL pointer is appropriate.)
      • ~.URL -- to list the URL where this code can be acquired (http, ftp, etc. should be specified).

      Since much of this is still in early development, some of these procedures may be subject to modification. And the list of 'special attributes' is certainly likely to grow in time.

NOTE: This page is out of date and will soon be updated to include the new (since the time this document was originally released) 'attribute trees' feature of PennMUSH as part of these design concepts. (Thanks, Talek!)

Although I see many option and combinations, these are my notes to illustrate the direction I see going with this...

Wise Man Say: Flowering Shrub uses Attribute Tree features to organize code for examination.

Sample Template:

<grandpackage>`<package>`<attr_type>.<syntax>

In this template,

<grandpackage> would be the equivalent of any one of: The Sandbox Globals Project, all of Myrddin's stuff bundled together, The mythical MUDcore supposedly written by Amberyl, etc., &c. Ideally, this would be an abbreviated version thereof (e.g., SGP for The Sandbox Globals Project). The WARPEDcore Project will use the single tilde (~) for this.

<package> would be the equivalent of a category of commands. In order to see this properly, one must envision the product as it could be at some point just just beyond what one would think of as 'complete'. Let's take, for example, a +finger command. No matter how much stuff you pack into and/or around this, in the end, it's just a single command. However, history shows that there are a number of 'social information' commands related to this (i.e., +who, +where, etc.), each of which could be quite robust in its own right yet each also just a single command. As single commands, they'd not be individual members of this category; but, as a group of 'social information' commands, together they become a <package>, such as 'socials' For example:

&SGP`SOCIALS`CMND.FINGER_X

Although I may not have presented this perfectly in this initial draft of my thoughts, the point here is that when you start writing attribute names, think bigger than the immediate feature -- place the immediate feature (whether it be a command such as +finger, or a unique ufun to sort-by-avg-idle-over-last-2-hours) into the context of a larger picture and include your 'maximum package name' appropriately as part of your attribute naming process. This sets your code up in a way such that it can be 'grafted' (copy/paste-migrated) onto yet a larger package than what you might have planned (<greatgrandpackage>?). For example, assuming licensing permits, SGP could be adapted to this design such that very little modification would be needed to make it 'attachable' to the WARPEDcore as a compatible module, yet still retaining it's separateness in development maintainership. E.g.,

~`SGP`SOCIALS`CMND.FINGER_X

And, please... if you see a better way of doing this, by all means, do it... but PLEASE... POST SOMETHING HERE! Share your insight!