Add hljs.registerAlias Method

[taufik-nurrohman]

Related:

• Add support for registerAlias similar to registerLanguage #2523
• File Extension as Aliases #2371

[joshgoebel]

Nice. Changelog and perhaps a simple test or two?

[joshgoebel]

Oh and you're going to need to update some docs also to add this since it's now public API.

api.rst

[wooorm]

Thanks! ✨ Looks functionally great, but I’m wondering about the api signature: Any reason why languageName is in an object, and not directly a parameter? Are there other values expected? Isn’t languageName the only really essential part of this call, whereas the aliases are optional?

[joshgoebel]

The older and wiser I get any function that takes more one or two unnamed parameters is a code smell - Objective C got this right long ago with every argument being named. But the short form of the idea is that often functions are verbs that act on nouns... so the first param is often clear from context.

startEngine(a,...)
registerAlias(b,...)

But the second, third, forth... all start to be completely meaningless... the closest thing we have to named arguments in JS are objects, and the new destructuring stuff names it quite easy to work with them in this way. (it wasn't hard before, but it's nicer now)

This way it's 100% clear what parameter is which.

registerAlias("js", { languageName: 'javascript' });

[joshgoebel]

Isn’t languageName the only really essential part of this call, whereas the aliases are optional?

I don't know what this means. You can't register an alias without telling it what language to point to... Both arguments are "essential". See verb/noun reasoning for why the "main subject" of the "action" of the function should be the first param.

Here is another API:

alterLanguage(languageName, addAliases: [...])

Same, verb/noun relationship... alter, what are we altering, the language. Very SQL like.

[wooorm]

As one could pass an empty list of aliases, it is not far off to see no alias the same as a list of no aliases.

[joshgoebel]

As one could pass an empty list of aliases

Could, but that would serve no purpose. If you have no aliases, then you have nothing to register.

[joshgoebel]

If I were being fancier I'd go with more English language:

register the alias "js" with the language: "javascript"

Translates to:

registerAlias("js", { withLanguage: 'javascript' });

[wooorm]

Could, but that would serve no purpose

Indeed, it should be a noop. Whereas no language should be an error.

---

I’m very glad this isn’t Java with its extremely long names. Or natural language.

For ordering: key, value|values is more in line with how other APIs, at least in JavaScript, work.

[joshgoebel]

For ordering: key, value|values is more in line with how other APIs, at least in JavaScript, work.

I don't think it's very useful to say "other APIs" as a general term as if all APIs were to be somehow treated the same - although if you had one particular article that made a general case fairly well I wouldn't mind reading it... This type of thinking makes big assumptions about the internal data storage. It's not the callers concern to know how this data is represented inside the library.

From the callers perspective they are "registering an alias" (the name of the function you recommended) and associating it with a given language. There isn't a key or value concept here.

To get technical: the alias IS actually the literal key here and the language the value, FYI... but again I only use that to make the point of how silly it is to base the ordering purely on the internal data structures. I don't use that point to support the ordering I've chosen - because again how it's stored internally is not relevant. :-)

[joshgoebel]

Indeed, it should be a noop. Whereas no language should be an error.

An empty array would be a noop right now, yes. No alias at all should be an error, just like no language should be. And I could imagine someone making a good argument for an empty array being an error condition too...

I get where you're going sort of, but I just don't agree with the premise. The whole idea makes little sense without both arguments, and even less with ONLY language.

registerAlias("javascript") // passing a language

Makes no sense... I can't do anything, I have no aliases, I have no subject for the verb - I have nothing to register. I could error or do literally nothing.

registerAlias("js") // passing an alias

I could actually do something here... I could keep a list of aliases waiting to be registered with languages, etc... pendingAliases(). Doesn't seem super useful to me... but since I have both the verb and subject I have options to decide what to do with that subject - HOW to register it.

[joshgoebel]

Anyways, if you have an article I'm happy to read it - I do try to keep an open mind... but right now verb/noun seems crystal clear here to me (as I've explained above) - and I find this verb/noun pattern to be extremely common pattern when naming functions.

My only thought is that it may have been better named registerAliases... revealing the full power of the function - that it can take an array - which likely could be an array of 1. Where as registerAlias doesn't reveal the use case of passing multiple items.

[wooorm]

An empty array would be a noop right now, yes. No alias at all should be an error, just like no language should be.

The reason for my thinking is to allow for the current code:

highlight.js/src/highlight.js

Lines 660 to 662 in 8c74229

	if (lang.aliases) {
	lang.aliases.forEach(function(alias) { aliases[alias] = name; });
	}

To be written as:

if (lang.aliases) {
  registerAlias(name, lang.aliases)
}

Or even:

registerAlias(name, lang.aliases)

...instead of:

if (lang.aliases) {
  registerAlias(lang.aliases, {languageName: name})
}

My proposal is based on my mental model of alternative names: there is a primary name, and there are zero or more alternative names. That it is stored in reverse, is indeed an implementation detail that I don’t need to know about.
I think of this as a setter, hence my comparison to map.set(key, value), element.setAttribute(key, value), etc.
One could think up other examples such as getters (where I prefer getter(name) instead of getter({languageName: name})) or a way to clear aliases (delete(name))? All probably not very useful, but this hopefully explains why I think what I think.

