commit fa4e8f4a3177f50dd16ac577ca7abb4ece7e283b · anil.recoil.org/ocaml-crockford

.gitignore

+22

LICENSE.md

···

       1
       1
       +
       MIT License

     

       2
       2
       +
       

     

       3
       3
       +
       Copyright (c) 2024-2025 Front Matter

     

       4
       4
       +
       Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>

     

       5
       5
       +
       

     

       6
       6
       +
       Permission is hereby granted, free of charge, to any person obtaining a copy

     

       7
       7
       +
       of this software and associated documentation files (the "Software"), to deal

     

       8
       8
       +
       in the Software without restriction, including without limitation the rights

     

       9
       9
       +
       to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

     

       10
       10
       +
       copies of the Software, and to permit persons to whom the Software is

     

       11
       11
       +
       furnished to do so, subject to the following conditions:

     

       12
       12
       +
       

     

       13
       13
       +
       The above copyright notice and this permission notice shall be included in all

     

       14
       14
       +
       copies or substantial portions of the Software.

     

       15
       15
       +
       

     

       16
       16
       +
       THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

     

       17
       17
       +
       IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

     

       18
       18
       +
       FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

     

       19
       19
       +
       AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

     

       20
       20
       +
       LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

     

       21
       21
       +
       OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

     

       22
       22
       +
       SOFTWARE.

+95

README.md

