[人] Ren - The Human Notation

Not everything you ever wanted to
know, but maybe enough for now.

Ceský Dansk Nederlands Français Deutsch Italiano Polski Español

Grammar (informative)
Repetition and alternation denotation.

opt means zero or one
any means zero or more
some means one or more
or means alternation

list: [ _anyvalue ]
map: #( _anyname-value-pair )
name-value-pair: name value
name: word : space
value: list _or map _or string _or percent _or number
_or logic _or none _or datetime _or date _or time
_or name _or word _or implied-string
_or segmented-number _or point
_or base-16-binary _or base-64-binary

string: " _anychar "
char: any-Unicode-char-except-"-or-^-or-control-char
^"; double quote
^/; linefeed
^M; carriage return
^@; null
^(XXXXxxxx) ; 4 or 8 hex digits
number: _optsign int _optfrac _optexp
int: _somedigits
frac: . _anydigits
exp: _one-ofEe _optsign _somedigits
sign: + _or -
digits: _one-of0123456789
percent: number %
logic: true _or false _or on _or off _or yes _or no
none: none
date: ₄digits - ₂digits - ₂digits
time: hours-minutes _optseconds
hours-minutes: _optsign ₂digits : ₂digits
seconds: : ₂digits _optfrac
tz-sep: / _or T _or @
timezone: Z _or hours-minutes
date-time: date tz-sep time _opttimezone
word-first-char: _not0123456789{}"()/\@#$%^,:;<>[]'
word-inner-char: word-first-char_ordigits
word: word-first-char _anyword-inner-char
implied-string: word-first-char _anyimp-str-inner-char
imp-str-inner-char: word-inner-char_or one-of/\@#$%,:'
segmented-number: int _2-or-moreseg-num-segment
seg-num-segment: . int
point: number _someaxis
axis: x number
base-16-binary: _opt16 #{ _{any 2}base-16-char } ; groups of 2
base-64-binary: 64#{ _{any 4}base-64-char } ; groups of 4

Goals:

Programming language independent text format
Be easy for programs to parse and generate
Be easy for humans to read and write
Reduce line noise for common datatypes
Keep it simple

Uses:

Data exchange between people and machines
Messaging
Configuration files
Document-oriented (schema-free) databases
Embedded data storage

Why is Ren so much more complicated than JSON?

It makes more datatype values directly identifiable by their lexical form. That complicates the grammar for implementers somewhat, but the small number of added literals, and extra datatypes provide a great deal of expressive power.

Why is Ren so much less complicated than XML?

Really?

Why is none used instead of null?

Null is a very programmer-friendly term, and may even be friendly to mathematicians, but it isn't friendly to normal people who might be given configuration or message files to edit. None also can't be as easily confused with Null as a character or a zero value. Unknown could be a nice word for this but, while we don't focus exclusively on being terse in the Redbol world, "unknown" is a lot more work to type than "none", and harder to scan visually.

    Preferences: none
    Theme: none

Why doesn't Ren use commas between values in lists and name-value pairs in maps?

Ren values are separated by whitespace, commas would be redundant. They also aren't a good fit in line-oriented configuration files.

Why does Ren call true and false logic values, instead of boolean?

As programmers, we're used to calling them booleans but it's a subjective call, and can't be seen as right or wrong.

Why does Ren support alternate logic literals like yes, no, on, and off?

For the same reason it supports true and false as substitutes for 0 and 1. They convey meaning.

    switch-1: off
    ready?: yes

Why doesn't Ren use backslash escapes?

The backslash is the most common escape character in C-like languages, but Ren is not a C-like language. While there is no perfect escape notation (if there were, all languages would use it), Ren chose its escape notation for a few reasons.

The backslash is used in Windows file paths
Using alpha chars for control codes mixes meanings
It matches ASCII caret notation
Leaning toothpick syndrome
ASCII Record Separator (RS) and Unit Separator (US) are
non-printing characters, making them...hard to type

It's another subjective call about what reads best to humans, while still being unambiguous when parsing, and considering delimiter collision. That said, because the backslash has no special meaning to Ren, you can use it for most escape sequences in strings in your C-like language of choice. An exception is the double quote character, because that is important to Ren.

What is the preferred file extension for a Ren file?

.ren. But Ren doesn't care.

What is the preferred MIME content-type to use for Ren data?

application/ren

If I have Ren data, but do not put [] or #() around it, what should the resulting structure be?

It should be treated as a streaming list by default. But if you notice that it contains well-formed name-value pairs, by all means make it a map. Configuration files are a good example. And if it contains a single Ren value, you can treat it as such.

How were the grammar diagrams created for Ren?

With Redlake Technologies' Railroad Diagram Generator.

Why does Ren use the format it does for names in name-value pairs?

The format may look familiar, because it's very close to the RFC822 standard for header fields. iCal also uses the name: format. When something makes sense to non-programmers at a glance, and when it has stood the test of time, Ren listens. Yes, even the term word is used in RFC822. It also more clearly implies that name: refers to what comes after it, the value is not being assigned to it. When it comes to parsing data, there is also great value in name: being an atomic element.