Writing Nomi
Style guidelines for hand-written Nomi (.nomi): examples, the stdlib (std/) and tests/. Each rule says which of several legal forms to choose and why. nomi fmt owns layout (§1), and the compiler owns what is legal.
The specification says what the language does. A reference written spec §N names one of its sections; a bare §N names a rule of this guide. A rule that names a feature links the spec section that defines it and, where one teaches it, the tour chapter.
This guide is the canonical list of Nomi’s conventions: a new one is added here, not scattered across other docs.
These pages are generated from docs/style.md in the repository.
Files and layout
Section titled “Files and layout”Names and bindings
Section titled “Names and bindings”- 4. Naming
- 5. Leave a binding’s type off when inference settles it
- 6. Thread one binding instead of inventing name ladders
Calls and functions
Section titled “Calls and functions”- 7. Pipe nested calls
- 8. Tracing with
dbg - 9. Call style
- 10. Read a field with
.name, notfn x -> x.name - 11. Pass a constructor, not
fn x -> Some(x) - 12.
returnis for leaving early
Types and values
Section titled “Types and values”- 13. Keep a type’s impls beside it
- 14. Write one derive declaration per interface
- 15. List an enum’s variants with
derive Variants - 16. Leave out a literal’s type name where the context names it
- 17. Use a tuple for a local pairing and a struct once it travels
- 18. Read a distinct’s value by destructuring
- 19. Use
typealiasonly to shorten a long anonymous shape - 20. Use a codepoint literal for codepoint work and a string for text
- 21. Write a typed literal with backticks only when its text has backslashes
- 22. Reach for the type that holds the value exactly:
DateTime, andDecimaloverFloat - 23. Write bit operations with the operators
Patterns and conditions
Section titled “Patterns and conditions”- 24. Test a match with
is, bind withif Pattern = x, branch withcase - 25. Join arms with one body by
or - 26. Take a vector apart with a pattern when its shape decides
- 27. Write a
caseof conditions with no subject - 28. Negate with
!=,refuteandIter.rejectbeforenot
Failure
Section titled “Failure”Collections and iteration
Section titled “Collections and iteration”- 31. Test membership with
in - 32. Collect a grid into a
SetorMaponce - 33. Reach for a named fold before
Iter.reduce - 34. Number elements with
Iter.with_index, not a counter in the state - 35. Choose between recursion,
Iter.loopandIter.iterate - 36. Build a list newest first and reverse it once
- 37. Sort by several keys with one tuple key
Applications and tests
Section titled “Applications and tests”- 38. Boot builds the application value
- 39. Write tests as ordinary code with direct assertions
- 40. Assert the value under test
- 41. Check a table of inputs with
subtests - 42. Keep expected values the tests share in a
once - 43. Test an interactive program with
io.replay - 44. Share a group’s boot and fakes through a helper file
Designing a module’s API
Section titled “Designing a module’s API”- 45. Put the data first
- 46. Name conversions and locale functions by their shape
- 47. Make a type opaque to keep an invariant
- 48. Give a module’s errors an enum
- 49. Doc comments and examples
- 50. Write generated code a reader can trust
- 51. Acquire a resource, then
deferits release on the next line - 52. Take an interface value unless the caller’s type comes back