[SVN] Naming convention

Allan Odgaard allan at macromates.com
Sat Apr 23 11:42:54 UTC 2005

On Apr 23, 2005, at 12:33, Mats Persson wrote:

> 1.	Markup languages like <html> or <xml> is described as 
> "keyword.markup". Should "markup" not be its own root just like 
> "variable" has become ??  Bit uncertain about the logic behind it 
> being a keyword.

I think Chris can probably give a better answer, but I'd think it's 
because with a very basic styling (e.g. of only keyword, constant, 
variable, string and comment), the tag-name should probably be styled 
like a keyword.

But labeling the entire tag as a keyword is wrong, I agree with that. 
Probably we should adopt another scheme, similar to 
declaration.(function|class) -- I don't know if it's stretching it a 
bit, but how about something like: declaration.tag and then tag-name, 
tag-attribute, and tag-value.

So we end up with these three similar markups:

    function-named argument



Looking at these lists though, it screams “dot-separated hierarchy” for 
the fragments of the three types of declaration, so instead we get: 
name.class, name.function, name.tag -- that way, styling only “name” 
will be enough to give colors to all 3 elements (which are rarely 
present in the same source, so that's probably good enough for most).

If we do these 3 constructs as having each fragment a dot-separated 
hierarchy, I'd like to add a (new) prefix. As of such, when targeting 
these elements it should not be necessary to put in declaration.* in 
the scope, seeing how this is technically not always feasible to define 
(like in LaTeX, where I used the function-fragments in names w/o a 
parent declaration.function).

> 2.	"Variable" in my world is $variable (in PHP), @variable in Ruby, 
> whereas INT_MAX would be a "constant" in my book. I guess I might be 
> missing something here ;-)

Yes, INT_MAX is also a constant IMHO, I just couldn't think of a 
variable, because in the majority of languages I use, a variable is not 
possible to markup. But I see the picture now :)

> 3.	In the PHP syntax file I use "keyword.construct.php" for ( class, 
> function, interface, etc. ) keywords. I assume that's much the same as 
> what you call "declaration.*" ??

I'm not entirely sure. Declaration refers to the declaration of a 
function or a class. But the actual 'function' or 'class' token should 
still be a keyword. I think we classify these as keyword.storage.

So (typing here from memory, and using the current naming scheme with 
function-name and function-argument) the way I think a PHP function 
should be marked up is:

    name = "declaration.function.php";
    begin = "^\\s*(function)\\s*([a-zA-Z0-9_]+)\\s*\\("; end = "\\)";
    captures = {   1 = { name = "keyword.storage.php"; };
                   2 = { name = "function-name"; };
    patterns = (
       {  name = "function-argument";
          match = "\\$[a-zA-Z0-9_]+"; }

> IF so, should I then change it into two sub groups called:
> -- "declaration.class.php"  = ( class, interface, extends, etc )
> -- "declaration.function.php"  = ( function, etc ? )
> or just rename it "declaration.php" ??  Bit confused ATM.

It should be the former (split between class/function). At least with 
the current system.

>> I think we should generally try to have as few top-level names as 
>> possible, adding to the depth rather than the breadth.
> I actually thought of just having "comment" in there rather than 
> "comment.line" as that would handle both, and users / settings devs 
> could extend it themselves in user / language setting files.

I'm not sure if people style their line/block comments differently. I 
used to do it, and I think the Ruby syntax did -- though I do find it 
useful for snippets to be able to work differently depending on the 
type of comment. Although here I'd like to further know whether it's a 
“#”-comment.line or “//”-comment.line.

I guess we could extend it to:

As of such, I do want the names to be very long so that they capture as 
much information as possible about the thing matched, but when looking 
at all names together, they should have as much as possible in common 
in the beginning of the names.

E.g. the OCaml syntax puts infix/prefix before floating-point in the 
keyword.operator name. That means that the OCaml styling needs to 
target two scopes instead of one, even when the operators should look 
the same, because they actually have no common prefix which aren't also 
shared with other stuff.

This is also the problem we have with class-name, function-name, and 
tag-name. If we want all 3 to look the same, which is not that 
unrealistic, then we need to target 3 different scopes.

[ Themes ]
> Therefore IF we could have a system like this, I think we could cut 
> down on confusion and clashes between user settings and dev's changes 
> to existing settings files

I think a very simple improvement on the current is just to allow the 
settings groups to be drag-sortable, and use the ordering when finding 

So basically the default stuff (that is shipped with TM or in repos.) 
would be in the bottom of the list, and the user would add a new 
settings group to the top, and anything he makes in that group takes 
precedence over the groups below (only though when there's a tie wrt 

So the user can either a) make a change to the default stuff (which 
causes a local copy to be created, and he'll never more see updates to 
that settings group, like when editing a bundle item) or b) he could 
create his own settings group and duplicate the item he want to change 
to that group, and he wouldn't need to make any changes to the 

This system could have different faces, like e.g. showing the default 
stuff as read-only, placing a separator in the list with the default 
stuff below it, and all that the user creates above it, shipping with a 
default “Your settings”-group which is empty etc. etc.

More information about the textmate-dev mailing list