package require logbookadmin
createLogBook path experiment spokesperson purpose ?select?
currentLogBook
setCurrentLogBook path
currentLogBookOrError
addPerson lastName firstName ?salutation?
listPeople
createShift name members
addMembersToShift shiftName members
removeMemberFromShift shiftName member
setCurrentShift shiftName
listShiftMembers shiftName
listShifts
currentShift
beginRun number title ?remark?
endRun ?remark?
pauseRun ?remark?
resumeRun ?remark?
emergencyEndRun ?remark?
listRuns
currentRun
findRun number
getNote id
getNoteText note
getNoteTitle ?note?
listAllNotes
listNotesForRun number
listNonRunNotes
kvExists key
kvGet key
kvSet key value
kvCreate key value
Using the low level logbook Tcl bindings can be painful because of the need to track the creation of instance commands and to ensure they get destroyed when on longer needed. At the cost of making many more transient objects than otherwise required, the logbookadmin package provides a much easier to use interface to the logbook API.
One of the features of logbookadmin, is that it adds the concept of a current logbook to the API. The current logbook is the one that all commands will operate on, other than commands that can modify the current logbook.
A feature of the logbookadmin API is that rather than returning command ensemble objects for complex objects, instead it returns dicts for them. See DICTIONARIES for a description of these dicts and their keys.
The logbookadmin interface is procedural. The interface, therefore appears as simple commands.
createLogBook path experiment spokesperson purpose ?select?
Creates a new logbook with the experiment
identifier, spokesperson and
purpose requested in the new database
file named path. If select
is provided and evaluates to a boolean true, the logbook
is made current and all other operations that don't specify
a logbook will operate on this logbook.
If not suppled, select defaults to a
boolean false value.
currentLogBook
If a current logbook has been established, the path to it is returned. If there is no current logbook, an empty string is returned. See, however currentLogBookOrError below.
setCurrentLogBook path
Sets the current logbook to be path.
Note that this does not validate the file as a logbook.
That's done on the first access.
currentLogBookOrError
Returns the path to the current logbook. If no logbook has been established as current, the command throws an error. This is most commonly used internally as well to obtain the logbook to operate on.
addPerson lastName firstName ?salutation?
Adds a new person to the current logbook whose
last name and first name are lastName
and firstName respectively. If
the optional salutation is provided it is
the salutation associated with the person. If not, then
the person is associated with a saluation that is an empty string.
listPeople
Returns a list containing person dictionaries. Each entry describes one person in the logbook and altogether all people registered in the logbook are returned. The dicts returned are descriged in DICTIONARIES
createShift name members
Creates a new shift. The shift will be named
name and initially have
members as its members.
The members list is a list of person
primary keys (ids). These can be gotten from person dicts.
To create an empty shift simply supply
[list] as the
members parameter to provide an
emptylist.
Once created, addMembersToShift and removeMemberFromShift can be used to edit the shift membership. Remember that shifts, not their members are associated with run state changes so the shift members should remain constant once data taking has begun.
addMembersToShift shiftName members
Adds new
members
to the shift named shiftName.
The members parameter is a list of
person ids (primary keys). The id of a person can be gotten
from its dict. representation.
removeMemberFromShift shiftName member
Removes the person whose primary key ismember
from the shift named shiftName.
setCurrentShift shiftName
The logbook has the concept of a current shift. This shift is
associated with all run state transitions and is intended to
describe who is on-duty during a segment of data taking. This
command sets the current shift to the shift named
shiftName.
listShiftMembers shiftName
Returns person dicts for all of the members of the shift
named shiftName
listShifts
Returns a list whose members are the names of all of the shifts defined to the logbook.
currentShift
If a current shift has been established, returns the name of that shift. If there is no current shift, an empty string is returned.
beginRun number title ?remark?
Creates a new run with run number and title
given by number and title
respectively and logs a BEGIN state transition
immediately. If remark is provided
it is a remark that is associated with the transition.
Note that for this to work a current shift must also have been established
and there cannot be another run with the same
number.
This command also establishes a current run. All future state transitions operate on that run until the run has ended at which point there is no longer a current run and state transitions other than those initiated by beginRun fail.
endRun ?remark?
Ends the current run by logging an END
state transition for it and indicating there is no current run.
If provided remark is a textual remark that
is associated with the transition.
pauseRun ?remark?
Pauses the current run by logging a PAUSE
transition for it. The current run remains the current run.
If provided remark is a textual comment
associated with the transition.
resumeRun ?remark?
Resumes a paused current run by logging a RESUME
transition. remark
if provided is a text comment string that is associated with the
transition
emergencyEndRun ?remark?
Ends a run with an EMERGENCY_END transition.
This differs from an END transition only in that
it implies the end of the run was not handled normally. The
remark, if supplied is a text string
associated with the transition.
listRuns
Returns a list. Each list element is a run dict that describes one run. All runs known to the logbook (including the current run if any) are represented by elements in the list.
For information about the contents of each dict see: DICTIONARIES.
currentRun
If there is a current run (sometimes referred to as the active run), returns a run dict that describes that run. If there is no current run an empty dict is returned. The command dict size applied to that dictionary value will be zero if the dictionary is not empty. For example:
findRun number
If there is a run in the logbook with run number
number the run dict that describes it
is returned. If not an empty dict is returned.
As with currentRun,
dict size can be used to determine if the
returned value is empty.
getNote id
Returns a note dict that describes the note with primary key
id. The contents of note dicts is described
in
DICTIONARIES.
getNoteText note
Given a note dict, returns the markdown text associated with the note
whose note dict is note.
This proc exports images associated with the note text and
fixe up image references so that they will be handled correctly
by markdown renderers.
getNoteTitle ?note?
Returns up to the first 20 characters of the first line of the
note text given a note dict note.
This is assumed to be a title string that can give a user some
idea of what the note is about.
If the first line of the note is over 20 characters long, the
first 20 characters followed by the text ...
is returned.
listAllNotes
Returns list containing the note dicts for all notes in the logbook.
listNotesForRun number
Returns a list containing the note dicts for all notes associated
with the run numbered number. It is perfectly
acceptable for this list to be empty, if there are no notes
associated with the run.
listNonRunNotes
Returns a list of dicts for all notes that are not associated with any run.
kvExists key
Returns a boolean true if the key value store of the current
logbook database contains a key with the string value
key
kvGet key
If the key key exists in the key value store,
the value associated with the key is returned. Otherwise, the
command raises an error.
kvSet key value
If there is a key key in the key value
store, the value associated with it is changed to
value. If not, a new key is created
and has a value value.
kvCreate key value
Creates a new key, value
pair in the logbook's key value store. If key
is already defined in the logbook database, an error is raised.
Several object types in the logbook database have dict representations. This section describes the key/value pairs in each dict.
Person Dict. This dict contains key/value pairs that define a person in the logbook:\
Contains the primary key of the person.
Contains the person's last name.
Contains the person's first name.
Contains the person's salutation. This string is empty if there is no saulation associated with the person.
Run dict. This dict describes the run metadata and its transitiongs. By nature each run has at least one transition. The key value pairs are:
The run's run number.
The run's title string.
Evaluates to a boolean that is true if the run is active.
list of transition dicts. Transition dicts contain the following key/value pairs:
The transition type name string e.g. BEGIN is always the first transition in a run.
The clock seconds when the transition was logged.
The remark string associated with this state transition.
Note Dict. Contains data associated with a note. Note that in order to make these dicts relatively light-weight, the text and images associated with a note cannot be directly accessed via this dict. Its key value pairs are:
The primary key assigned to the note.
If present the contents of this key are the run dict that describes the run associated with this note.
The clock seconds at which the note was loaded into the database.
Contains the person dict that describes the note's author.