The cl-mongo-id Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The cl-mongo-id Reference Manual

This is the cl-mongo-id Reference Manual, version 0.1.0, generated automatically by Declt version 2.4 "Will Decker" on Wed Jun 20 11:15:27 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

cl-mongo-id

This is a simple library for creating/handling MongoDB's ObjectIDs. It works by grabbing key pieces of info (unix timestamp, hostname, process pid, global "inc" value) and creating a new ObjectID as a 12-byte array #(79 151 129 ...)

It aims to be as cross-platform/implementation as possible. If you find you're unable to run it on your specific platform, please let me know and I'll do whatever I can to fix it!

Usage

Install

(ql:quickload :cl-mongo-id)

Create byte array from string id:

(mongoid:oid "4f9638d834322b9531000005")  ->
    #(79 150 56 216 52 50 43 149 49 0 0 5)

Create new id using MongoDB ObjectID specification:

(mongoid:oid)  ->
    #(79 150 62 92 61 196 44 20 228 0 0 0)

Grab a string representation of an ObjectID:

(mongoid:oid-str (mongoid:oid))  ->
    "4F97001C3DC42C14E4000050"

Usage with cl-mongo

The cl-mongo-id library can be used with cl-mongo. There is just one caveat: You must import the make-bson-oid function from the cl-mongo package before you can use the two together.

