urbit-hob

commit 64015f958226fe623c0bbf9078d5bd91d05d5da2
parent d0d48f337a597457810b83ca23d0cfcea621c287
Author: Jared Tobin <jared@jtobin.io>
Date:   Wed, 18 Sep 2019 11:43:19 -0230

ob, co, muk: add basic docs

Adds simple examples to Urbit.Ob.Co, in particular.

Diffstat:
M
lib/Urbit/Ob/Co.hs
 | 
59
++++++++++++++++++++++++++++++++++++++++++++++++++++++++---
M
lib/Urbit/Ob/Muk.hs
 | 
13
+++++++++++++
M
lib/Urbit/Ob/Ob.hs
 | 
15
++++++++++++++-

3 files changed, 83 insertions(+), 4 deletions(-)
diff --git a/lib/Urbit/Ob/Co.hs b/lib/Urbit/Ob/Co.hs
@@ -1,5 +1,18 @@
 {-# LANGUAGE OverloadedStrings #-}
 
+-- |
+-- Module: Urbit.Ob.Co
+-- Copyright: (c) 2019 Jared Tobin
+-- License: MIT
+--
+-- Maintainer: Jared Tobin <jared@jtobin.io>
+-- Stability: unstable
+-- Portability: ghc
+--
+-- General functions for atom printing.
+--
+-- Roughly analogous to the +co arm in hoon.hoon.
+
 module Urbit.Ob.Co (
     Patp
 
@@ -21,21 +34,54 @@ import Numeric.Natural (Natural)
 import Prelude hiding (log)
 import qualified Urbit.Ob.Ob as Ob (fein, fynd)
 
--- | A patp type.
+-- | Hoon's \@p encoding.
+--
+--   This encoding is an /obfuscated/ representation of some underlying number,
+--   but a pronounceable, memorable, and unique one.
+--
+--   The representation exists for any natural number, but it's typically used
+--   only for naming Azimuth points, and thus normal 32-bit Urbit ships.
+--
+--   (It's also used for naming comets, i.e. self-signed 128-bit Urbit ships.)
 --
---   Bytes are stored little-endian.
 newtype Patp = Patp BS.ByteString
-  deriving (Eq, Show)
+  deriving Eq
+
+instance Show Patp where
+  show = T.unpack . render
 
 unPatp :: Patp -> BS.ByteString
 unPatp (Patp p) = p
 
+-- | Convert a 'Natural' to \@p.
+--
+--   >>> patp 0
+--   ~zod
+--   >>> patp 256
+--   ~marzod
+--   >>> patp 65536
+--   ~dapnep-ronmyl
+--   >>> patp 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
+--   ~fipfes-fipfes-fipfes-fipfes--fipfes-fipfes-fipfes-fipfes
+--
 patp :: Natural -> Patp
 patp = Patp . BS.reverse . C.unroll . Ob.fein
 
+-- | Convert a \@p value to its corresponding 'Natural'.
+--
+--   >>> let zod = patp 0
+--   >>> fromPatp zod
+--   0
+--
 fromPatp :: Patp -> Natural
 fromPatp = Ob.fynd . C.roll . BS.reverse . unPatp
 
+-- | Render a \@p value as 'T.Text'.
+--
+--   >>> render (patp 0)
+--   "~zod"
+--   >>> render (patp 15663360)
+--   "~nidsut-tomdun"
 render :: Patp -> T.Text
 render (Patp bs) = render' bs
 
@@ -60,6 +106,13 @@ render' bs =
           then BS.cons 0 bs
           else bs
 
+-- | Parse a \@p value existing as 'T.Text'.
+--
+--   >>> parse "~nidsut-tomdun"
+--   Right ~nidsut-tomdun
+--   > parse "~fipfes-fipfes-fipfes-doznec"
+--   Right ~fipfes-fipfes-fipfes-doznec
+--
 parse :: T.Text -> Either T.Text Patp
 parse p =
       fmap (Patp . snd)
diff --git a/lib/Urbit/Ob/Muk.hs b/lib/Urbit/Ob/Muk.hs
@@ -1,4 +1,17 @@
 
+-- |
+-- Module: Urbit.Ob.Muk
+-- Copyright: (c) 2019 Jared Tobin
+-- License: MIT
+--
+-- Maintainer: Jared Tobin <jared@jtobin.io>
+-- Stability: unstable
+-- Portability: ghc
+--
+-- A specific murmur3 variant.
+--
+-- Analogous to +muk in hoon.hoon.
+
 module Urbit.Ob.Muk (
     muk
   ) where
diff --git a/lib/Urbit/Ob/Ob.hs b/lib/Urbit/Ob/Ob.hs
@@ -1,5 +1,18 @@
 {-# LANGUAGE BangPatterns #-}
 
+-- |
+-- Module: Urbit.Ob.Ob
+-- Copyright: (c) 2019 Jared Tobin
+-- License: MIT
+--
+-- Maintainer: Jared Tobin <jared@jtobin.io>
+-- Stability: unstable
+-- Portability: ghc
+--
+-- Integer obfuscation functions.
+--
+-- Analogous to the +ob arm in hoon.hoon.
+
 module Urbit.Ob.Ob (
     fein
   , fynd
@@ -43,7 +56,7 @@ fynd = loop where
              then hi .|. loop lo
              else cry
 
--- | Generalised Feistel cipher
+-- | Generalised Feistel cipher.
 --
 --   See: Black and Rogaway (2002), "Ciphers with arbitrary finite domains."
 --