Permalink
Browse files

Basic docs about annotations

  • Loading branch information...
dahlia committed Oct 29, 2017
1 parent 46b1dfe commit fc45316420b2fbd6a90c00a718a456914a82ffec
Showing with 131 additions and 0 deletions.
  1. +131 −0 docs/annotation.md
View
@@ -0,0 +1,131 @@
Annotations
===========
Annotations can be attached to any declarations, and purpose to be used
as directive or metadata by target compiler or runtime library.
Each annotation starts with an `@` character, and its name follows,
e.g., `@foo`. Annotation names have the same rule to other Nirum identifiers,
but there's no separation of facial and behind names.
There are annotations defined and used by a target compiler, or more than one
targets. If an annotation that no target defined is used, they are merely no-op
(i.e., ignored and even not errored).
Nirum annotations are similar to Java's one or C#'s attributes.
Declarations
------------
All declarations in Nirum can attach annotations. Declarations in Nirum mean
things that have their own name, e.g., imports, records, fields, union tags,
service methods, method parameters. In other words, any things that can have
docs comments also can have annotations.
Each declaration is allowed to have multiple annotations, but their name cannot
be duplicated.
For example, the following code is allowed:
~~~~~~~~ nirum
@foo
@bar(baz = "qux")
boxed filename (text);
~~~~~~~~
Whereas the following code is disallowed:
~~~~~~~~ nirum
@foo
@foo(baz = "qux") // `foo` is duplicated
boxed filename (text);
~~~~~~~~
Arguments
---------
Annotations have zero or more arguments. Every parameter is named, and names
cannot be duplicated in an annotation. Annotation arguments follow
an annotation name and are wrapped by parentheses. An `=` operator is placed
between each parameter name and its argument value. Arguments are separated
by a comma, and an optional trailing comma is also allowed. E.g.:
~~~~~~~~ nirum
@foo()
@bar(baz = "qux")
@quux(corge = "grault", garply = "waldo", fred = "plugh",)
boxed filename (text);
~~~~~~~~
Currently, argument values are only allowed to be a text (which is wrapped by
double quotes), but they could be extended to other types (e.g., integer).
Note that C-style escape sequences work between double quotes, e.g.:
~~~~~~~~ nirum
@foo(bar = "Escape double quotes (\") with backslashes (\\).")
boxed filename (text);
~~~~~~~~
Common annotations
------------------
The following annotations are common among more than one target languages.
For target-specific annotations, read each target's docs.
### `@docs` (`docs`)
`@docs` annotations represent docs comments (`# ...`). The following two
examples are equivalent, and the former is internally transformed to the latter:
~~~~~~~~ nirum
# Docs comments are transformed to `@docs` annotations.
boxed filename (text);
~~~~~~~~
~~~~~~~~ nirum
@docs(docs = "Docs comments are transformed to `@docs` annotations.\n")
boxed filename (text);
~~~~~~~~
It is primarily for simplifying internal syntax tree, but can be used at runtime
for other purposes.
Since all docs comments become transformed to `@docs` annotations,
a declaration cannot have both a docs comment and a `@docs` annotation at
a time.
`docs`
: A docs text.
### `@error`
Many object-oriented languages (e.g., Java, Python) require exception classes
to inherit a specific base class (e.g., `Exception`) to be thrown.
`@error` annotation is a hint for such languages to make a record or a union to
inherit that.
For example, the following first Nirum code is compiled to the second Python
code:
~~~~~~~~ nirum
@error
union file-error = file-not-found
| file-not-readable
;
~~~~~~~~
~~~~~~~~ python
class FileError(Exception):
...
class FileNotFound(FileError):
...
class FileNotReadable(FileError):
...
~~~~~~~~

0 comments on commit fc45316

Please sign in to comment.