Noid - routines to mint and manage nice opaque identifiers
use Noid; # import routines into a Perl script $dbreport = Noid::dbcreate( # create minter database & printable $dbdir, $contact, # report on its properties; $contact $template, $term, # is string identifying the operator $naan, $naa, # (authentication information); the $subnaa ); # report is printable $noid = Noid::dbopen( $dbname, $flags ); # open a minter, optionally $flags = 0 | DB_RDONLY; # in read only mode Noid::mint( $noid, $contact, $pepper ); # generate an identifier Noid::dbclose( $noid ); # close minter when done Noid::checkchar( $id ); # if id ends in +, replace with new check # char and return full id, else return id # if current check char valid, else return # 'undef' Noid::validate( $noid, # check that ids conform to template ("-" $template, # means use minter's template); returns @ids ); # array of corresponding strings, errors # beginning with "iderr:" $n = Noid::bind( $noid, $contact, # bind data to identifier; set $validate, $how, # $validate to 0 if id. doesn't $id, $elem, $value ); # need to conform to a template Noid::note( $noid, $contact, $key, $value ); # add an internal note Noid::fetch( $noid, $verbose, # fetch bound data; set $verbose $id, @elems ); # to 1 to return labels print Noid::dbinfo( $noid, # get minter information; level $level ); # brief (default), full, or dump Noid::getnoid( $noid, $varname ); # get arbitrary named internal # variable Noid::hold( $noid, $contact, # place or release hold; return $on_off, @ids ); # 1 on success, 0 on error Noid::hold_set( $noid, $id ); Noid::hold_release( $noid, $id ); Noid::parse_template( $template, # read template for errors, returning $prefix, $mask, # namespace size (NOLIMIT=unbounded) $gen_type, # or 0 on error; $message, $gen_type, $message ); # $prefix, & $mask are output params Noid::queue( $noid, $contact, # return strings for queue attempts $when, @ids ); # (failures start "error:") Noid::n2xdig( $num, $mask ); # show identifier matching ord. $num Noid::sample( $noid, $num ); # show random ident. less than $num Noid::scope( $noid ); # show range of ids inside the minter print Noid::errmsg( $noid, $reset ); # print message from failed call $reset = undef | 1; # use 1 to clear error message buffer Noid::addmsg( $noid, $message ); # add message to error message buffer Noid::logmsg( $noid, $message ); # write message to minter log
This is very brief documentation for the Noid Perl module subroutines. For this early version of the software, it is indispensable to have the documentation for the noid utility (the primary user of these routines) at hand. Typically that can be viewed with
while the present document can be viewed with
The noid utility creates minters (identifier generators) and accepts commands that operate them. Once created, a minter can be used to produce persistent, globally unique names for documents, databases, images, vocabulary terms, etc. Properly managed, these identifiers can be used as long term durable information object references within naming schemes such as ARK, PURL, URN, DOI, and LSID. At the same time, alternative minters can be set up to produce short-lived names for transaction identifiers, compact web server session keys (cf. UUIDs), and other ephemera.
In general, a noid minter efficiently generates, tracks, and binds unique identifiers, which are produced without replacement in random or sequential order, and with or without a check character that can be used for detecting transcription errors. A minter can bind identifiers to arbitrary element names and element values that are either stored or produced upon retrieval from rule-based transformations of requested identifiers; the latter has application in identifier resolution. Noid minters are very fast, scalable, easy to create and tear down, and have a relatively small footprint. They use BerkeleyDB as the underlying database.
Identifiers generated by a noid minter are also known as "noids" (nice opaque identifiers). While a minter can record and bind any identifiers that you bring to its attention, often it is used to generate, bringing to your attention, identifier strings that carry no widely recognizable meaning. This semantic opaqueness reduces their vulnerability to era- and language-specific change, and helps persistence by making for identifiers that can age and travel well.