hisham hm

Writing release announcement emails

Mailing lists are not exactly fashionable nowadays, but some of them remain relevant for some communities. The Lua community is one such example. As of 2017, a lot of what goes on in the Lua module development world still resonates in lua-l. With over 2500 subscribers, it’s a good way to kickstart interest in your new project.

Mailing list users tend to be somewhat pedantic about etiquette guidelines for posting, especially for announcements and the like. So, I usually follow this little formula for writing release announcement emails, which has been effective for me:

An example of an upgrade announcement is here:

[ANN] LuaRocks 2.4.2

Hello, list!

I'm happy to announce LuaRocks 2.4.2. LuaRocks is the Lua package
manager. (For more information, please visit http://luarocks.org )


Those of you on Unix who are running LuaRocks as a rock (i.e. those
who previously installed using `make bootstrap`) can install it using:

   luarocks install luarocks

What's new since 2.4.1:

* Fixed conflict resolution on deploy/delete
* Improved dependency check messages
* Performance improvements when removing packages
* Support user-defined `platforms` array in config file
* Improvements in Lua interpreter version detection in Unix configure script
* Relaxed Lua version detection to improve support for alternative
implementations (e.g. Ravi)
* Plus assorted bugfixes and improvements

This release contains commits by Peter Melnichenko, Robert Karasek and myself.

As always, all kinds of feedback is greatly appreciated.

Thank you, enjoy!

-- Hisham

An example of a new project announcement is here:

[ANN] safer - Paranoid Lua programming


Announcing yet another "strict-mode" style module: "safer".

* http://github.com/hishamhm/safer

Install with
   luarocks install safer

# Safer - Paranoid Lua programming

Taking defensive programming to the next level. Use this module
to avoid unexpected globals creeping up in your code, and stopping
sub-modules from fiddling with fields of tables as you pass them

## API

#### `safer.globals([exception_globals], [exception_nils])`

No new globals after this point.

`exception_globals` is an optional set (keys are strings, values are
`true`) specifying names to be exceptionally accepted as new globals.
Use this in case you have to declare a legacy module that declares a
global, for example. A few legacy modules are already handled by

`exception_nils` is an optional set (keys are strings, values are
`true`) specifying names
to be exceptionally accepted to be accessed as nonexisting globals.
Use this in case code does feature-testing based on checking the
presence of globals. A few common feature-test nils such as `jit` and
`unpack` are already handled by default.

#### `t = safer.table(t)`

Block creation of new fields in this table.

#### `t = safer.readonly(t)`

Make table read-only: block creation of new fields in this table
and setting new values to existing fields.

Note that both `safer.table` and `safer.readonly` are implemented
creating a proxy table, so:

* Equality tests will fail: `safer.readonly(t) ~= t`
* If anyone still has a reference to this table prior
  to creating the safer version, they can still mess
  with the unsafe table and affect the safe one.


Licensed under the terms of the MIT License, the same as Lua.

During its genesis, this module was called "safe", but I renamed it
to "safer" to remind us that we are never fully safe. ;)

-- Hisham
http://hisham.hm/ - @hisham_hm

Hope this helps!

The danger of simple examples

When discussing language syntax, people often resort to small examples using simple variables like foo or x, almost like “meta-syntactic variables”, i.e., to make clear these tokens are outside of the syntax under discussion.

One dangerous side-effect, though, is that these variables are always short and sweet. And syntax that works well with short variables doesn’t always work as well in real-world situations where they have to deal with the rest of the language.

Case the first

Recently we were discussing multiple assignment style in the Lua mailing list. Someone suggested this:

local a, b, c, d =
      e, f, g, h

…which makes the assignments “more parallel” than a single line and avoid writing lots of locals.
I think this a case where the over-simplified example is misleading.
With real-world looking variables, it would look more like

local cfg,              constraints, module_name,          initial_path =
      "default_config", {},          get_module_name(ctx), "/etc/myapp/default.config"

So yeah, It looks pretty with a, b, c but in the real world with significant names, this becomes a pain to maintain, and when we stuff too much in a single line, diffs are harder to read.

Case the second

