Mercurial > p > roundup > code

annotate doc/spec.html @ 106:25216cb3ff79

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added some documentation to the roundup package.
author Richard Jones <richard@users.sourceforge.net>
date Sat, 28 Jul 2001 01:39:02 +0000
parents 5147b4c51fd5
children 944bb5255eaf
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
71
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1 <html>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
2 <head>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
3 <title>Software Carpentry Track: Roundup</title>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
4 </head>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
5 <body bgcolor=white>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
6
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
7 <table width="100%">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
8 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
9
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
10 <td align="left">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
11 <a href="http://www.software-carpentry.com"><img src="images/logo-software-carpentry-standard.gif" alt="[Software Carpentry logo]" border="0"></a>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
12 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
13
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
14 <td align="right">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
15 <table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
16 <tr><td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
17 <a href="http://www.acl.lanl.gov"><img src="images//logo-acl-medium.gif" alt="[ACL Logo]" border="0"></a>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
18 </td></tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
19 <tr><td><hr></td></tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
20 <tr><td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
21 <a href="http://www.codesourcery.com"><img src="images/logo-codesourcery-medium.gif" alt="[CodeSourcery Logo]" border="0"></a>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
22 </td></tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
23 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
24 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
25
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
26 </tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
27 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
28
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
29 <hr><p>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
30
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
31 <h1 align=center>Roundup</h1>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
32 <h3 align=center>An Issue-Tracking System for Knowledge Workers</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
33 <h4 align=center><a href="http://www.lfw.org/ping/">Ka-Ping Yee</a><br>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
34 <a href="mailto:ping@lfw.org">ping@lfw.org</a></h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
35 <h3 align=center>Implementation Guide</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
36
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
37 <h2>Contents</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
38
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
39 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
40 <li>Introduction
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
41 <li>The Layer Cake
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
42 <li>Hyperdatabase
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
43 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
44 <li>Dates and Date Arithmetic
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
45 <li>Nodes and Classes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
46 <li>Identifiers and Designators
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
47 <li>Property Names and Types
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
48 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
49 <li>Application Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
50 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
51 <li>Roundup Database
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
52 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
53 <li>Reserved Classes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
54 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
55 <li>Users
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
56 <li>Messages
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
57 <li>Files
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
58 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
59 <li>Item Classes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
60 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
61 <li>Default Schema
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
62 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
63 <li>Detector Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
64 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
65 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
66 <li>Detector Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
67 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
68 <li>Command Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
69 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
70 <li>Interface Specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
71 <li>Usage Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
72 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
73 <li>E-mail User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
74 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
75 <li>Message Processing
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
76 <li>Nosy Lists
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
77 <li>Setting Properties
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
78 <li>Workflow Example
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
79 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
80 <li>Web User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
81 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
82 <li>Views and View Specifiers
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
83 <li>Displaying Properties
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
84 <li>Index Views
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
85 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
86 <li>Index View Specifiers
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
87 <li>Filter Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
88 <li>Index Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
89 <li>Sorting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
90 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
91 <li>Item Views
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
92 <ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
93 <li>Item View Specifiers
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
94 <li>Editor Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
95 <li>Spool Section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
96 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
97 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
98 <li>Deployment Scenarios
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
99 <li>Acknowledgements
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
100 </ol>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
101
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
102 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
103 <h2>1. Introduction</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
104
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
105 <p>This document presents a description of the components
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
106 of the Roundup system and specifies their interfaces and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
107 behaviour in sufficient detail to guide an implementation.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
108 For the philosophy and rationale behind the Roundup design,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
109 see the first-round Software Carpentry submission for Roundup.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
110 This document fleshes out that design as well as specifying
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
111 interfaces so that the components can be developed separately.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
112
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
113 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
114 <h2>2. The Layer Cake</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
115
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
116 <p>Lots of software design documents come with a picture of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
117 a cake. Everybody seems to like them. I also like cakes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
118 (i think they are tasty). So i, too, shall include
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
119 a picture of a cake here.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
120
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
121 <p align=center><table cellspacing=0 cellpadding=10 border=0 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
122 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
123 <td bgcolor="#e8e8e8" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
124 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
125 E-mail Client
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
126 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
127 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
128 <td bgcolor="#e0e0e0" align="center">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
129 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
130 Web Browser
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
131 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
132 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
133 <td bgcolor="#e8e8e8" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
134 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
135 Detector Scripts
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
136 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
137 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
138 <td bgcolor="#e0e0e0" align="center">
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
139 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
140 Shell
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
141 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
142 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
143 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
144 <td bgcolor="#d0d0f0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
145 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
146 E-mail User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
147 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
148 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
149 <td bgcolor="#f0d0d0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
150 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
151 Web User Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
152 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
153 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
154 <td bgcolor="#d0f0d0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
155 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
156 Detector Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
157 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
158 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
159 <td bgcolor="#f0d0f0" align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
160 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
161 Command Interface
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
162 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
163 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
164 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
165 <td bgcolor="#f0f0d0" colspan=4 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
166 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
167 Roundup Database Layer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
168 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
169 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
170 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
171 <td bgcolor="#d0f0f0" colspan=4 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
172 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
173 Hyperdatabase Layer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
174 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
175 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
176 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
177 <td bgcolor="#e8e8e8" colspan=4 align=center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
178 <p><font face="helvetica, arial"><small>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
179 Storage Layer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
180 </small></font>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
181 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
182 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
183
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
184 <p>The colourful parts of the cake are part of our system;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
185 the faint grey parts of the cake are external components.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
186
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
187 <p>I will now proceed to forgo all table manners and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
188 eat from the bottom of the cake to the top. You may want
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
189 to stand back a bit so you don't get covered in crumbs.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
190
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
191 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
192 <h2>3. Hyperdatabase</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
193
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
194 <p>The lowest-level component to be implemented is the hyperdatabase.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
195 The hyperdatabase is intended to be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
196 a flexible data store that can hold configurable data in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
197 records which we call <em>nodes</em>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
198
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
199 <p>The hyperdatabase is implemented on top of the storage layer,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
200 an external module for storing its data. The storage layer could
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
201 be a third-party RDBMS; for a "batteries-included" distribution,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
202 implementing the hyperdatabase on the standard <tt>bsddb</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
203 module is suggested.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
204
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
205 <h3>3.1. Dates and Date Arithmetic</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
206
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
207 <p>Before we get into the hyperdatabase itself, we need a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
208 way of handling dates. The hyperdatabase module provides
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
209 Timestamp objects for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
210 representing date-and-time stamps and Interval objects for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
211 representing date-and-time intervals.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
212
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
213 <p>As strings, date-and-time stamps are specified with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
214 the date in international standard format
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
215 (<em>yyyy</em>-<em>mm</em>-<em>dd</em>)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
216 joined to the time (<em>hh</em>:<em>mm</em>:<em>ss</em>)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
217 by a period ("."). Dates in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
218 this form can be easily compared and are fairly readable
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
219 when printed. An example of a valid stamp is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
220 "<strong>2000-06-24.13:03:59</strong>".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
221 We'll call this the "full date format". When Timestamp objects are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
222 printed as strings, they appear in the full date format with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
223 the time always given in GMT. The full date format is always
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
224 exactly 19 characters long.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
225
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
226 <p>For user input, some partial forms are also permitted:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
227 the whole time or just the seconds may be omitted; and the whole date
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
228 may be omitted or just the year may be omitted. If the time is given,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
229 the time is interpreted in the user's local time zone.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
230 The <tt>Date</tt> constructor takes care of these conversions.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
231 In the following examples, suppose that <em>yyyy</em> is the current year,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
232 <em>mm</em> is the current month, and <em>dd</em> is the current
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
233 day of the month; and suppose that the user is on Eastern Standard Time.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
234
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
235 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
236 <li>"<strong>2000-04-17</strong>" means &lt;Date 2000-04-17.00:00:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
237 <li>"<strong>01-25</strong>" means &lt;Date <em>yyyy</em>-01-25.00:00:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
238 <li>"<strong>2000-04-17.03:45</strong>" means &lt;Date 2000-04-17.08:45:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
239 <li>"<strong>08-13.22:13</strong>" means &lt;Date <em>yyyy</em>-08-14.03:13:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
240 <li>"<strong>11-07.09:32:43</strong>" means &lt;Date <em>yyyy</em>-11-07.14:32:43&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
241 <li>"<strong>14:25</strong>" means
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
242 &lt;Date <em>yyyy</em>-<em>mm</em>-<em>dd</em>.19:25:00&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
243 <li>"<strong>8:47:11</strong>" means
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
244 &lt;Date <em>yyyy</em>-<em>mm</em>-<em>dd</em>.13:47:11&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
245 <li>the special date "<strong>.</strong>" means "right now"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
246 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
247
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
248 <p>Date intervals are specified using the suffixes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
249 "y", "m", and "d". The suffix "w" (for "week") means 7 days.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
250 Time intervals are specified in hh:mm:ss format (the seconds
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
251 may be omitted, but the hours and minutes may not).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
252
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
253 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
254 <li>"<strong>3y</strong>" means three years
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
255 <li>"<strong>2y 1m</strong>" means two years and one month
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
256 <li>"<strong>1m 25d</strong>" means one month and 25 days
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
257 <li>"<strong>2w 3d</strong>" means two weeks and three days
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
258 <li>"<strong>1d 2:50</strong>" means one day, two hours, and 50 minutes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
259 <li>"<strong>14:00</strong>" means 14 hours
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
260 <li>"<strong>0:04:33</strong>" means four minutes and 33 seconds
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
261 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
262
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
263 <p>The Date class should understand simple date expressions of the form
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
264 <em>stamp</em> + <em>interval</em> and <em>stamp</em> - <em>interval</em>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
265 When adding or subtracting intervals involving months or years, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
266 components are handled separately. For example, when evaluating
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
267 "<strong>2000-06-25 + 1m 10d</strong>", we first add one month to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
268 get <strong>2000-07-25</strong>, then add 10 days to get
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
269 <strong>2000-08-04</strong> (rather than trying to decide whether
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
270 <strong>1m 10d</strong> means 38 or 40 or 41 days).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
271
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
272 <p>Here is an outline of the Date and Interval classes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
273
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
274 <blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
275 <pre><small>class <strong>Date</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
276 def <strong>__init__</strong>(self, spec, offset):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
277 """Construct a date given a specification and a time zone offset.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
278
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
279 'spec' is a full date or a partial form, with an optional
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
280 added or subtracted interval. 'offset' is the local time
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
281 zone offset from GMT in hours.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
282 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
283
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
284 def <strong>__add__</strong>(self, interval):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
285 """Add an interval to this date to produce another date."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
286
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
287 def <strong>__sub__</strong>(self, interval):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
288 """Subtract an interval from this date to produce another date."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
289
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
290 def <strong>__cmp__</strong>(self, other):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
291 """Compare this date to another date."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
292
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
293 def <strong>__str__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
294 """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
295
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
296 def <strong>local</strong>(self, offset):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
297 """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
298
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
299 class <strong>Interval</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
300 def <strong>__init__</strong>(self, spec):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
301 """Construct an interval given a specification."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
302
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
303 def <strong>__cmp__</strong>(self, other):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
304 """Compare this interval to another interval."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
305
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
306 def <strong>__str__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
307 """Return this interval as a string."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
308 </small></pre>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
309 </blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
310
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
311 <p>Here are some examples of how these classes would behave in practice.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
312 For the following examples, assume that we are on Eastern Standard
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
313 Time and the current local time is 19:34:02 on 25 June 2000.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
314
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
315 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
316 >&gt;&gt;&gt; <span class="input">Date(".")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
317 <span class="output">&lt;Date 2000-06-26.00:34:02&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
318 &gt;&gt;&gt; <span class="input">_.local(-5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
319 <span class="output">"2000-06-25.19:34:02"</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
320 &gt;&gt;&gt; <span class="input">Date(". + 2d")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
321 <span class="output">&lt;Date 2000-06-28.00:34:02&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
322 &gt;&gt;&gt; <span class="input">Date("1997-04-17", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
323 <span class="output">&lt;Date 1997-04-17.00:00:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
324 &gt;&gt;&gt; <span class="input">Date("01-25", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
325 <span class="output">&lt;Date 2000-01-25.00:00:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
326 &gt;&gt;&gt; <span class="input">Date("08-13.22:13", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
327 <span class="output">&lt;Date 2000-08-14.03:13:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
328 &gt;&gt;&gt; <span class="input">Date("14:25", -5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
329 <span class="output">&lt;Date 2000-06-25.19:25:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
330 &gt;&gt;&gt; <span class="input">Interval(" 3w 1 d 2:00")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
331 <span class="output">&lt;Interval 22d 2:00&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
332 &gt;&gt;&gt; <span class="input">Date(". + 2d") - Interval("3w")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
333 <span class="output">&lt;Date 2000-06-07.00:34:02&gt;</span
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
334 ></small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
335
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
336 <h3>3.2. Nodes and Classes</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
337
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
338 <p>Nodes contain data in <em>properties</em>. To Python, these
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
339 properties are presented as the key-value pairs of a dictionary.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
340 Each node belongs to a <em>class</em> which defines the names
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
341 and types of its properties. The database permits the creation
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
342 and modification of classes as well as nodes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
343
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
344 <h3>3.3. Identifiers and Designators</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
345
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
346 <p>Each node has a numeric identifier which is unique among
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
347 nodes in its class. The nodes are numbered sequentially
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
348 within each class in order of creation, starting from 1.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
349 The <em>designator</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
350 for a node is a way to identify a node in the database, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
351 consists of the name of the node's class concatenated with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
352 the node's numeric identifier.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
353
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
354 <p>For example, if "spam" and "eggs" are classes, the first
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
355 node created in class "spam" has id 1 and designator "spam1".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
356 The first node created in class "eggs" also has id 1 but has
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
357 the distinct designator "eggs1". Node designators are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
358 conventionally enclosed in square brackets when mentioned
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
359 in plain text. This permits a casual mention of, say,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
360 "[patch37]" in an e-mail message to be turned into an active
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
361 hyperlink.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
362
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
363 <h3>3.4. Property Names and Types</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
364
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
365 <p>Property names must begin with a letter.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
366
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
367 <p>A property may be one of five <em>basic types</em>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
368
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
369 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
370 <li><em>String</em> properties are for storing arbitrary-length
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
371 strings.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
372
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
373 <li><em>Date</em> properties store date-and-time stamps.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
374 Their values are Timestamp objects.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
375
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
376 <li>A <em>Link</em> property refers to a single other node
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
377 selected from a specified class. The class is part of the property;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
378 the value is an integer, the id of the chosen node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
379
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
380 <li>A <em>Multilink</em> property refers to possibly many nodes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
381 in a specified class. The value is a list of integers.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
382 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
383
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
384 <p><tt>None</tt> is also a permitted value for any of these property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
385 types. An attempt to store <tt>None</tt> into a String property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
386 stores the empty string; an attempt to store <tt>None</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
387 into a Multilink property stores an empty list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
388
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
389 <h3>3.5. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
390
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
391 <p>The hyperdb module provides property objects to designate
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
392 the different kinds of properties. These objects are used when
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
393 specifying what properties belong in classes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
394
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
395 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
396 >class <strong>String</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
397 def <strong>__init__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
398 """An object designating a String property."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
399
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
400 class <strong>Date</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
401 def <strong>__init__</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
402 """An object designating a Date property."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
403
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
404 class <strong>Link</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
405 def <strong>__init__</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
406 """An object designating a Link property that links to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
407 nodes in a specified class."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
408
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
409 class <strong>Multilink</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
410 def <strong>__init__</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
411 """An object designating a Multilink property that links
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
412 to nodes in a specified class."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
413 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
414
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
415 <p>Here is the interface provided by the hyperdatabase.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
416
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
417 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
418 >class <strong>Database</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
419 """A database for storing records containing flexible data types."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
420
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
421 def <strong>__init__</strong>(self, storagelocator, journaltag):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
422 """Open a hyperdatabase given a specifier to some storage.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
423
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
424 The meaning of 'storagelocator' depends on the particular
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
425 implementation of the hyperdatabase. It could be a file name,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
426 a directory path, a socket descriptor for a connection to a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
427 database over the network, etc.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
428
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
429 The 'journaltag' is a token that will be attached to the journal
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
430 entries for any edits done on the database. If 'journaltag' is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
431 None, the database is opened in read-only mode: the Class.create(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
432 Class.set(), and Class.retire() methods are disabled.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
433 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
434
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
435 def <strong>__getattr__</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
436 """A convenient way of calling self.getclass(classname)."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
437
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
438 def <strong>getclasses</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
439 """Return a list of the names of all existing classes."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
440
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
441 def <strong>getclass</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
442 """Get the Class object representing a particular class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
443
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
444 If 'classname' is not a valid class name, a KeyError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
445 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
446
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
447 class <strong>Class</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
448 """The handle to a particular class of nodes in a hyperdatabase."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
449
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
450 def <strong>__init__</strong>(self, db, classname, **properties):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
451 """Create a new class with a given name and property specification.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
452
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
453 'classname' must not collide with the name of an existing class,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
454 or a ValueError is raised. The keyword arguments in 'properties'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
455 must map names to property objects, or a TypeError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
456 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
457
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
458 # Editing nodes:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
459
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
460 def <strong>create</strong>(self, **propvalues):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
461 """Create a new node of this class and return its id.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
462
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
463 The keyword arguments in 'propvalues' map property names to values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
464 The values of arguments must be acceptable for the types of their
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
465 corresponding properties or a TypeError is raised. If this class
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
466 has a key property, it must be present and its value must not
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
467 collide with other key strings or a ValueError is raised. Any other
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
468 properties on this class that are missing from the 'propvalues'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
469 dictionary are set to None. If an id in a link or multilink
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
470 property does not refer to a valid node, an IndexError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
471 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
472
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
473 def <strong>get</strong>(self, nodeid, propname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
474 """Get the value of a property on an existing node of this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
475
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
476 'nodeid' must be the id of an existing node of this class or an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
477 IndexError is raised. 'propname' must be the name of a property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
478 of this class or a KeyError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
479 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
480
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
481 def <strong>set</strong>(self, nodeid, **propvalues):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
482 """Modify a property on an existing node of this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
483
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
484 'nodeid' must be the id of an existing node of this class or an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
485 IndexError is raised. Each key in 'propvalues' must be the name
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
486 of a property of this class or a KeyError is raised. All values
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
487 in 'propvalues' must be acceptable types for their corresponding
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
488 properties or a TypeError is raised. If the value of the key
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
489 property is set, it must not collide with other key strings or a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
490 ValueError is raised. If the value of a Link or Multilink
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
491 property contains an invalid node id, a ValueError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
492 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
493
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
494 def <strong>retire</strong>(self, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
495 """Retire a node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
496
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
497 The properties on the node remain available from the get() method,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
498 and the node's id is never reused. Retired nodes are not returned
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
499 by the find(), list(), or lookup() methods, and other nodes may
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
500 reuse the values of their key properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
501 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
502
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
503 def <strong>history</strong>(self, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
504 """Retrieve the journal of edits on a particular node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
505
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
506 'nodeid' must be the id of an existing node of this class or an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
507 IndexError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
508
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
509 The returned list contains tuples of the form
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
510
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
511 (date, tag, action, params)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
512
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
513 'date' is a Timestamp object specifying the time of the change and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
514 'tag' is the journaltag specified when the database was opened.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
515 'action' may be:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
516
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
517 'create' or 'set' -- 'params' is a dictionary of property values
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
518 'link' or 'unlink' -- 'params' is (classname, nodeid, propname)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
519 'retire' -- 'params' is None
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
520 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
521
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
522 # Locating nodes:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
523
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
524 def <strong>setkey</strong>(self, propname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
525 """Select a String property of this class to be the key property.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
526
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
527 'propname' must be the name of a String property of this class or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
528 None, or a TypeError is raised. The values of the key property on
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
529 all existing nodes must be unique or a ValueError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
530 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
531
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
532 def <strong>getkey</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
533 """Return the name of the key property for this class or None."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
534
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
535 def <strong>lookup</strong>(self, keyvalue):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
536 """Locate a particular node by its key property and return its id.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
537
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
538 If this class has no key property, a TypeError is raised. If the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
539 'keyvalue' matches one of the values for the key property among
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
540 the nodes in this class, the matching node's id is returned;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
541 otherwise a KeyError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
542 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
543
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
544 def <strong>find</strong>(self, propname, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
545 """Get the ids of nodes in this class which link to a given node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
546
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
547 'propname' must be the name of a property in this class, or a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
548 KeyError is raised. That property must be a Link or Multilink
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
549 property, or a TypeError is raised. 'nodeid' must be the id of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
550 an existing node in the class linked to by the given property,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
551 or an IndexError is raised.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
552 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
553
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
554 def <strong>list</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
555 """Return a list of the ids of the active nodes in this class."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
556
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
557 def <strong>count</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
558 """Get the number of nodes in this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
559
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
560 If the returned integer is 'numnodes', the ids of all the nodes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
561 in this class run from 1 to numnodes, and numnodes+1 will be the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
562 id of the next node to be created in this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
563 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
564
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
565 # Manipulating properties:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
566
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
567 def <strong>getprops</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
568 """Return a dictionary mapping property names to property objects."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
569
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
570 def <strong>addprop</strong>(self, **properties):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
571 """Add properties to this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
572
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
573 The keyword arguments in 'properties' must map names to property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
574 objects, or a TypeError is raised. None of the keys in 'properties'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
575 may collide with the names of existing properties, or a ValueError
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
576 is raised before any properties have been added.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
577 """</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
578
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
579 <h3>3.6. Application Example</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
580
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
581 <p>Here is an example of how the hyperdatabase module would work in practice.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
582
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
583 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
584 >&gt;&gt;&gt; <span class="input">import hyperdb</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
585 &gt;&gt;&gt; <span class="input">db = hyperdb.Database("foo.db", "ping")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
586 &gt;&gt;&gt; <span class="input">db</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
587 <span class="output">&lt;hyperdb.Database "foo.db" opened by "ping"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
588 &gt;&gt;&gt; <span class="input">hyperdb.Class(db, "status", name=hyperdb.String())</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
589 <span class="output">&lt;hyperdb.Class "status"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
590 &gt;&gt;&gt; <span class="input">_.setkey("name")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
591 &gt;&gt;&gt; <span class="input">db.status.create(name="unread")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
592 <span class="output">1</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
593 &gt;&gt;&gt; <span class="input">db.status.create(name="in-progress")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
594 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
595 &gt;&gt;&gt; <span class="input">db.status.create(name="testing")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
596 <span class="output">3</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
597 &gt;&gt;&gt; <span class="input">db.status.create(name="resolved")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
598 <span class="output">4</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
599 &gt;&gt;&gt; <span class="input">db.status.count()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
600 <span class="output">4</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
601 &gt;&gt;&gt; <span class="input">db.status.list()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
602 <span class="output">[1, 2, 3, 4]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
603 &gt;&gt;&gt; <span class="input">db.status.lookup("in-progress")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
604 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
605 &gt;&gt;&gt; <span class="input">db.status.retire(3)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
606 &gt;&gt;&gt; <span class="input">db.status.list()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
607 <span class="output">[1, 2, 4]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
608 &gt;&gt;&gt; <span class="input">hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
609 <span class="output">&lt;hyperdb.Class "issue"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
610 &gt;&gt;&gt; <span class="input">db.issue.create(title="spam", status=1)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
611 <span class="output">1</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
612 &gt;&gt;&gt; <span class="input">db.issue.create(title="eggs", status=2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
613 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
614 &gt;&gt;&gt; <span class="input">db.issue.create(title="ham", status=4)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
615 <span class="output">3</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
616 &gt;&gt;&gt; <span class="input">db.issue.create(title="arguments", status=2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
617 <span class="output">4</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
618 &gt;&gt;&gt; <span class="input">db.issue.create(title="abuse", status=1)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
619 <span class="output">5</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
620 &gt;&gt;&gt; <span class="input">hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String())</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
621 <span class="output">&lt;hyperdb.Class "user"&gt;</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
622 &gt;&gt;&gt; <span class="input">db.issue.addprop(fixer=hyperdb.Link("user"))</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
623 &gt;&gt;&gt; <span class="input">db.issue.getprops()</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
624 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
625 >{"title": &lt;hyperdb.String&gt;, "status": &lt;hyperdb.Link to "status"&gt;,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
626 "user": &lt;hyperdb.Link to "user"&gt;}</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
627 &gt;&gt;&gt; <span class="input">db.issue.set(5, status=2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
628 &gt;&gt;&gt; <span class="input">db.issue.get(5, "status")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
629 <span class="output">2</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
630 &gt;&gt;&gt; <span class="input">db.status.get(2, "name")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
631 <span class="output">"in-progress"</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
632 &gt;&gt;&gt; <span class="input">db.issue.get(5, "title")</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
633 <span class="output">"abuse"</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
634 &gt;&gt;&gt; <span class="input">db.issue.find("status", db.status.lookup("in-progress"))</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
635 <span class="output">[2, 4, 5]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
636 &gt;&gt;&gt; <span class="input">db.issue.history(5)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
637 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
638 >[(&lt;Date 2000-06-28.19:09:43&gt;, "ping", "create", {"title": "abuse", "status": 1}),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
639 (&lt;Date 2000-06-28.19:11:04&gt;, "ping", "set", {"status": 2})]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
640 &gt;&gt;&gt; <span class="input">db.status.history(1)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
641 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
642 >[(&lt;Date 2000-06-28.19:09:43&gt;, "ping", "link", ("issue", 5, "status")),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
643 (&lt;Date 2000-06-28.19:11:04&gt;, "ping", "unlink", ("issue", 5, "status"))]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
644 &gt;&gt;&gt; <span class="input">db.status.history(2)</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
645 <span class="output"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
646 >[(&lt;Date 2000-06-28.19:11:04&gt;, "ping", "link", ("issue", 5, "status"))]</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
647 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
648
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
649 <p>For the purposes of journalling, when a Multilink property is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
650 set to a new list of nodes, the hyperdatabase compares the old
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
651 list to the new list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
652 The journal records "unlink" events for all the nodes that appear
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
653 in the old list but not the new list,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
654 and "link" events for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
655 all the nodes that appear in the new list but not in the old list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
656
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
657 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
658 <h2>4. Roundup Database</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
659
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
660 <p>The Roundup database layer is implemented on top of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
661 hyperdatabase and mediates calls to the database.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
662 Some of the classes in the Roundup database are considered
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
663 <em>item classes</em>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
664 The Roundup database layer adds detectors and user nodes,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
665 and on items it provides mail spools, nosy lists, and superseders.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
666
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
667 <h3>4.1. Reserved Classes</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
668
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
669 <p>Internal to this layer we reserve three special classes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
670 of nodes that are not items.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
671
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
672 <h4>4.1.1. Users</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
673
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
674 <p>Users are stored in the hyperdatabase as nodes of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
675 class "user". The "user" class has the definition:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
676
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
677 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
678 >hyperdb.Class(db, "user", username=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
679 password=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
680 address=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
681 db.user.setkey("username")</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
682
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
683 <h4>4.1.2. Messages</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
684
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
685 <p>E-mail messages are represented by hyperdatabase nodes of class "msg".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
686 The actual text content of the messages is stored in separate files.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
687 (There's no advantage to be gained by stuffing them into the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
688 hyperdatabase, and if messages are stored in ordinary text files,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
689 they can be grepped from the command line.) The text of a message is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
690 saved in a file named after the message node designator (e.g. "msg23")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
691 for the sake of the command interface (see below). Attachments are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
692 stored separately and associated with "file" nodes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
693 The "msg" class has the definition:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
694
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
695 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
696 >hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
697 recipients=hyperdb.Multilink("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
698 date=hyperdb.Date(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
699 summary=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
700 files=hyperdb.Multilink("file"))</small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
701 ></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
702
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
703 <p>The "author" property indicates the author of the message
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
704 (a "user" node must exist in the hyperdatabase for any messages
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
705 that are stored in the system).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
706 The "summary" property contains a summary of the message for display
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
707 in a message index.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
708
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
709 <h4>4.1.3. Files</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
710
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
711 <p>Submitted files are represented by hyperdatabase
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
712 nodes of class "file". Like e-mail messages, the file content
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
713 is stored in files outside the database,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
714 named after the file node designator (e.g. "file17").
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
715 The "file" class has the definition:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
716
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
717 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
718 >hyperdb.Class(db, "file", user=hyperdb.Link("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
719 name=hyperdb.String(),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
720 type=hyperdb.String())</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
721
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
722 <p>The "user" property indicates the user who submitted the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
723 file, the "name" property holds the original name of the file,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
724 and the "type" property holds the MIME type of the file as received.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
725
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
726 <h3>4.2. Item Classes</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
727
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
728 <p>All items have the following standard properties:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
729
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
730 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
731 >title=hyperdb.String()
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
732 messages=hyperdb.Multilink("msg")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
733 files=hyperdb.Multilink("file")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
734 nosy=hyperdb.Multilink("user")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
735 superseder=hyperdb.Multilink("item")</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
736
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
737 <p>Also, two Date properties named "creation" and "activity" are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
738 fabricated by the Roundup database layer. By "fabricated" we
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
739 mean that no such properties are actually stored in the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
740 hyperdatabase, but when properties on items are requested, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
741 "creation" and "activity" properties are made available.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
742 The value of the "creation" property is the date when an item was
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
743 created, and the value of the "activity" property is the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
744 date when any property on the item was last edited (equivalently,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
745 these are the dates on the first and last records in the item's journal).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
746
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
747 <h3>4.3. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
748
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
749 <p>The interface to a Roundup database delegates most method
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
750 calls to the hyperdatabase, except for the following
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
751 changes and additional methods.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
752
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
753 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
754 >class <strong>Database</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
755 # Overridden methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
756
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
757 def <strong>__init__</strong>(self, storagelocator, journaltag):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
758 """When the Roundup database is opened by a particular user,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
759 the 'journaltag' is the id of the user's "user" node."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
760
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
761 def <strong>getclass</strong>(self, classname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
762 """This method now returns an instance of either Class or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
763 ItemClass depending on whether an item class is specified."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
764
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
765 # New methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
766
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
767 def <strong>getuid</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
768 """Return the id of the "user" node associated with the user
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
769 that owns this connection to the hyperdatabase."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
770
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
771 class <strong>Class</strong>:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
772 # Overridden methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
773
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
774 def <strong>create</strong>(self, **propvalues):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
775 def <strong>set</strong>(self, **propvalues):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
776 def <strong>retire</strong>(self, nodeid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
777 """These operations trigger detectors and can be vetoed. Attempts
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
778 to modify the "creation" or "activity" properties cause a KeyError.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
779 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
780
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
781 # New methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
782
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
783 def <strong>audit</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
784 def <strong>react</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
785 """Register a detector (see below for more details)."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
786
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
787 class <strong>ItemClass</strong>(Class):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
788 # Overridden methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
789
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
790 def <strong>__init__</strong>(self, db, classname, **properties):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
791 """The newly-created class automatically includes the "messages",
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
792 "files", "nosy", and "superseder" properties. If the 'properties'
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
793 dictionary attempts to specify any of these properties or a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
794 "creation" or "activity" property, a ValueError is raised."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
795
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
796 def <strong>get</strong>(self, nodeid, propname):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
797 def <strong>getprops</strong>(self):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
798 """In addition to the actual properties on the node, these
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
799 methods provide the "creation" and "activity" properties."""
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
800
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
801 # New methods:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
802
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
803 def <strong>addmessage</strong>(self, nodeid, summary, text):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
804 """Add a message to an item's mail spool.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
805
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
806 A new "msg" node is constructed using the current date, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
807 user that owns the database connection as the author, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
808 the specified summary text. The "files" and "recipients"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
809 fields are left empty. The given text is saved as the body
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
810 of the message and the node is appended to the "messages"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
811 field of the specified item.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
812 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
813
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
814 def <strong>sendmessage</strong>(self, nodeid, msgid):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
815 """Send a message to the members of an item's nosy list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
816
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
817 The message is sent only to users on the nosy list who are not
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
818 already on the "recipients" list for the message. These users
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
819 are then added to the message's "recipients" list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
820 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
821 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
822
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
823 <h3>4.4. Default Schema</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
824
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
825 <p>The default schema included with Roundup turns it into a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
826 typical software bug tracker. The database is set up like this:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
827
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
828 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
829 >pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
830 pri.setkey("name")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
831 pri.create(name="critical", order="1")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
832 pri.create(name="urgent", order="2")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
833 pri.create(name="bug", order="3")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
834 pri.create(name="feature", order="4")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
835 pri.create(name="wish", order="5")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
836
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
837 stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
838 stat.setkey("name")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
839 stat.create(name="unread", order="1")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
840 stat.create(name="deferred", order="2")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
841 stat.create(name="chatting", order="3")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
842 stat.create(name="need-eg", order="4")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
843 stat.create(name="in-progress", order="5")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
844 stat.create(name="testing", order="6")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
845 stat.create(name="done-cbb", order="7")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
846 stat.create(name="resolved", order="8")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
847
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
848 Class(db, "keyword", name=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
849
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
850 Class(db, "issue", fixer=hyperdb.Multilink("user"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
851 topic=hyperdb.Multilink("keyword"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
852 priority=hyperdb.Link("priority"),
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
853 status=hyperdb.Link("status"))
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
854 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
855
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
856 <p>(The "order" property hasn't been explained yet. It
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
857 gets used by the Web user interface for sorting.)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
858
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
859 <p>The above isn't as pretty-looking as the schema specification
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
860 in the first-stage submission, but it could be made just as easy
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
861 with the addition of a convenience function like <tt>Choice</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
862 for setting up the "priority" and "status" classes:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
863
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
864 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
865 >def Choice(name, *options):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
866 cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
867 for i in range(len(options)):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
868 cl.create(name=option[i], order=i)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
869 return hyperdb.Link(name)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
870 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
871
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
872 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
873 <h2>5. Detector Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
874
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
875 <p>Detectors are Python functions that are triggered on certain
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
876 kinds of events. The definitions of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
877 functions live in Python modules placed in a directory set aside
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
878 for this purpose. Importing the Roundup database module also
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
879 imports all the modules in this directory, and the <tt>init()</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
880 function of each module is called when a database is opened to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
881 provide it a chance to register its detectors.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
882
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
883 <p>There are two kinds of detectors:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
884
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
885 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
886 <li>an <em>auditor</em> is triggered just before modifying an node
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
887 <li>a <em>reactor</em> is triggered just after an node has been modified
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
888 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
889
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
890 <p>When the Roundup database is about to perform a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
891 <tt>create()</tt>, <tt>set()</tt>, or <tt>retire()</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
892 operation, it first calls any auditors that
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
893 have been registered for that operation on that class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
894 Any auditor may raise a <tt>Reject</tt> exception
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
895 to abort the operation.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
896
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
897 <p>If none of the auditors raises an exception, the database
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
898 proceeds to carry out the operation. After it's done, it
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
899 then calls all of the reactors that have been registered
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
900 for the operation.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
901
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
902 <h3>5.1. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
903
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
904 <p>The <tt>audit()</tt> and <tt>react()</tt> methods
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
905 register detectors on a given class of nodes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
906
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
907 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
908 >class Class:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
909 def <strong>audit</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
910 """Register an auditor on this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
911
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
912 'event' should be one of "create", "set", or "retire".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
913 'detector' should be a function accepting four arguments.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
914 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
915
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
916 def <strong>react</strong>(self, event, detector):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
917 """Register a reactor on this class.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
918
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
919 'event' should be one of "create", "set", or "retire".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
920 'detector' should be a function accepting four arguments.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
921 """
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
922 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
923
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
924 <p>Auditors are called with the arguments:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
925
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
926 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
927 >audit(db, cl, nodeid, newdata)</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
928
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
929 where <tt>db</tt> is the database, <tt>cl</tt> is an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
930 instance of Class or ItemClass within the database, and <tt>newdata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
931 is a dictionary mapping property names to values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
932
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
933 For a <tt>create()</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
934 operation, the <tt>nodeid</tt> argument is <tt>None</tt> and <tt>newdata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
935 contains all of the initial property values with which the node
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
936 is about to be created.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
937
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
938 For a <tt>set()</tt> operation, <tt>newdata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
939 contains only the names and values of properties that are about
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
940 to be changed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
941
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
942 For a <tt>retire()</tt> operation, <tt>newdata</tt> is <tt>None</tt>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
943
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
944 <p>Reactors are called with the arguments:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
945
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
946 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
947 >react(db, cl, nodeid, olddata)</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
948
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
949 where <tt>db</tt> is the database, <tt>cl</tt> is an
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
950 instance of Class or ItemClass within the database, and <tt>olddata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
951 is a dictionary mapping property names to values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
952
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
953 For a <tt>create()</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
954 operation, the <tt>nodeid</tt> argument is the id of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
955 newly-created node and <tt>olddata</tt> is None.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
956
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
957 For a <tt>set()</tt> operation, <tt>olddata</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
958 contains the names and previous values of properties that were changed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
959
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
960 For a <tt>retire()</tt> operation, <tt>nodeid</tt> is the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
961 id of the retired node and <tt>olddata</tt> is <tt>None</tt>.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
962
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
963 <h3>5.2. Detector Example</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
964
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
965 <p>Here is an example of detectors written for a hypothetical
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
966 project-management application, where users can signal approval
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
967 of a project by adding themselves to an "approvals" list, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
968 a project proceeds when it has three approvals.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
969
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
970 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
971 ># Permit users only to add themselves to the "approvals" list.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
972
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
973 def check_approvals(db, cl, id, newdata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
974 if newdata.has_key("approvals"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
975 if cl.get(id, "status") == db.status.lookup("approved"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
976 raise Reject, "You can't modify the approvals list " \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
977 "for a project that has already been approved."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
978 old = cl.get(id, "approvals")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
979 new = newdata["approvals"]
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
980 for uid in old:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
981 if uid not in new and uid != db.getuid():
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
982 raise Reject, "You can't remove other users from the "
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
983 "approvals list; you can only remove yourself."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
984 for uid in new:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
985 if uid not in old and uid != db.getuid():
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
986 raise Reject, "You can't add other users to the approvals "
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
987 "list; you can only add yourself."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
988
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
989 # When three people have approved a project, change its
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
990 # status from "pending" to "approved".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
991
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
992 def approve_project(db, cl, id, olddata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
993 if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
994 if cl.get(id, "status") == db.status.lookup("pending"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
995 cl.set(id, status=db.status.lookup("approved"))
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
996
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
997 def init(db):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
998 db.project.audit("set", check_approval)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
999 db.project.react("set", approve_project)</small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1000 ></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1001
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1002 <p>Here is another example of a detector that can allow or prevent
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1003 the creation of new nodes. In this scenario, patches for a software
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1004 project are submitted by sending in e-mail with an attached file,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1005 and we want to ensure that there are <tt>text/plain</tt> attachments on
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1006 the message. The maintainer of the package can then apply the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1007 patch by setting its status to "applied".
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1008
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1009 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1010 ># Only accept attempts to create new patches that come with patch files.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1011
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1012 def check_new_patch(db, cl, id, newdata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1013 if not newdata["files"]:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1014 raise Reject, "You can't submit a new patch without " \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1015 "attaching a patch file."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1016 for fileid in newdata["files"]:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1017 if db.file.get(fileid, "type") != "text/plain":
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1018 raise Reject, "Submitted patch files must be text/plain."
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1019
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1020 # When the status is changed from "approved" to "applied", apply the patch.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1021
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1022 def apply_patch(db, cl, id, olddata):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1023 if cl.get(id, "status") == db.status.lookup("applied") and \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1024 olddata["status"] == db.status.lookup("approved"):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1025 # ...apply the patch...
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1026
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1027 def init(db):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1028 db.patch.audit("create", check_new_patch)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1029 db.patch.react("set", apply_patch)</small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1030 ></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1031
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1032 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1033 <h2>6. Command Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1034
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1035 <p>The command interface is a very simple and minimal interface,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1036 intended only for quick searches and checks from the shell prompt.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1037 (Anything more interesting can simply be written in Python using
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1038 the Roundup database module.)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1039
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1040 <h3>6.1. Interface Specification</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1041
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1042 <p>A single command, <tt>roundup</tt>, provides basic access to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1043 the hyperdatabase from the command line.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1044
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1045 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1046 <li><tt>roundup&nbsp;get&nbsp;</tt>[<tt>-list</tt>]<tt>&nbsp;</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1047 ><em>designator</em>[<tt>,</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1048 ><em>designator</em><tt>,</tt>...]<tt>&nbsp;</tt><em>propname</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1049 <li><tt>roundup&nbsp;set&nbsp;</tt><em>designator</em>[<tt>,</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1050 ><em>designator</em><tt>,</tt>...]<tt>&nbsp;</tt><em>propname</em
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1051 ><tt>=</tt><em>value</em> ...
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1052 <li><tt>roundup&nbsp;find&nbsp;</tt>[<tt>-list</tt>]<tt>&nbsp;</tt
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1053 ><em>classname</em><tt>&nbsp;</tt><em>propname</em>=<em>value</em> ...
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1054 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1055
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1056 <p>Property values are represented as strings in command arguments
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1057 and in the printed results:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1058
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1059 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1060 <li>Strings are, well, strings.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1061
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1062 <li>Date values are printed in the full date format in the local
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1063 time zone, and accepted in the full format or any of the partial
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1064 formats explained above.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1065
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1066 <li>Link values are printed as node designators. When given as
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1067 an argument, node designators and key strings are both accepted.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1068
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1069 <li>Multilink values are printed as lists of node designators
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1070 joined by commas. When given as an argument, node designators
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1071 and key strings are both accepted; an empty string, a single node,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1072 or a list of nodes joined by commas is accepted.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1073 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1074
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1075 <p>When multiple nodes are specified to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1076 <tt>roundup&nbsp;get</tt> or <tt>roundup&nbsp;set</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1077 commands, the specified properties are retrieved or set
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1078 on all the listed nodes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1079
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1080 <p>When multiple results are returned by the <tt>roundup&nbsp;get</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1081 or <tt>roundup&nbsp;find</tt> commands, they are printed one per
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1082 line (default) or joined by commas (with the <tt>-list</tt>) option.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1083
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1084 <h3>6.2. Usage Example</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1085
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1086 <p>To find all messages regarding in-progress issues that
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1087 contain the word "spam", for example, you could execute the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1088 following command from the directory where the database
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1089 dumps its files:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1090
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1091 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1092 >shell% <span class="input">for issue in `roundup find issue status=in-progress`; do</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1093 &gt; <span class="input">grep -l spam `roundup get $issue messages`</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1094 &gt; <span class="input">done</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1095 <span class="output">msg23
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1096 msg49
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1097 msg50
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1098 msg61</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1099 shell%</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1100
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1101 <p>Or, using the <tt>-list</tt> option, this can be written as a single command:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1102
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1103 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1104 >shell% <span class="input">grep -l spam `roundup get \
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1105 \`roundup find -list issue status=in-progress\` messages`</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1106 <span class="output">msg23
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1107 msg49
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1108 msg50
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1109 msg61</span>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1110 shell%</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1111
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1112 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1113 <h2>7. E-mail User Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1114
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1115 <p>The Roundup system must be assigned an e-mail address
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1116 at which to receive mail. Messages should be piped to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1117 the Roundup mail-handling script by the mail delivery
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1118 system (e.g. using an alias beginning with "|" for sendmail).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1119
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1120 <h3>7.1. Message Processing</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1121
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1122 <p>Incoming messages are examined for multiple parts.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1123 In a <tt>multipart/mixed</tt> message or part, each subpart is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1124 extracted and examined. In a <tt>multipart/alternative</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1125 message or part, we look for a <tt>text/plain</tt> subpart and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1126 ignore the other parts. The <tt>text/plain</tt> subparts are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1127 assembled to form the textual body of the message, to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1128 be stored in the file associated with a "msg" class node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1129 Any parts of other types are each stored in separate
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1130 files and given "file" class nodes that are linked to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1131 the "msg" node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1132
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1133 <p>The "summary" property on message nodes is taken from
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1134 the first non-quoting section in the message body.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1135 The message body is divided into sections by blank lines.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1136 Sections where the second and all subsequent lines begin
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1137 with a "&gt;" or "|" character are considered "quoting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1138 sections". The first line of the first non-quoting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1139 section becomes the summary of the message.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1140
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1141 <p>All of the addresses in the To: and Cc: headers of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1142 incoming message are looked up among the user nodes, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1143 the corresponding users are placed in the "recipients"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1144 property on the new "msg" node. The address in the From:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1145 header similarly determines the "author" property of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1146 new "msg" node.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1147 The default handling for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1148 addresses that don't have corresponding users is to create
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1149 new users with no passwords and a username equal to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1150 address. (The web interface does not permit logins for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1151 users with no passwords.) If we prefer to reject mail from
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1152 outside sources, we can simply register an auditor on the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1153 "user" class that prevents the creation of user nodes with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1154 no passwords.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1155
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1156 <p>The subject line of the incoming message is examined to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1157 determine whether the message is an attempt to create a new
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1158 item or to discuss an existing item. A designator enclosed
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1159 in square brackets is sought as the first thing on the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1160 subject line (after skipping any "Fwd:" or "Re:" prefixes).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1161
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1162 <p>If an item designator (class name and id number) is found
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1163 there, the newly created "msg" node is added to the "messages"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1164 property for that item, and any new "file" nodes are added to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1165 the "files" property for the item.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1166
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1167 <p>If just an item class name is found there, we attempt to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1168 create a new item of that class with its "messages" property
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1169 initialized to contain the new "msg" node and its "files"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1170 property initialized to contain any new "file" nodes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1171
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1172 <p>Both cases may trigger detectors (in the first case we
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1173 are calling the <tt>set()</tt> method to add the message to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1174 item's spool; in the second case we are calling the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1175 <tt>create()</tt> method to create a new node). If an auditor
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1176 raises an exception, the original message is bounced back to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1177 the sender with the explanatory message given in the exception.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1178
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1179 <h3>7.2. Nosy Lists</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1180
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1181 <p>A standard detector is provided that watches for additions
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1182 to the "messages" property. When a new message is added, the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1183 detector sends it to all the users on the "nosy" list for the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1184 item that are not already on the "recipients" list of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1185 message. Those users are then appended to the "recipients"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1186 property on the message, so multiple copies of a message
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1187 are never sent to the same user. The journal recorded by
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1188 the hyperdatabase on the "recipients" property then provides
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1189 a log of when the message was sent to whom.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1190
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1191 <h3>7.3. Setting Properties</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1192
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1193 <p>The e-mail interface also provides a simple way to set
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1194 properties on items. At the end of the subject line,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1195 <em>propname</em><tt>=</tt><em>value</em> pairs can be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1196 specified in square brackets, using the same conventions
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1197 as for the <tt>roundup&nbsp;set</tt> shell command.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1198
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1199 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1200 <h2>8. Web User Interface</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1201
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1202 <p>The web interface is provided by a CGI script that can be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1203 run under any web server. A simple web server can easily be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1204 built on the standard <tt>CGIHTTPServer</tt> module, and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1205 should also be included in the distribution for quick
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1206 out-of-the-box deployment.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1207
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1208 <p>The user interface is constructed from a number of template
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1209 files containing mostly HTML. Among the HTML tags in templates
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1210 are interspersed some nonstandard tags, which we use as
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1211 placeholders to be replaced by properties and their values.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1212
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1213 <h3>8.1. Views and View Specifiers</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1214
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1215 <p>There are two main kinds of views: index views and item views.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1216 An index view displays a list of items of a particular class,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1217 optionally sorted and filtered as requested. An item view
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1218 presents the properties of a particular item for editing
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1219 and displays the message spool for the item.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1220
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1221 <p>A <em>view specifier</em> is a string that specifies
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1222 all the options needed to construct a particular view.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1223 It goes after the URL to the Roundup CGI script or the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1224 web server to form the complete URL to a view. When the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1225 result of selecting a link or submitting a form takes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1226 the user to a new view, the Web browser should be redirected
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1227 to a canonical location containing a complete view specifier
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1228 so that the view can be bookmarked.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1229
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1230 <h3>8.2. Displaying Properties</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1231
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1232 <p>Properties appear in the user interface in three contexts:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1233 in indices, in editors, and as filters. For each type of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1234 property, there are several display possibilities. For example,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1235 in an index view, a string property may just be printed as
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1236 a plain string, but in an editor view, that property should
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1237 be displayed in an editable field.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1238
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1239 <p>The display of a property is handled by functions in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1240 a <tt>displayers</tt> module. Each function accepts at
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1241 least three standard arguments -- the database, class name,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1242 and node id -- and returns a chunk of HTML.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1243
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1244 <p>Displayer functions are triggered by <tt>&lt;display&gt;</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1245 tags in templates. The <tt>call</tt> attribute of the tag
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1246 provides a Python expression for calling the displayer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1247 function. The three standard arguments are inserted in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1248 front of the arguments given. For example, the occurrence of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1249
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1250 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1251 > &lt;display call="plain('status', max=30)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1252 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1253
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1254 in a template triggers a call to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1255
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1256 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1257 > plain(db, "issue", 13, "status", max=30)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1258 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1259
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1260 when displaying item 13 in the "issue" class. The displayer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1261 functions can accept extra arguments to further specify
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1262 details about the widgets that should be generated. By defining new
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1263 displayer functions, the user interface can be highly customized.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1264
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1265 <p>Some of the standard displayer functions include:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1266
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1267 <ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1268 <li><strong>plain</strong>: display a String property directly;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1269 display a Date property in a specified time zone with an option
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1270 to omit the time from the date stamp; for a Link or Multilink
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1271 property, display the key strings of the linked nodes (or the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1272 ids if the linked class has no key property)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1273
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1274 <li><strong>field</strong>: display a property like the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1275 <strong>plain</strong> displayer above, but in a text field
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1276 to be edited
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1277
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1278 <li><strong>menu</strong>: for a Link property, display
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1279 a menu of the available choices
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1280
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1281 <li><strong>link</strong>: for a Link or Multilink property,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1282 display the names of the linked nodes, hyperlinked to the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1283 item views on those nodes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1284
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1285 <li><strong>count</strong>: for a Multilink property, display
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1286 a count of the number of links in the list
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1287
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1288 <li><strong>reldate</strong>: display a Date property in terms
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1289 of an interval relative to the current date (e.g. "+ 3w", "- 2d").
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1290
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1291 <li><strong>download</strong>: show a Link("file") or Multilink("file")
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1292 property using links that allow you to download files
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1293
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1294 <li><strong>checklist</strong>: for a Link or Multilink property,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1295 display checkboxes for the available choices to permit filtering
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1296 </ul>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1297
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1298 <h3>8.3. Index Views</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1299
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1300 <p>An index view contains two sections: a filter section
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1301 and an index section.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1302 The filter section provides some widgets for selecting
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1303 which items appear in the index. The index section is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1304 a table of items.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1305
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1306 <h4>8.3.1. Index View Specifiers</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1307
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1308 <p>An index view specifier looks like this (whitespace
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1309 has been added for clarity):
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1310
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1311 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1312 >/issue?status=unread,in-progress,resolved&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1313 topic=security,ui&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1314 :group=+priority&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1315 :sort=-activity&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1316 :filters=status,topic&amp;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1317 :columns=title,status,fixer
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1318 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1319
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1320 <p>The index view is determined by two parts of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1321 specifier: the layout part and the filter part.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1322 The layout part consists of the query parameters that
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1323 begin with colons, and it determines the way that the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1324 properties of selected nodes are displayed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1325 The filter part consists of all the other query parameters,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1326 and it determines the criteria by which nodes
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1327 are selected for display.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1328
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1329 <p>The filter part is interactively manipulated with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1330 the form widgets displayed in the filter section. The
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1331 layout part is interactively manipulated by clicking
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1332 on the column headings in the table.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1333
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1334 <p>The filter part selects the <em>union</em> of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1335 sets of items with values matching any specified Link
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1336 properties and the <em>intersection</em> of the sets
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1337 of items with values matching any specified Multilink
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1338 properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1339
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1340 <p>The example specifies an index of "issue" nodes.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1341 Only items with a "status" of <em>either</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1342 "unread" or "in-progres" or "resolved" are displayed,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1343 and only items with "topic" values including <em>both</em>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1344 "security" <em>and</em> "ui" are displayed. The items
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1345 are grouped by priority, arranged in ascending order;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1346 and within groups, sorted by activity, arranged in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1347 descending order. The filter section shows filters
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1348 for the "status" and "topic" properties, and the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1349 table includes columns for the "title", "status", and
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1350 "fixer" properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1351
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1352 <p>Associated with each item class is a default
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1353 layout specifier. The layout specifier in the above
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1354 example is the default layout to be provided with
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1355 the default bug-tracker schema described above in
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1356 section 4.4.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1357
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1358 <h4>8.3.2. Filter Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1359
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1360 <p>The template for a filter section provides the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1361 filtering widgets at the top of the index view.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1362 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1363 tags are included or omitted depending on whether the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1364 view specifier requests a filter for a particular property.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1365
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1366 <p>Here's a simple example of a filter template.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1367
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1368 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1369 >&lt;property name=status&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1370 &lt;display call="checklist('status')"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1371 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1372 &lt;br&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1373 &lt;property name=priority&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1374 &lt;display call="checklist('priority')"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1375 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1376 &lt;br&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1377 &lt;property name=fixer&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1378 &lt;display call="menu('fixer')"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1379 &lt;/property&gt;</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1380
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1381 <h4>8.3.3. Index Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1382
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1383 <p>The template for an index section describes one row of
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1384 the index table.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1385 Fragments enclosed in <tt>&lt;property&gt;</tt>...<tt>&lt;/property&gt;</tt>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1386 tags are included or omitted depending on whether the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1387 view specifier requests a column for a particular property.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1388 The table cells should contain <tt>&lt;display&gt;</tt> tags
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1389 to display the values of the item's properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1390
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1391 <p>Here's a simple example of an index template.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1392
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1393 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1394 >&lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1395 &lt;property name=title&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1396 &lt;td&gt;&lt;display call="plain('title', max=50)"&gt;&lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1397 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1398 &lt;property name=status&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1399 &lt;td&gt;&lt;display call="plain('status')"&gt;&lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1400 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1401 &lt;property name=fixer&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1402 &lt;td&gt;&lt;display call="plain('fixer')"&gt;&lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1403 &lt;/property&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1404 &lt;/tr&gt;</small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1405
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1406 <h4>8.3.4. Sorting</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1407
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1408 <p>String and Date values are sorted in the natural way.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1409 Link properties are sorted according to the value of the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1410 "order" property on the linked nodes if it is present; or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1411 otherwise on the key string of the linked nodes; or
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1412 finally on the node ids. Multilink properties are
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1413 sorted according to how many links are present.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1414
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1415 <h3>8.4. Item Views</h3>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1416
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1417 <p>An item view contains an editor section and a spool section.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1418 At the top of an item view, links to superseding and superseded
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1419 items are always displayed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1420
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1421 <h4>8.4.1. Item View Specifiers</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1422
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1423 <p>An item view specifier is simply the item's designator:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1424
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1425 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1426 >/patch23
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1427 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1428
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1429 <h4>8.4.2. Editor Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1430
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1431 <p>The editor section is generated from a template
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1432 containing <tt>&lt;display&gt;</tt> tags to insert
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1433 the appropriate widgets for editing properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1434
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1435 <p>Here's an example of a basic editor template.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1436
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1437 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1438 >&lt;table&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1439 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1440 &lt;td colspan=2&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1441 &lt;display call="field('title', size=60)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1442 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1443 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1444 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1445 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1446 &lt;display call="field('fixer', size=30)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1447 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1448 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1449 &lt;display call="menu('status')&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1450 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1451 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1452 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1453 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1454 &lt;display call="field('nosy', size=30)"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1455 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1456 &lt;td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1457 &lt;display call="menu('priority')&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1458 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1459 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1460 &lt;tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1461 &lt;td colspan=2&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1462 &lt;display call="note()"&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1463 &lt;/td&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1464 &lt;/tr&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1465 &lt;/table&gt;
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1466 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1467
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1468 <p>As shown in the example, the editor template can also
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1469 request the display of a "note" field, which is a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1470 text area for entering a note to go along with a change.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1471
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1472 <p>When a change is submitted, the system automatically
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1473 generates a message describing the changed properties.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1474 The message displays all of the property values on the
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1475 item and indicates which ones have changed.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1476 An example of such a message might be this:
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1477
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1478 <blockquote><pre><small
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1479 >title: Polly Parrot is dead
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1480 priority: critical
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1481 status: unread -&gt; in-progress
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1482 fixer: (none)
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1483 keywords: parrot,plumage,perch,nailed,dead
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1484 </small></pre></blockquote>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1485
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1486 <p>If a note is given in the "note" field, the note is
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1487 appended to the description. The message is then added
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1488 to the item's message spool (thus triggering the standard
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1489 detector to react by sending out this message to the nosy list).
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1490
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1491 <h4>8.4.3. Spool Section</h4>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1492
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1493 <p>The spool section lists messages in the item's "messages"
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1494 property. The index of messages displays the "date", "author",
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1495 and "summary" properties on the message nodes, and selecting a
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1496 message takes you to its content.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1497
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1498 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1499 <h2>9. Deployment Scenarios</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1500
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1501 <p>The design described above should be general enough
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1502 to permit the use of Roundup for bug tracking, managing
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1503 projects, managing patches, or holding discussions. By
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1504 using nodes of multiple types, one could deploy a system
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1505 that maintains requirement specifications, catalogs bugs,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1506 and manages submitted patches, where patches could be
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1507 linked to the bugs and requirements they address.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1508
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1509 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1510 <h2>10. Acknowledgements</h2>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1511
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1512 <p>My thanks are due to Christy Heyl for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1513 reviewing and contributing suggestions to this paper
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1514 and motivating me to get it done, and to
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1515 Jesse Vincent, Mark Miller, Christopher Simons,
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1516 Jeff Dunmall, Wayne Gramlich, and Dean Tribble for
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1517 their assistance with the first-round submission.
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1518 </td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1519 </tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1520 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1521
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1522 <p>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1523
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1524 <center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1525 <table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1526 <tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1527 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/index.html"><b>[Home]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1528 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/faq.html"><b>[FAQ]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1529 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/license.html"><b>[License]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1530 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/contest-rules.html"><b>[Rules]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1531 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_config/"><b>[Configure]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1532 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_build/"><b>[Build]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1533 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_test/"><b>[Test]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1534 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/sc_track/"><b>[Track]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1535 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/biblio.html"><b>[Resources]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1536 <td>&nbsp;&nbsp;&nbsp;<a href="http://www.software-carpentry.com/lists/"><b>[Archives]</b></a>&nbsp;&nbsp;&nbsp;</td>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1537 </tr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1538 </table>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1539 </center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1540
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1541 <p><hr>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1542 <center>Last modified 2001/04/06 11:50:59.9063 US/Mountain</center>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1543 </BODY>
5147b4c51fd5 Added the Roundup spec to the new documentation directory.
Richard Jones <richard@users.sourceforge.net>
parents:
diff changeset
1544 </HTML>
Roundup Issue Tracker: http://roundup-tracker.org/