···

       1
       1
       +
       # Crockford Base32 Encoding for OCaml

     

       2
       2
       +
       

     

       3
       3
       +
       An OCaml implementation of [Douglas Crockford's

     

       4
       4
       +
       Base32](https://www.crockford.com/base32.html) encoding with ISO 7064 checksum

     

       5
       5
       +
       support. Provides encoding and decoding of int64 values to URI-friendly base32

     

       6
       6
       +
       strings, with optional checksum validation, padding, splitting, and random ID

     

       7
       7
       +
       generation. Ported from <https://github.com/front-matter/commonmeta>.

     

       8
       8
       +
       

     

       9
       9
       +
       ## Installation

     

       10
       10
       +
       

     

       11
       11
       +
       ```bash

     

       12
       12
       +
       opam install crockford

     

       13
       13
       +
       ```

     

       14
       14
       +
       

     

       15
       15
       +
       Or add to your `dune-project`:

     

       16
       16
       +
       

     

       17
       17
       +
       ```scheme

     

       18
       18
       +
       (package

     

       19
       19
       +
         (depends

     

       20
       20
       +
           (crockford)))

     

       21
       21
       +
       ```

     

       22
       22
       +
       

     

       23
       23
       +
       ## Usage

     

       24
       24
       +
       

     

       25
       25
       +
       ### Basic Encoding and Decoding

     

       26
       26
       +
       

     

       27
       27
       +
       ```ocaml

     

       28
       28
       +
       (* Encode a number *)

     

       29
       29
       +
       let encoded = Crockford.encode 1234567890L in

     

       30
       30
       +
       (* "16jkpa2" *)

     

       31
       31
       +
       

     

       32
       32
       +
       (* Decode back to number *)

     

       33
       33
       +
       let decoded = Crockford.decode "16jkpa2" in

     

       34
       34
       +
       (* 1234567890L *)

     

       35
       35
       +
       ```

     

       36
       36
       +
       

     

       37
       37
       +
       ### With Checksum

     

       38
       38
       +
       

     

       39
       39
       +
       ```ocaml

     

       40
       40
       +
       (* Encode with checksum *)

     

       41
       41
       +
       let encoded = Crockford.encode ~checksum:true 1234567890L in

     

       42
       42
       +
       (* "16jkpa2d" *)

     

       43
       43
       +
       

     

       44
       44
       +
       (* Decode and validate checksum *)

     

       45
       45
       +
       let decoded = Crockford.decode ~checksum:true "16jkpa2d" in

     

       46
       46
       +
       (* 1234567890L - or raises Checksum_mismatch if invalid *)

     

       47
       47
       +
       ```

     

       48
       48
       +
       

     

       49
       49
       +
       ### Formatted Output

     

       50
       50
       +
       

     

       51
       51
       +
       ```ocaml

     

       52
       52
       +
       (* Split with dashes for readability *)

     

       53
       53
       +
       let encoded = Crockford.encode ~split_every:4 1234567890L in

     

       54
       54
       +
       (* "16jk-pa2" *)

     

       55
       55
       +
       

     

       56
       56
       +
       (* With minimum length (zero-padded) *)

     

       57
       57
       +
       let encoded = Crockford.encode ~min_length:10 1234L in

     

       58
       58
       +
       (* "000000016j" *)

     

       59
       59
       +
       ```

     

       60
       60
       +
       

     

       61
       61
       +
       ### Random ID Generation

     

       62
       62
       +
       

     

       63
       63
       +
       ```ocaml

     

       64
       64
       +
       Random.self_init ();

     

       65
       65
       +
       

     

       66
       66
       +
       (* Generate random IDs *)

     

       67
       67
       +
       let id = Crockford.generate ~length:8 ~checksum:true () in

     

       68
       68
       +
       (* e.g., "a3x7m9q5" *)

     

       69
       69
       +
       

     

       70
       70
       +
       (* Generate formatted IDs *)

     

       71
       71
       +
       let id = Crockford.generate ~length:16 ~split_every:4 ~checksum:true () in

     

       72
       72
       +
       (* e.g., "7n2q-8xkm-5pwt-3hr9" *)

     

       73
       73
       +
       ```

     

       74
       74
       +
       

     

       75
       75
       +
       ### Normalization

     

       76
       76
       +
       

     

       77
       77
       +
       ```ocaml

     

       78
       78
       +
       (* Handles common character confusions *)

     

       79
       79
       +
       let decoded = Crockford.decode "ILO" in  (* Treated as "110" *)

     

       80
       80
       +
       let decoded = Crockford.decode "16-JK-PA" in  (* Dashes ignored *)

     

       81
       81
       +
       ```

     

       82
       82
       +
       

     

       83
       83
       +
       ## License

     

       84
       84
       +
       

     

       85
       85
       +
       MIT License

     

       86
       86
       +
       

     

       87
       87
       +
       ## Author

     

       88
       88
       +
       

     

       89
       89
       +
       Anil Madhavapeddy <anil@recoil.org>

     

       90
       90
       +
       (based on code from https://github.com/front-matter/commonmeta)

     

       91
       91
       +
       

     

       92
       92
       +
       ## Links

     

       93
       93
       +
       

     

       94
       94
       +
       - [Homepage](https://tangled.org/@anil.recoil.org/ocaml-crockford)

     

       95
       95
       +
       - [Crockford Base32 Specification](https://www.crockford.com/base32.html)

bin/dune

···

       1
       1
       +
       (executable

     

       2
       2
       +
        (name roguedoi)

     

       3
       3
       +
        (public_name roguedoi)

     

       4
       4
       +
        (libraries crockford cmdliner))

+32

bin/roguedoi.ml

···

       1
       1
       +
       (* roguedoi.ml - Generate random DOI identifiers with Crockford base32 encoding *)

     

       2
       2
       +
       

     

       3
       3
       +
       let generate_doi prefix length split =

     

       4
       4
       +
         Random.self_init ();

     

       5
       5
       +
         let suffix = Crockford.generate ~length ~split_every:split ~checksum:true () in

     

       6
       6
       +
         Printf.printf "https://doi.org/%s/%s\n%!" prefix suffix

     

       7
       7
       +
       

     

       8
       8
       +
       let () =

     

       9
       9
       +
         let open Cmdliner in

     

       10
       10
       +
       

     

       11
       11
       +
         let prefix =

     

       12
       12
       +
           let doc = "DOI prefix to use (e.g., 10.59350)" in

     

       13
       13
       +
           Arg.(value & opt string "10.59350" & info ["p"; "prefix"] ~docv:"PREFIX" ~doc)

     

       14
       14
       +
         in

     

       15
       15
       +
       

     

       16
       16
       +
         let length =

     

       17
       17
       +
           let doc = "Total length of the generated suffix (including checksum)" in

     

       18
       18
       +
           Arg.(value & opt int 10 & info ["l"; "length"] ~docv:"LENGTH" ~doc)

     

       19
       19
       +
         in

     

       20
       20
       +
       

     

       21
       21
       +
         let split =

     

       22
       22
       +
           let doc = "Split the suffix every N characters with hyphens (0 = no splitting)" in

     

       23
       23
       +
           Arg.(value & opt int 5 & info ["s"; "split"] ~docv:"SPLIT" ~doc)

     

       24
       24
       +
         in

     

       25
       25
       +
       

     

       26
       26
       +
         let generate_cmd =

     

       27
       27
       +
           let doc = "Generate a random DOI with Crockford base32 encoding" in

     

       28
       28
       +
           let info = Cmd.info "roguedoi" ~version:"0.1.0" ~doc in

     

       29
       29
       +
           Cmd.v info Term.(const generate_doi $ prefix $ length $ split)

     

       30
       30
       +
         in

     

       31
       31
       +
       

     

       32
       32
       +
         exit (Cmd.eval generate_cmd)

+32

crockford.opam

···

       1
       1
       +
       # This file is generated by dune, edit dune-project instead

     

       2
       2
       +
       opam-version: "2.0"

     

       3
       3
       +
       synopsis: "Crockford Base32 encoding for OCaml"

     

       4
       4
       +
       description:

     

       5
       5
       +
         "An OCaml implementation of Douglas Crockford's Base32 encoding with ISO 7064 checksum support. Provides encoding and decoding of int64 values to URI-friendly base32 strings, with optional checksum validation, padding, splitting, and random ID generation."

     

       6
       6
       +
       maintainer: ["Anil Madhavapeddy <anil@recoil.org>"]

     

       7
       7
       +
       authors: ["Anil Madhavapeddy"]

     

       8
       8
       +
       license: "ISC"

     

       9
       9
       +
       homepage: "https://tangled.org/@anil.recoil.org/ocaml-crockford"

     

       10
       10
       +
       bug-reports: "https://tangled.org/@anil.recoil.org/ocaml-crockford/issues"

     

       11
       11
       +
       depends: [

     

       12
       12
       +
         "dune" {>= "3.20"}

     

       13
       13
       +
         "ocaml" {>= "4.14.1"}

     

       14
       14
       +
         "odoc" {with-doc}

     

       15
       15
       +
         "alcotest" {with-test & >= "1.9.0"}

     

       16
       16
       +
         "cmdliner" {>= "1.1.0"}

     

       17
       17
       +
       ]

     

       18
       18
       +
       build: [

     

       19
       19
       +
         ["dune" "subst"] {dev}

     

       20
       20
       +
         [

     

       21
       21
       +
           "dune"

     

       22
       22
       +
           "build"

     

       23
       23
       +
           "-p"

     

       24
       24
       +
           name

     

       25
       25
       +
           "-j"

     

       26
       26
       +
           jobs

     

       27
       27
       +
           "@install"

     

       28
       28
       +
           "@runtest" {with-test}

     

       29
       29
       +
           "@doc" {with-doc}

     

       30
       30
       +
         ]

     

       31
       31
       +
       ]

     

       32
       32
       +
       x-maintenance-intent: ["(latest)"]

+26

dune-project

···

       1
       1
       +
       (lang dune 3.20)

     

       2
       2
       +
       

     

       3
       3
       +
       (name crockford)

     

       4
       4
       +
       

     

       5
       5
       +
       (generate_opam_files true)

     

       6
       6
       +
       

     

       7
       7
       +
       (license ISC)

     

       8
       8
       +
       (authors "Anil Madhavapeddy")

     

       9
       9
       +
       (homepage "https://tangled.org/@anil.recoil.org/ocaml-crockford")

     

       10
       10
       +
       (maintainers "Anil Madhavapeddy <anil@recoil.org>")

     

       11
       11
       +
       (bug_reports "https://tangled.org/@anil.recoil.org/ocaml-crockford/issues")

     

       12
       12
       +
       (maintenance_intent "(latest)")

     

       13
       13
       +
       

     

       14
       14
       +
       (package

     

       15
       15
       +
        (name crockford)

     

       16
       16
       +
        (synopsis "Crockford Base32 encoding for OCaml")

     

       17
       17
       +
        (description

     

       18
       18
       +
         "An OCaml implementation of Douglas Crockford's Base32 encoding with \

     

       19
       19
       +
          ISO 7064 checksum support. Provides encoding and decoding of int64 values \

     

       20
       20
       +
          to URI-friendly base32 strings, with optional checksum validation, padding, \

     

       21
       21
       +
          splitting, and random ID generation.")

     

       22
       22
       +
        (depends

     

       23
       23
       +
         (ocaml (>= 4.14.1))

     

       24
       24
       +
         (odoc :with-doc)

     

       25
       25
       +
         (alcotest (and :with-test (>= 1.9.0)))

     

       26
       26
       +
         (cmdliner (>= 1.1.0))))

+177

lib/crockford.ml

···

       1
       1
       +
       type invalid_length = { length: int; message: string }

     

       2
       2
       +
       type invalid_character = { char: char; message: string }

     

       3
       3
       +
       type invalid_checksum = { checksum: string; message: string }

     

       4
       4
       +
       type checksum_mismatch = { expected: int64; got: int64; identifier: string }

     

       5
       5
       +
       

     

       6
       6
       +
       type decode_error =

     

       7
       7
       +
         | Invalid_length of invalid_length

     

       8
       8
       +
         | Invalid_character of invalid_character

     

       9
       9
       +
         | Invalid_checksum of invalid_checksum

     

       10
       10
       +
         | Checksum_mismatch of checksum_mismatch

     

       11
       11
       +
       

     

       12
       12
       +
       exception Decode_error of decode_error

     

       13
       13
       +
       

     

       14
       14
       +
       let pp_invalid_length fmt { length; message } =

     

       15
       15
       +
         Format.fprintf fmt "Invalid_length: length=%d, %s" length message

     

       16
       16
       +
       

     

       17
       17
       +
       let pp_invalid_character fmt { char; message } =

     

       18
       18
       +
         Format.fprintf fmt "Invalid_character: char='%c', %s" char message

     

       19
       19
       +
       

     

       20
       20
       +
       let pp_invalid_checksum fmt { checksum; message } =

     

       21
       21
       +
         Format.fprintf fmt "Invalid_checksum: checksum=%s, %s" checksum message

     

       22
       22
       +
       

     

       23
       23
       +
       let pp_checksum_mismatch fmt { expected; got; identifier } =

     

       24
       24
       +
         Format.fprintf fmt "Checksum_mismatch: expected=%Ld, got=%Ld, identifier=%s"

     

       25
       25
       +
           expected got identifier

     

       26
       26
       +
       

     

       27
       27
       +
       let pp_decode_error fmt = function

     

       28
       28
       +
         | Invalid_length e -> pp_invalid_length fmt e

     

       29
       29
       +
         | Invalid_character e -> pp_invalid_character fmt e

     

       30
       30
       +
         | Invalid_checksum e -> pp_invalid_checksum fmt e

     

       31
       31
       +
         | Checksum_mismatch e -> pp_checksum_mismatch fmt e

     

       32
       32
       +
       

     

       33
       33
       +
       let encoding_chars = "0123456789abcdefghjkmnpqrstvwxyz"

     

       34
       34
       +
       

     

       35
       35
       +
       let generate_checksum number =

     

       36
       36
       +
         Int64.(sub (add (sub 97L (rem (mul 100L number) 97L)) 1L) 0L)

     

       37
       37
       +
       

     

       38
       38
       +
       let validate number ~checksum =

     

       39
       39
       +
         Int64.equal checksum (generate_checksum number)

     

       40
       40
       +
       

     

       41
       41
       +
       let normalize str =

     

       42
       42
       +
         let len = String.length str in

     

       43
       43
       +
         let buf = Bytes.create len in

     

       44
       44
       +
         let rec process i j =

     

       45
       45
       +
           if i >= len then Bytes.sub_string buf 0 j

     

       46
       46
       +
           else

     

       47
       47
       +
             let c = String.get str i in

     

       48
       48
       +
             let c_lower = Char.lowercase_ascii c in

     

       49
       49
       +
             match c_lower with

     

       50
       50
       +
             | '-' -> process (i + 1) j

     

       51
       51
       +
             | 'i' | 'l' -> Bytes.set buf j '1'; process (i + 1) (j + 1)

     

       52
       52
       +
             | 'o' -> Bytes.set buf j '0'; process (i + 1) (j + 1)

     

       53
       53
       +
             | _ -> Bytes.set buf j c_lower; process (i + 1) (j + 1)

     

       54
       54
       +
         in

     

       55
       55
       +
         process 0 0

     

       56
       56
       +
       

     

       57
       57
       +
       let encode ?(split_every=0) ?(min_length=0) ?(checksum=false) number =

     

       58
       58
       +
         let original_number = number in

     

       59
       59
       +
       

     

       60
       60
       +
         (* Build base32 encoding *)

     

       61
       61
       +
         let rec build_encoding acc n =

     

       62
       62
       +
           if Int64.equal n 0L then acc

     

       63
       63
       +
           else

     

       64
       64
       +
             let remainder = Int64.to_int (Int64.rem n 32L) in

     

       65
       65
       +
             let n' = Int64.div n 32L in

     

       66
       66
       +
             build_encoding (encoding_chars.[remainder] :: acc) n'

     

       67
       67
       +
         in

     

       68
       68
       +
       

     

       69
       69
       +
         let encoded_list =

     

       70
       70
       +
           if Int64.equal number 0L then ['0']

     

       71
       71
       +
           else build_encoding [] number

     

       72
       72
       +
         in

     

       73
       73
       +
       

     

       74
       74
       +
         let encoded_str = String.concat "" (List.map (String.make 1) encoded_list) in

     

       75
       75
       +
       

     

       76
       76
       +
         (* Adjust min_length if checksum is enabled *)

     

       77
       77
       +
         let adjusted_length =

     

       78
       78
       +
           if checksum && min_length > 2 then min_length - 2

     

       79
       79
       +
           else min_length

     

       80
       80
       +
         in

     

       81
       81
       +
       

     

       82
       82
       +
         (* Pad with zeros if needed *)

     

       83
       83
       +
         let padded =

     

       84
       84
       +
           if adjusted_length > 0 && String.length encoded_str < adjusted_length then

     

       85
       85
       +
             String.make (adjusted_length - String.length encoded_str) '0' ^ encoded_str

     

       86
       86
       +
           else

     

       87
       87
       +
             encoded_str

     

       88
       88
       +
         in

     

       89
       89
       +
       

     

       90
       90
       +
         (* Add checksum *)

     

       91
       91
       +
         let with_checksum =

     

       92
       92
       +
           if checksum then

     

       93
       93
       +
             let cs = generate_checksum original_number in

     

       94
       94
       +
             padded ^ Printf.sprintf "%02Ld" cs

     

       95
       95
       +
           else

     

       96
       96
       +
             padded

     

       97
       97
       +
         in

     

       98
       98
       +
       

     

       99
       99
       +
         (* Split if requested *)

     

       100
       100
       +
         if split_every > 0 then

     

       101
       101
       +
           let len = String.length with_checksum in

     

       102
       102
       +
           let num_splits = (len + split_every - 1) / split_every in

     

       103
       103
       +
           let splits = Array.make num_splits "" in

     

       104
       104
       +
           for i = 0 to num_splits - 1 do

     

       105
       105
       +
             let start = i * split_every in

     

       106
       106
       +
             let chunk_len = min split_every (len - start) in

     

       107
       107
       +
             splits.(i) <- String.sub with_checksum start chunk_len

     

       108
       108
       +
           done;

     

       109
       109
       +
           String.concat "-" (Array.to_list splits)

     

       110
       110
       +
         else

     

       111
       111
       +
           with_checksum

     

       112
       112
       +
       

     

       113
       113
       +
       let decode ?(checksum=false) str =

     

       114
       114
       +
         let encoded = normalize str in

     

       115
       115
       +
       

     

       116
       116
       +
         let (encoded_part, checksum_value) =

     

       117
       117
       +
           if checksum then begin

     

       118
       118
       +
             if String.length encoded < 3 then

     

       119
       119
       +
               raise (Decode_error (Invalid_checksum {

     

       120
       120
       +
                 checksum = encoded;

     

       121
       121
       +
                 message = "encoded string too short for checksum"

     

       122
       122
       +
               }));

     

       123
       123
       +
       

     

       124
       124
       +
             let cs_str = String.sub encoded (String.length encoded - 2) 2 in

     

       125
       125
       +
             let cs =

     

       126
       126
       +
               try Int64.of_string cs_str

     

       127
       127
       +
               with Failure _ ->

     

       128
       128
       +
                 raise (Decode_error (Invalid_checksum {

     

       129
       129
       +
                   checksum = cs_str;

     

       130
       130
       +
                   message = "invalid checksum format"

     

       131
       131
       +
                 }))

     

       132
       132
       +
             in

     

       133
       133
       +
             (String.sub encoded 0 (String.length encoded - 2), Some cs)

     

       134
       134
       +
           end else

     

       135
       135
       +
             (encoded, None)

     

       136
       136
       +
         in

     

       137
       137
       +
       

     

       138
       138
       +
         (* Decode base32 *)

     

       139
       139
       +
         let number = ref 0L in

     

       140
       140
       +
         String.iter (fun c ->

     

       141
       141
       +
           number := Int64.mul !number 32L;

     

       142
       142
       +
           match String.index_opt encoding_chars c with

     

       143
       143
       +
           | Some pos -> number := Int64.add !number (Int64.of_int pos)

     

       144
       144
       +
           | None ->

     

       145
       145
       +
               raise (Decode_error (Invalid_character {

     

       146
       146
       +
                 char = c;

     

       147
       147
       +
                 message = Printf.sprintf "character '%c' not in base32 alphabet" c

     

       148
       148
       +
               }))

     

       149
       149
       +
         ) encoded_part;

     

       150
       150
       +
       

     

       151
       151
       +
         (* Validate checksum if present *)

     

       152
       152
       +
         (match checksum_value with

     

       153
       153
       +
         | Some cs ->

     

       154
       154
       +
             if not (validate !number ~checksum:cs) then

     

       155
       155
       +
               raise (Decode_error (Checksum_mismatch {

     

       156
       156
       +
                 expected = generate_checksum !number;

     

       157
       157
       +
                 got = cs;

     

       158
       158
       +
                 identifier = str

     

       159
       159
       +
               }))

     

       160
       160
       +
         | None -> ());

     

       161
       161
       +
       

     

       162
       162
       +
         !number

     

       163
       163
       +
       

     

       164
       164
       +
       let generate ~length ?(split_every=0) ?(checksum=false) () =

     

       165
       165
       +
         if checksum && length < 3 then

     

       166
       166
       +
           raise (Decode_error (Invalid_length {

     

       167
       167
       +
             length;

     

       168
       168
       +
             message = "length must be >= 3 if checksum is enabled"

     

       169
       169
       +
           }));

     

       170
       170
       +
       

     

       171
       171
       +
         let adjusted_length = if checksum then length - 2 else length in

     

       172
       172
       +
       

     

       173
       173
       +
         (* Generate random number between 0 and 32^length *)

     

       174
       174
       +
         let max_val = 32.0 ** float_of_int adjusted_length in

     

       175
       175
       +
         let random_num = Int64.of_float (Random.float max_val) in

     

       176
       176
       +
       

     

       177
       177
       +
         encode ~split_every ~min_length:adjusted_length ~checksum random_num

+89

lib/crockford.mli

···

       1
       1
       +
       (** Crockford Base32 encoding for OCaml *)

     

       2
       2
       +
       

     

       3
       3
       +
       (** {1 Error Types} *)

     

       4
       4
       +
       

     

       5
       5
       +
       type invalid_length = { length: int; message: string }

     

       6
       6
       +
       (** Error for invalid length parameters *)

     

       7
       7
       +
       

     

       8
       8
       +
       type invalid_character = { char: char; message: string }

     

       9
       9
       +
       (** Error for invalid characters during decoding *)

     

       10
       10
       +
       

     

       11
       11
       +
       type invalid_checksum = { checksum: string; message: string }

     

       12
       12
       +
       (** Error for invalid checksum format *)

     

       13
       13
       +
       

     

       14
       14
       +
       type checksum_mismatch = { expected: int64; got: int64; identifier: string }

     

       15
       15
       +
       (** Error for checksum validation failures *)

     

       16
       16
       +
       

     

       17
       17
       +
       type decode_error =

     

       18
       18
       +
         | Invalid_length of invalid_length

     

       19
       19
       +
         | Invalid_character of invalid_character

     

       20
       20
       +
         | Invalid_checksum of invalid_checksum

     

       21
       21
       +
         | Checksum_mismatch of checksum_mismatch

     

       22
       22
       +
       (** Union of all possible decode errors *)

     

       23
       23
       +
       

     

       24
       24
       +
       exception Decode_error of decode_error

     

       25
       25
       +
       (** Main exception raised for all decoding errors *)

     

       26
       26
       +
       

     

       27
       27
       +
       val pp_invalid_length : Format.formatter -> invalid_length -> unit

     

       28
       28
       +
       (** Pretty-print an invalid_length error *)

     

       29
       29
       +
       

     

       30
       30
       +
       val pp_invalid_character : Format.formatter -> invalid_character -> unit

     

       31
       31
       +
       (** Pretty-print an invalid_character error *)

     

       32
       32
       +
       

     

       33
       33
       +
       val pp_invalid_checksum : Format.formatter -> invalid_checksum -> unit

     

       34
       34
       +
       (** Pretty-print an invalid_checksum error *)

     

       35
       35
       +
       

     

       36
       36
       +
       val pp_checksum_mismatch : Format.formatter -> checksum_mismatch -> unit

     

       37
       37
       +
       (** Pretty-print a checksum_mismatch error *)

     

       38
       38
       +
       

     

       39
       39
       +
       val pp_decode_error : Format.formatter -> decode_error -> unit

     

       40
       40
       +
       (** Pretty-print a decode_error *)

     

       41
       41
       +
       

     

       42
       42
       +
       (** {1 Constants} *)

     

       43
       43
       +
       

     

       44
       44
       +
       val encoding_chars : string

     

       45
       45
       +
       (** The Crockford base32 encoding alphabet (excludes i, l, o, u) *)

     

       46
       46
       +
       

     

       47
       47
       +
       (** {1 Encoding and Decoding} *)

     

       48
       48
       +
       

     

       49
       49
       +
       val encode :

     

       50
       50
       +
         ?split_every:int ->

     

       51
       51
       +
         ?min_length:int ->

     

       52
       52
       +
         ?checksum:bool ->

     

       53
       53
       +
         int64 -> string

     

       54
       54
       +
       (** [encode ?split_every ?min_length ?checksum n] encodes an int64 to a Crockford base32 string.

     

       55
       55
       +
           @param split_every Split the output with '-' every n characters (default: no splitting)

     

       56
       56
       +
           @param min_length Pad with zeros to this minimum length (default: no padding)

     

       57
       57
       +
           @param checksum Append ISO 7064 checksum as 2 digits (default: false) *)

     

       58
       58
       +
       

     

       59
       59
       +
       val decode : ?checksum:bool -> string -> int64

     

       60
       60
       +
       (** [decode ?checksum str] decodes a Crockford base32 string to int64.

     

       61
       61
       +
           @param checksum Expect and validate ISO 7064 checksum (default: false)

     

       62
       62
       +
           @raise Decode_error if decoding fails (invalid characters, invalid checksum format, or checksum mismatch) *)

     

       63
       63
       +
       

     

       64
       64
       +
       (** {1 ID Generation} *)

     

       65
       65
       +
       

     

       66
       66
       +
       val generate :

     

       67
       67
       +
         length:int ->

     

       68
       68
       +
         ?split_every:int ->

     

       69
       69
       +
         ?checksum:bool ->

     

       70
       70
       +
         unit -> string

     

       71
       71
       +
       (** [generate ~length ?split_every ?checksum ()] generates a random Crockford base32 string.

     

       72
       72
       +
           @param length The length of the generated string (excluding checksum)

     

       73
       73
       +
           @param split_every Split the output with '-' every n characters (default: no splitting)

     

       74
       74
       +
           @param checksum Append ISO 7064 checksum as 2 digits (default: false)

     

       75
       75
       +
           @raise Decode_error if checksum is true and length < 3

     

       76
       76
       +
       

     

       77
       77
       +
           Note: Caller must initialize Random module with {!Random.self_init} before use *)

     

       78
       78
       +
       

     

       79
       79
       +
       (** {1 Utility Functions} *)

     

       80
       80
       +
       

     

       81
       81
       +
       val normalize : string -> string

     

       82
       82
       +
       (** [normalize str] normalizes a string for decoding by converting to lowercase,

     

       83
       83
       +
           removing dashes, and mapping confusable characters (i→1, l→1, o→0) *)

     

       84
       84
       +
       

     

       85
       85
       +
       val validate : int64 -> checksum:int64 -> bool

     

       86
       86
       +
       (** [validate n ~checksum] validates that a checksum matches the number *)

     

       87
       87
       +
       

     

       88
       88
       +
       val generate_checksum : int64 -> int64

     

       89
       89
       +
       (** [generate_checksum n] generates an ISO 7064 (mod 97-10) checksum for a number *)

lib/dune

···

       1
       1
       +
       (library

     

       2
       2
       +
        (name crockford)

     

       3
       3
       +
        (public_name crockford))

test/dune

···

       1
       1
       +
       (test

     

       2
       2
       +
        (name test_crockford)

     

       3
       3
       +
        (libraries crockford alcotest))

+211

test/test_crockford.ml

···

       1
       1
       +
       (* Test suite using Alcotest - ported from crockford_test.go *)

     

       2
       2
       +
       

     

       3
       3
       +
       (* Encode tests *)

     

       4
       4
       +
       let test_encode () =

     

       5
       5
       +
         let test_cases = [

     

       6
       6
       +
           (0L, 0, 0, false, "0");

     

       7
       7
       +
           (1234L, 0, 0, false, "16j");

     

       8
       8
       +
           (1234L, 2, 0, false, "16-j");

     

       9
       9
       +
           (1234L, 2, 4, false, "01-6j");

     

       10
       10
       +
           (538751765283013L, 5, 10, false, "f9zqn-sf065");

     

       11
       11
       +
           (736381604818L, 5, 10, true, "ndsw7-4yj20");

     

       12
       12
       +
           (258706475165200172L, 7, 14, true, "75rw5cg-n1bsc64");

     

       13
       13
       +
           (161006169L, 4, 8, true, "4shg-js75");

     

       14
       14
       +
         ] in

     

       15
       15
       +
         List.iter (fun (input, split_every, length, checksum, expected) ->

     

       16
       16
       +
           let result = Crockford.encode ~split_every ~min_length:length ~checksum input in

     

       17
       17
       +
           let test_name = Printf.sprintf "encode %Ld (split=%d, len=%d, checksum=%b)" input split_every length checksum in

     

       18
       18
       +
           Alcotest.(check string) test_name expected result

     

       19
       19
       +
         ) test_cases

     

       20
       20
       +
       

     

       21
       21
       +
       (* Generate tests *)

     

       22
       22
       +
       let test_generate () =

     

       23
       23
       +
         Random.self_init ();

     

       24
       24
       +
       

     

       25
       25
       +
         let test_cases = [

     

       26
       26
       +
           (4, 0, false);

     

       27
       27
       +
           (10, 5, false);

     

       28
       28
       +
           (10, 5, true);

     

       29
       29
       +
         ] in

     

       30
       30
       +
         List.iter (fun (length, split_every, checksum) ->

     

       31
       31
       +
           let result = Crockford.generate ~length ~split_every ~checksum () in

     

       32
       32
       +
           let expected_length =

     

       33
       33
       +
             if split_every > 0 then

     

       34
       34
       +
               length + (length / split_every) - 1

     

       35
       35
       +
             else

     

       36
       36
       +
               length

     

       37
       37
       +
           in

     

       38
       38
       +
           let test_name = Printf.sprintf "generate length=%d split=%d checksum=%b" length split_every checksum in

     

       39
       39
       +
           Alcotest.(check int) test_name expected_length (String.length result)

     

       40
       40
       +
         ) test_cases

     

       41
       41
       +
       

     

       42
       42
       +
       (* Decode tests *)

     

       43
       43
       +
       let test_decode () =

     

       44
       44
       +
         let test_cases = [

     

       45
       45
       +
           ("0", false, Some 0L);

     

       46
       46
       +
           ("16j", false, Some 1234L);

     

       47
       47
       +
           ("16-j", false, Some 1234L);

     

       48
       48
       +
           ("01-6j", false, Some 1234L);

     

       49
       49
       +
           ("f9zqn-sf065", false, Some 538751765283013L);

     

       50
       50
       +
           ("twwjw-1ww98", true, Some 924377286556L);

     

       51
       51
       +
           ("9ed5m-ytn", false, Some 324712168277L);

     

       52
       52
       +
           ("9ed5m-ytn30", true, Some 324712168277L);

     

       53
       53
       +
           ("elife.01567", false, None); (* Should fail - contains invalid character '.' *)

     

       54
       54
       +
         ] in

     

       55
       55
       +
         List.iter (fun (input, checksum, expected) ->

     

       56
       56
       +
           let test_name = Printf.sprintf "decode '%s' (checksum=%b)" input checksum in

     

       57
       57
       +
           match expected with

     

       58
       58
       +
           | Some want ->

     

       59
       59
       +
               let got = Crockford.decode ~checksum input in

     

       60
       60
       +
               Alcotest.(check int64) test_name want got

     

       61
       61
       +
           | None ->

     

       62
       62
       +
               (* Expected to fail *)

     

       63
       63
       +
               Alcotest.check_raises

     

       64
       64
       +
                 test_name

     

       65
       65
       +
                 (Crockford.Decode_error (Crockford.Invalid_character {

     

       66
       66
       +
                   char = '.';

     

       67
       67
       +
                   message = "character '.' not in base32 alphabet"

     

       68
       68
       +
                 }))

     

       69
       69
       +
                 (fun () -> ignore (Crockford.decode ~checksum input))

     

       70
       70
       +
         ) test_cases

     

       71
       71
       +
       

     

       72
       72
       +
       (* Normalize tests *)

     

       73
       73
       +
       let test_normalize () =

     

       74
       74
       +
         let test_cases = [

     

       75
       75
       +
           ("f9ZQNSF065", "f9zqnsf065");

     

       76
       76
       +
           ("f9zqn-sf065", "f9zqnsf065");

     

       77
       77
       +
           ("f9Llio", "f91110");

     

       78
       78
       +
         ] in

     

       79
       79
       +
         List.iter (fun (input, expected) ->

     

       80
       80
       +
           let result = Crockford.normalize input in

     

       81
       81
       +
           let test_name = Printf.sprintf "normalize '%s'" input in

     

       82
       82
       +
           Alcotest.(check string) test_name expected result

     

       83
       83
       +
         ) test_cases

     

       84
       84
       +
       

     

       85
       85
       +
       (* GenerateChecksum tests *)

     

       86
       86
       +
       let test_generate_checksum () =

     

       87
       87
       +
         let test_cases = [

     

       88
       88
       +
           (450320459383L, 85L);

     

       89
       89
       +
           (123456789012L, 44L);

     

       90
       90
       +
         ] in

     

       91
       91
       +
         List.iter (fun (input, expected) ->

     

       92
       92
       +
           let result = Crockford.generate_checksum input in

     

       93
       93
       +
           let test_name = Printf.sprintf "generate_checksum %Ld" input in

     

       94
       94
       +
           Alcotest.(check int64) test_name expected result

     

       95
       95
       +
         ) test_cases

     

       96
       96
       +
       

     

       97
       97
       +
       (* Validate tests *)

     

       98
       98
       +
       let test_validate () =

     

       99
       99
       +
         let test_cases = [

     

       100
       100
       +
           (375301249367L, 92L, true);

     

       101
       101
       +
           (930412369850L, 36L, true);

     

       102
       102
       +
         ] in

     

       103
       103
       +
         List.iter (fun (input, checksum, expected) ->

     

       104
       104
       +
           let result = Crockford.validate input ~checksum in

     

       105
       105
       +
           let test_name = Printf.sprintf "validate %Ld checksum=%Ld" input checksum in

     

       106
       106
       +
           Alcotest.(check bool) test_name expected result

     

       107
       107
       +
         ) test_cases

     

       108
       108
       +
       

     

       109
       109
       +
       (* Additional roundtrip tests *)

     

       110
       110
       +
       let test_roundtrip () =

     

       111
       111
       +
         let test_numbers = [

     

       112
       112
       +
           0L;

     

       113
       113
       +
           1L;

     

       114
       114
       +
           32L;

     

       115
       115
       +
           1024L;

     

       116
       116
       +
           1234567890L;

     

       117
       117
       +
           Int64.max_int;

     

       118
       118
       +
         ] in

     

       119
       119
       +
       

     

       120
       120
       +
         List.iter (fun num ->

     

       121
       121
       +
           let encoded = Crockford.encode num in

     

       122
       122
       +
           let decoded = Crockford.decode encoded in

     

       123
       123
       +
           Alcotest.(check int64) (Printf.sprintf "roundtrip %Ld" num) num decoded

     

       124
       124
       +
         ) test_numbers

     

       125
       125
       +
       

     

       126
       126
       +
       let test_roundtrip_with_checksum () =

     

       127
       127
       +
         let test_numbers = [

     

       128
       128
       +
           0L;

     

       129
       129
       +
           1L;

     

       130
       130
       +
           32L;

     

       131
       131
       +
           1024L;

     

       132
       132
       +
           1234567890L;

     

       133
       133
       +
         ] in

     

       134
       134
       +
       

     

       135
       135
       +
         List.iter (fun num ->

     

       136
       136
       +
           let encoded = Crockford.encode ~checksum:true num in

     

       137
       137
       +
           let decoded = Crockford.decode ~checksum:true encoded in

     

       138
       138
       +
           Alcotest.(check int64) (Printf.sprintf "roundtrip with checksum %Ld" num) num decoded

     

       139
       139
       +
         ) test_numbers

     

       140
       140
       +
       

     

       141
       141
       +
       (* Error handling tests *)

     

       142
       142
       +
       let test_error_invalid_character () =

     

       143
       143
       +
         Alcotest.check_raises

     

       144
       144
       +
           "invalid character"

     

       145
       145
       +
           (Crockford.Decode_error (Crockford.Invalid_character {

     

       146
       146
       +
             char = '#';

     

       147
       147
       +
             message = "character '#' not in base32 alphabet"

     

       148
       148
       +
           }))

     

       149
       149
       +
           (fun () -> ignore (Crockford.decode "abc#def"))

     

       150
       150
       +
       

     

       151
       151
       +
       let test_error_invalid_checksum () =

     

       152
       152
       +
         Alcotest.check_raises

     

       153
       153
       +
           "invalid checksum length"

     

       154
       154
       +
           (Crockford.Decode_error (Crockford.Invalid_checksum {

     

       155
       155
       +
             checksum = "ab";

     

       156
       156
       +
             message = "encoded string too short for checksum"

     

       157
       157
       +
           }))

     

       158
       158
       +
           (fun () -> ignore (Crockford.decode ~checksum:true "ab"))

     

       159
       159
       +
       

     

       160
       160
       +
       let test_error_checksum_mismatch () =

     

       161
       161
       +
         let encoded = Crockford.encode ~checksum:true 1234L in

     

       162
       162
       +
         let corrupted = String.sub encoded 0 (String.length encoded - 2) ^ "00" in

     

       163
       163
       +
       

     

       164
       164
       +
         Alcotest.check_raises

     

       165
       165
       +
           "checksum mismatch"

     

       166
       166
       +
           (Crockford.Decode_error (Crockford.Checksum_mismatch {

     

       167
       167
       +
             expected = Crockford.generate_checksum 1234L;

     

       168
       168
       +
             got = 0L;

     

       169
       169
       +
             identifier = corrupted

     

       170
       170
       +
           }))

     

       171
       171
       +
           (fun () -> ignore (Crockford.decode ~checksum:true corrupted))

     

       172
       172
       +
       

     

       173
       173
       +
       let test_error_invalid_length () =

     

       174
       174
       +
         Alcotest.check_raises

     

       175
       175
       +
           "invalid length for generate"

     

       176
       176
       +
           (Crockford.Decode_error (Crockford.Invalid_length {

     

       177
       177
       +
             length = 2;

     

       178
       178
       +
             message = "length must be >= 3 if checksum is enabled"

     

       179
       179
       +
           }))

     

       180
       180
       +
           (fun () -> ignore (Crockford.generate ~length:2 ~checksum:true ()))

     

       181
       181
       +
       

     

       182
       182
       +
       let () =

     

       183
       183
       +
         let open Alcotest in

     

       184
       184
       +
         run "Crockford" [

     

       185
       185
       +
           "encoding", [

     

       186
       186
       +
             test_case "encode" `Quick test_encode;

     

       187
       187
       +
           ];

     

       188
       188
       +
           "decoding", [

     

       189
       189
       +
             test_case "decode" `Quick test_decode;

     

       190
       190
       +
           ];

     

       191
       191
       +
           "normalization", [

     

       192
       192
       +
             test_case "normalize" `Quick test_normalize;

     

       193
       193
       +
           ];

     

       194
       194
       +
           "checksum", [

     

       195
       195
       +
             test_case "generate_checksum" `Quick test_generate_checksum;

     

       196
       196
       +
             test_case "validate" `Quick test_validate;

     

       197
       197
       +
           ];

     

       198
       198
       +
           "generation", [

     

       199
       199
       +
             test_case "generate" `Quick test_generate;

     

       200
       200
       +
           ];

     

       201
       201
       +
           "roundtrip", [

     

       202
       202
       +
             test_case "roundtrip encoding/decoding" `Quick test_roundtrip;

     

       203
       203
       +
             test_case "roundtrip with checksum" `Quick test_roundtrip_with_checksum;

     

       204
       204
       +
           ];

     

       205
       205
       +
           "errors", [

     

       206
       206
       +
             test_case "invalid character" `Quick test_error_invalid_character;

     

       207
       207
       +
             test_case "invalid checksum" `Quick test_error_invalid_checksum;

     

       208
       208
       +
             test_case "checksum mismatch" `Quick test_error_checksum_mismatch;

     

       209
       209
       +
             test_case "invalid length" `Quick test_error_invalid_length;

     

       210
       210
       +
           ];

     

       211
       211
       +
         ]