Things always look good in tiny examples with single-letter variables. Which brings me to a gripe I have with an often-suggested Lua idiom: the famous t[#t+1] = v to append to arrays.

The reason why I think it’s so disengenious to defend t[#t+1] = v as the preferred idiom for appending to an array is because it looks good with a single-letter variable and five-line tutorial examples, but in the real world we use nested tables. In the end, table.insert(my.nested[data], v) is both more readable and avoids repetition:

Note how it’s not even necessarily shorter: in this realistic example the variable name dominates the size of the statement:

table.insert(my.nested[data], val)
my.nested[data][#my.nested[data] + 1] = val

Do I think table.insert is too long? Yes I do, I wouldn’t mind having a shorter idiom (many were proposed in the Lua list over the years, most of them were fine, but I’m not getting into them because we risk delving into syntactic bikeshedding again, so let’s avoid that).

Do I think it’s worth it to add local tinsert = table.insert to every program? No, I think this is worse than the t[#t+1] = v idiom, because I hate having to guess which abbreviation the module author used to write a shorter table.insert in their code (I’ve even seen local append = table.insert in the wild!). And then again, the abbreviation doesn’t gain us much: being comfortable to read is more important than being comfortable to write, but being easy to maintain is just as important if not more.

And yes, it is important to ponder what are the differences between being “easy to read”, “easy to write” and “easy to maintain”. And when pondering those, watch out for misleading short variables in the examples!

Of course, some idioms are advisable specifically for when you have short variables:

local r, g, b = 0, 255, 0

Everyone can easily read what’s going on there. But note that, almost without noticing, I also used a realistic example here! Realistic examples help getting the discussion grounded, and I find that they are often lacking when discussing syntax.

PS: And before someone mentions, the performance gains for localizing such variables as local tinsert = table.insert are overstated:

Terça-feira, 7 de março

Estava entre Ipanema e Leblon. Entrei numa banca de jornal, pela primeira vez em muito tempo, movido por pura curiosidade de olhar as revistas, além das capas de Veja, IstoÉ e Carta Capital que eu vejo penduradas todo dia. Fiquei me perguntando quem compra as revistas de dentro da banca hoje e quais revistas eu encontraria lá dentro.

Meu olho foi correndo meio a esmo. No fundo eu queria saber se acharia uma Guitar World, como as que o meu irmão mais velho comprava quando eu era criança, mas não achei.

A prateleira da altura dos olhos (sempre a mais importante no comércio, aprendi pequeno em casa) é tomada por revistas de palavras cruzadas da Coquerel.

Um livrinho “Old Games” exibia um grande logo do MSX. Dizia “436 jogos”. Fiquei imaginando se sairia uma edição do Apple II.

Num canto, os quadrinhos de faroeste do Tex. Quando eu era criança, elas já ficavam num canto da banca. Quando eu era criança, eu já me perguntava “quem diabos compra revistas do Tex?”

Revistas de mangá. Muitos mangás. Acho que tantos quanto revistas de palavras cruzadas. Esses não existiam na banca quando eu era criança.

Olho pra baixo, e pra minha surpresa aonda existe Disney Especial. “Os Cineastas”. Quando eu era criança muitas dessas edições já eram reedições do tempo que os meus irmãos mais velhos eram crianças.

Minha jornada nostálgica à infância é interrompida quando uma voz pergunta ao jornaleiro, que estava tranquilamente me ignorando atrás do balcão:

“Tem seda?”

Era um guri loirinho de cabelos cacheados, camiseta de uniforme de colégio particular, nenhum fio de barba no rosto, guiando uma bicicleta elétrica. Ele e o jornaleiro trocaram duas frases, acho que sobre o tipo de seda, não entendi direito, logo ele partiu.

Fui embora da banca. Não comprei nada, mas saí de lá me sentindo ao mesmo tempo velho e criança.

Receita de hummus

Para cada lata de grão de bico meio limão e duas colheres cheias de tahine um dentinho de alho e sal a gosto.

Botar tudo no liquidificador e bater.

Pen-and-paper Street Fighter II

I just remembered an interesting tidbit from my childhood.

Around 7th grade in school I invented a pen-and-paper version of Street Fighter II for people to play during classes.

I don’t remember the exact details, but basically I drew a grid for the screen and then I drew stick figures in it, and passed the page around.

People would write-in their moves and then I played CPU: I’d erase the stick figures and redraw in new positions, update hit/miss, update the energy meters.

I remember trying to keep it balanced and true to the game: Dhalsim’s punch and kick could hit farther but were weaker, etc. I had all of the “sprites” with the character movements pre-determined on my notebook.

The game went on sneaking a page back and forth along players and me at the back of the class. I imagine how bored out of our minds we must have been in school to enjoy playing “Street Fighter II at 0.05 frames per second”.