(import 'cl-mongo::make-bson-oid)

(with-mongo-connection (:host "127.0.0.1" :db "test")
  ;; querying a document of a known id
  (db.find "mycoll" (kv "_id" (make-bson-oid :oid (mongoid:oid "4f9638d834322b9531000005"))))

  ;; creating a new document with an oid
  (let ((doc (make-document :oid (make-bson-oid :oid (mongoid:oid)))))
    (db.save "mycoll" doc)))

Thread safe

cl-mongo-id is built to be thread-safe (specifically the inc value). This means you can create ID's via (oid) from several different threads without problems, and your inc value will be unique between all of them.

Helper functions

cl-mongo-id has some helper functions that may be useful to you for either debugging or grabbing values from your IDs.

Note that all of the following helper functions take a keyword argument :bytes, which if set to T will return the raw bytes of that portion of the ID and not convert them to an integer.

get-timestamp

Get the unix timestamp from a Mongo Object ID:

(mongoid:get-timestamp (oid "4f96f9fa3dc42c14e400004e"))  ->
    1335294458

get-pid

Get the PID the ID was created under:

(mongoid:get-pid (oid "4f96f9fa3dc42c14e400004e"))  ->
    5348

get-hostname

Get the int value corresponding to the first three bytes of the MD5 of the hostname the ID was created on:

(mongoid:get-hostname (oid "4f96f9fa3dc42c14e400004e"))  ->
    4047916
(mongoid:get-hostname (oid "4f96f9fa3dc42c14e400004e") :bytes t)  ->
    #(61 196 44)

get-inc

Get the ID's "inc" value:

(mongoid:get-inc (oid "4f96f9fa3dc42c14e400004e"))  ->
    78

Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 cl-mongo-id

Author

Andrew Lyon <orthecreedence@gmail.com>

License

MIT

Description

A library for the creation/parsing of MongoDB Object IDs

Version

0.1.0

Dependencies
Source

cl-mongo-id.asd (file)

Component

mongo-id.lisp (file)


Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 cl-mongo-id.asd

Location

cl-mongo-id.asd

Systems

cl-mongo-id (system)


Previous: , Up: Lisp files   [Contents][Index]

3.1.2 cl-mongo-id/mongo-id.lisp

Parent

cl-mongo-id (system)

Location

mongo-id.lisp

Packages

cl-mongo-id

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 cl-mongo-id

Source

mongo-id.lisp (file)

Nickname

mongoid

Use List

common-lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: get-hostname OID &key BYTES

Grab the hostname int out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the hostname part of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-inc OID &key BYTES

Grab the inc value out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the inc value of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-pid OID &key BYTES

Grab the pid out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the PID part of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-timestamp OID &key BYTES

Grab the timestamp out of a vector oid. Passing :bytes t will return an array of bytes corresponding to the timestamp part of the ID instead of parsing it as an integer.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: oid &optional ID

Generate a mongo id, in byte vector format.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: oid-str OID

Given a vector ID, convert it to a string.

Package

cl-mongo-id

Source

mongo-id.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Special variables

Special Variable: *id-inc*
Package

cl-mongo-id

Source

mongo-id.lisp (file)

Special Variable: *id-inc-lock*
Package

cl-mongo-id

Source

mongo-id.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

5.2.2 Functions

Function: convert-hex-vector HEX-STRING

Takes a hex string, IE 4f2b8096 and converts it into a byte array: 4f2b8096 -> #(79 43 128 150)
Hex string *must* have even number of bytes.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: convert-vector-int VECTOR

Convert a byte array to an integer: #(79 150 243 81) -> 1335292753

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: create-new-id ()

Create a brand-spankin-new ObjectId using the current timestamp/inc values, along with hostname and process pid.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-current-hostname ()

Get hostname of machine.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-current-pid &key IF-NOT-EXISTS-RETURN

Get the current process’ PID. This function does it’s best to be cross- implementation. If it isn’t able to grab the PID from the system, it defaults to returning whatever value is passed into the :if-not-exists-return key.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-current-timestamp ()

Get current unix timestamp.

Package

cl-mongo-id

Source

mongo-id.lisp (file)

Function: get-inc-val ()

Thread-safe method to get current ObjectId inc value. Takes an optional timestamp value to calculate inc for.

Package

cl-mongo-id

Source

mongo-id.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L  
Index Entry  Section

C
cl-mongo-id.asd: The cl-mongo-id<dot>asd file
cl-mongo-id/mongo-id.lisp: The cl-mongo-id/mongo-id<dot>lisp file

F
File, Lisp, cl-mongo-id.asd: The cl-mongo-id<dot>asd file
File, Lisp, cl-mongo-id/mongo-id.lisp: The cl-mongo-id/mongo-id<dot>lisp file

L
Lisp File, cl-mongo-id.asd: The cl-mongo-id<dot>asd file
Lisp File, cl-mongo-id/mongo-id.lisp: The cl-mongo-id/mongo-id<dot>lisp file

Jump to:   C   F   L  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   C   F   G   O  
Index Entry  Section

C
convert-hex-vector: Internal functions
convert-vector-int: Internal functions
create-new-id: Internal functions

F
Function, convert-hex-vector: Internal functions
Function, convert-vector-int: Internal functions
Function, create-new-id: Internal functions
Function, get-current-hostname: Internal functions
Function, get-current-pid: Internal functions
Function, get-current-timestamp: Internal functions
Function, get-hostname: Exported functions
Function, get-inc: Exported functions
Function, get-inc-val: Internal functions
Function, get-pid: Exported functions
Function, get-timestamp: Exported functions
Function, oid: Exported functions
Function, oid-str: Exported functions

G
get-current-hostname: Internal functions
get-current-pid: Internal functions
get-current-timestamp: Internal functions
get-hostname: Exported functions
get-inc: Exported functions
get-inc-val: Internal functions
get-pid: Exported functions
get-timestamp: Exported functions

O
oid: Exported functions
oid-str: Exported functions

Jump to:   C   F   G   O  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*id-inc*: Internal special variables
*id-inc-lock*: Internal special variables

S
Special Variable, *id-inc*: Internal special variables
Special Variable, *id-inc-lock*: Internal special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   P   S  
Index Entry  Section

C
cl-mongo-id: The cl-mongo-id system
cl-mongo-id: The cl-mongo-id package

P
Package, cl-mongo-id: The cl-mongo-id package

S
System, cl-mongo-id: The cl-mongo-id system

Jump to:   C   P   S