urbit-ob

JavaScript utilities for phonemic base wrangling.
git clone git://git.jtobin.io/urbit-ob.git
Log | Files | Refs | README

README.md (2686B)

      1 # urbit-ob
      2 
      3 [![Build Status](https://secure.travis-ci.org/urbit/urbit-ob.png)](http://travis-ci.org/urbit/urbit-ob)
      4 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
      5 [![npm](https://img.shields.io/npm/v/urbit-ob.svg)](https://www.npmjs.com/package/urbit-ob)
      6 
      7 Utilities for phonetic base wrangling.
      8 
      9 ## What
     10 
     11 Here you can primarily find functions for dealing with the *phonetic bases*
     12 used by Urbit.  The `@p` encoding is used for naming ships, while the `@q`
     13 encoding is used for representing arbitrary data in a memorable and
     14 pronounceable fashion.
     15 
     16 The `@p` encoding is an *obfuscated* representation of an underlying 32-bit
     17 number, in particular, hence the 'ob' in the library's name.
     18 
     19 ## Install
     20 
     21 You can grab the library from npm via:
     22 
     23 ```
     24 npm install urbit-ob
     25 ```
     26 
     27 Otherwise you can just clone the repo, and a simple `npm install` will pull
     28 down the dependencies.
     29 
     30 ## Usage
     31 
     32 The library exposes two families of functions:
     33 
     34 * `patp / patp2dec / patp2hex / hex2patp / isValidPatp`
     35 * `patq / patq2dec / patq2hex / hex2patq / isValidPatq`
     36 
     37 They are pretty self-explanatory.  Use `patp` or `patq` to convert base-10
     38 numbers (or strings encoding base-10 numbers) to `@p` or `@q` respectively.
     39 Use `patp2dec` or `patq2dec` to go in reverse.  `patp2hex`, `patq2hex`, and
     40 their inverses work similarly.  `isValidPat{p, q}` can be used to check the
     41 validity of a `@p` or `@q` string.
     42 
     43 Some examples:
     44 
     45 ```
     46 > const ob = require('urbit-ob')
     47 > ob.patp('0')
     48 '~zod'
     49 > ob.patp2dec('~nidsut-tomdun')
     50 '15663360'
     51 > ob.hex2patq('010203')
     52 '~doznec-binwes'
     53 > ob.patq2hex('~marned-wismul-nilsev-botnyt')
     54 '01ca0e51d20462f3'
     55 > ob.isValidPatq('~marned-wismul-nilsev-botnyt')
     56 > true
     57 ```
     58 
     59 There are a few other noteworthy functions exposed as well:
     60 
     61 * `clan`, for determining the ship class of a `@p` value
     62 * `sein`, for determining the parent of a `@p` value
     63 * `eqPatq`, for comparing `@q` values for equality
     64 * `isValidPat`, for a faster/weaker check of `@p` or `@q`-ness that only
     65   validates syllables (and not proper dash formatting)
     66 
     67 For example, you can check that `~marzod` is a star with parent `~zod`:
     68 
     69 ```
     70 > ob.clan('~marzod')
     71 'star'
     72 > ob.sein('~marzod')
     73 '~zod'
     74 ```
     75 
     76 And note that `@q` values are considered equal modulo the existence of leading
     77 zero bytes:
     78 
     79 ```
     80 > '~doznec-marzod' === '~nec-marzod'
     81 false
     82 > ob.eqPatq('~doznec-marzod', '~nec-marzod')
     83 true
     84 ```
     85 
     86 ## Testing
     87 
     88 A simple `npm test` will run the test suite.
     89 
     90 
     91 ## Building
     92 
     93 `npm run build` will build the library for the browser.
     94 
     95 ## See Also
     96 
     97 * [urbit-hob](https://github.com/urbit/urbit-hob) -- Haskell bindings
     98 * [urbit-gob](https://github.com/deelawn/urbit-gob) -- Go bindings