[joshgoebel]

This seems completely clear to me:

if (lang.aliases) {
  registerAliases(lang.aliases, {languageName})
}

Again there are no keys or values here, this isn't a Map. It's not a setter either, by it's very name. Your argument would hold up better if the language was the noun, but it's not.

if (lang.aliases) {
  alterLanguage(languageName, { addAliases: lang.aliases })
}

I would still have the conditional for clarity. I don't think passing null to the function and treating that the same as an empty array is a great habit to get into. (Writing TypeScript has made me think a lot harder about input and output typing). So I think your stated goal here (registerAlias(name, lang.aliases)) is NOT desirable when aliases is null/undefined.

Explicit almost always tops implicit for me.

One could think up other examples such as getters (where I prefer getter(name) instead of getter({languageName: name}))

Not sure I follow... this isn't [as large a] problem for single argument functions.

getLanguage(a)

Although this isn't immediately clear either... We can be sure what is returned by not was is passed, there could be multiple ways to find a language... by name, by unique ID, etc...

getLanguage("C++")
getLanguage("cpp")
getLanguage(32)
// vs
getLanguageBy({prettyName: "C++"})
getLanguageBy({name: "cpp"})
getLanguageBy({id: 32})

I think we're just going to have to agree to disagree.

[joshgoebel]

It's also not fully correct to think of aliases as purely an attribute of a single language - even more so now that we can add them dynamically - opening them up to all sorts of creative uses. I've already seriously considered things like the following:

registerAlias("php", languageNames: ["php_snippet", "php_template"])

IE, PHP could refer to either language... perhaps decided based on relevancy, etc... and we actually have another language where there are two languages with the same name... the kind of thing you could solve with more powerful aliases, also...

registerAlias("basic", languageNames: ["trs100_basic", "microsoft_basic","c64_basic"])

[joshgoebel]

I do think I finally understand you, but for me it's all about the naming. (that and my last point that I don't think of aliases are purely attributes of a language)

For me though as soon as the function name was registerAlias(es) (which is a reasonable enough name, and congruent with registerLanguage as you pointed out) there is no discussion to be had, the very name of the function tells you the first argument will be alias/aliases. Again, I think this verb/subject pattern is super common and used everywhere.

IF we had a different name then a different API might make sense (as I mentioned above somewhere). But we started with the name and we ended here.

[joshgoebel]

The swift guidelines make a lot of sense to me:

https://swift.org/documentation/api-design-guidelines/#argument-labels

The last rule being "Label all other arguments.", so their definitely on the labeling side of things. :-)

[joshgoebel]

The explicit naming also makes it clear that we expect a language name, not a language object...

var javascript = hljs.getLanguage("javascript")
// which is correct?  No way to know.
hljs.registerAlias("js", javascript)
hljs.registerAlias("js", "javascript")

It's completely unclear which would be the correct form (perhaps neither!), since you have no clue what that second argument is supposed to be. This is the problem with multiple unlabeled arguments - they lose all meaning at the call site. I could make it worse:

hljs.registerAlias("js", "javascript", true, false)

WHAT does that do? :-)

[joshgoebel]

I just had an interesting discussion where a colleague pointed out to me that native language could have an effect on what feel naturals regarding naming.

I think native language may have an effect though on what feels natural to someone. Word order being rather different, as I recall, in German vs. English.

I never even considered that aspect and I definitely write code from a purely English grammatical perspective. It's possible that a language that sequences things entirely different could lend itself to a different naming approach. Hard to say for certain, but it's easy to imagine. But English is all I have to work with.

[wooorm]

Thanks for all your comments! Yes, I do believe natural language is important. What I’m mostly worried about is that you point to Swift guidelines, which has named parameters, whereas JavaScript does not. By accepting an object, you can indeed label them, but for me objects imply optionality and that multiple fields are (or will be) supported.

I still feel I prefer addIngredient(salad, 'tomato') or addIngredient(pasta, 'capers') over the inverse. And would think addIngredient(soup) a noop as there is no ingredient. But indeed, we do disagree about this style. And that’s fine!

[joshgoebel]

What I’m mostly worried about is that you point to Swift guidelines, which has named parameters, whereas JavaScript does not.

Objects are the tool we have in JS to get named arguments. This was also a SUPER common pattern in Ruby also [named arguments passed as a Hash] until we got real named arguments. I'd imagine it's a pattern in other languages, also. This is what type definitions and documentation is for. :-) I pointed to that because it was an easy find vs spending more time looking for a JS example of someone preaching the same thing.

but for me objects imply optionality and that multiple fields are (or will be) supported.

You know what they say about implications, no wait that's assumptions, but still. :-) Consider letting go of that bias and I think you'll find some amazing new options in JS land. I think it's a very powerful, useful, and expressive pattern.

And that’s fine!

Indeed. :-)