Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
This has been replaced by Space
JavaScript CSS HTML
branch: master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
tests
.travis.yml
Note.js
example.html
makefile
mit-license.txt
note.min.js
package.json
package.note
readme.md
spec.txt
textmate.language

readme.md

Update: Note has been replaced by Space: https://github.com/breck7/space

Note

Note is a concise encoding for hash tables.

Note is designed to make it easy for both humans and programmers to read, write, edit, and share hash tables.

Examples

Here's how I could encode data about myself:

firstName Breck
lastName Yunits
birthday 02/26/1984
email breck7@gmail.com

Here's how I could encode a tax return:

socialSecurityNumber 555-55-5555
name John Smith
taxYear 2012
income 10,000
dependents 1
exemptions 2
address 123 Main Street
city San Francisco
state California

Here's how I could encode nested analytics about a website:

/homepage
 pageviews 2312
 uniques 231
 referers
  /about 23
  /contact 41
/about
 pageviews 314
 uniques 201
 referers
  /home 100
  /contact 21
/contact
 pageviews 214
 uniques 124
 referers
  /home 110
  /about 10

Design Goals

Human Readable. Note has no syntax characters other than whitespace to make it easy to read and edit. Unlike other languages such as XML or JSON, Note is designed to be easy for beginner programmers and complete laypersons to read and edit.

Concise. Note has just a few features to make it simple and broadly usable. There are no syntax characters other than whitespace, no types other than strings and nested hash tables, and Note uses the smallest amount of whitespace possible to establish structure. Unlike other whitespace languages which use 2-4 spaces (or the tab character), Note only uses a single space to indent an item or a single newline to seperate key/value pairs.

Extendable. Note is useful to solve many problems as is. However, Note is designed to be extendable. Although Note has no types other than hash tables and strings, you can build domain specific languages on top of Note that expect other types as encoded strings. Example: https://github.com/breck7/blocks

Technical Spec

The following is a higher level overview of the spec. The actual technical spec can be read here: https://github.com/breck7/note/blob/master/spec.txt

Data Structures. Note is a serialization format for recursive hash tables. Note uses 2 data structures: hash tables and strings.

Syntax Characters. Note has two special characters:

  1. The Space Character.
  2. The New Line Character.

A Note object is simply a hash table. A single space character(" ") separates a name with its value. A newline separates pairs. Names are always strings. Names can contain any character except space or newline. Values can be either strings or nested Note objects and can contain any character. A newline plus indented space indicates a nested hash table.

Programming Languages

Note does not care what programming language you use. Although the implementation of Note included here is built in Javascript, Note can be read, written, and modified easily with any programming language. In fact, one of the main benefits of Note is that it can be used by many programs, with many different languages, and they can all easily share hash tables using Note.

More implementations are coming soon.

More Examples

Basic Example

email john@doe.com

In the Note object above, "email" is a name, and "john@doe.com" is the corresponding value.

A Note object with multiple pairs

email john@doe.com
gender male

In the Note object above, "email" and "gender" are names, and "john@doe.com" and "male" are the corresponding values.

You can set values as strings like in the examples above, or you can set values to be nested Note objects by putting a newline immediately after the name and by indenting each item in the nested Note object by 1 space.

Nested Note

email john@doe.com
gender male
phone_numbers
 home 555-5555
 cell 444-4444

In this example, the value of phone_numbers is itself another Note object.

Multiline strings

email john@doe.com
gender male
phone_numbers
 home 555-5555
 cell 444-4444
biography This is my bio.
 It it written on multiple lines.
 There is a space after biography above, which instructs the code that this is
 a multiline string, and not a nested Note object.
 The end.

Values can be multiline strings by adding a space after the name (in this case "biography") and indenting the additional lines by one space.

Examples

Extending Note

Although Note has no types and very few features, you can easily build encodings on top of Note that do have types and additional features. Your extension can expect a leaf to follow a certain encoding (ie: HTML, JSON, CSV, Markdown, Base64, et cetera.).

For example, you could build a class called Person, that extends note, and expects a JSON encoded array for the favorite_colors property.

function Person (note) {
  this.patch(note)
  if (this.favorite_colors)
   this.favorite_colors = JSON.parse(this.favorite_colors)
}
Person.prototype = new Note()

var joe = new Person('favorite_colors ["blue", "red", "green"]')
console.log(joe.favorite_colors[0])
// prints "blue"
console.log(joe.favorite_colors[2])
// prints "green"

Javascript API

The Javascript library in this repo works in both the browser and with Node.js.

The API in the Javascript implementation is still somewhat in flux, but there are many neat methods such as diff, patch, and toString that demonstrate some neat features of Note.

Contributing

If you'd like to contribute please contact me at breck7@gmail.com.

Testing

Build Status

Support

Feel free to contact me at breck7@gmail.com for help using or extending Note.

Current Limitations

You cannot have spaces in names.

This object, with spaces in the name, cannot be represented in Note:

{ "This name has a space" : "value" }

To get around this you could rename the name, or use camelCasing or underscores instead of spaces.

Order is not important in Note.

A Note is a hash table and not an array, and so:

winners
 joe
 bob
 sam

is equivalent to

winners
 bob
 joe
 sam

If order is important for your application, you could specify the numbers:

winners
 1 joe
 2 bob
 3 sam

OR you can make your code expect a leaf node to contain an array type:

winners joe bob sam
winners ['joe', 'bob', 'sam]
winners joe,bob,sam

Influences

Note was inspired mostly by JSON and HAML, a bit by XML and YAML, and our personal desire for a simple, powerful encoding with less syntax.

Something went wrong with that request. Please try again.