Attachment 'Ref-2.1.py'
Download 1 # -*- coding: iso-8859-1 -*-
2 """
3 MoinMoin - Ref macro, Version 2.1, 27.12.2010
4
5 A macro to cite references from a dictionary page (a ' key:: value' listing).
6
7 Searches one or more dictionary pages to match key (Argument 1, with or without 'key=', quoted string). Matches are included in the page as (1) bookmarks, (2) search key text followed by a footnote link, (3) search key text as the link to the footnote, (4) found reference text only and (5) search key text only.
8
9 The dictionary page is set the RefDict by default, or can be set for (a) the whole page by #pragma ref-dict, or (b) for individual calls by Argument 3.
10
11 For options (2) and (3), search key text will have 'et al' set to Italics (which can be switched off for the whole page by setting #pragma ref-ital off). Also, the year (last word of the key assumed to be a year) can be surrounded in brackets. By default these are just ' (year)' but can be set by #pragma ref-year-bkt to give, for example ', (^)' (where ^ indicates the insertion point for year), if the desired format in the in-text citation differs from the key text in the dictionary.
12
13 Exclamation marks (as WikiName escapes) can be included in the search key, they are removed for matching in dictpage(s) and restored for display under options (2) and (3).
14
15 Additionally superscripting of the numerical link in options (2) and (3) can be switched off and default square brackets are used to distinguish the link from the text. The bracketing can customised using #pragma ref-link-bkt as described above for bracketing the year.
16
17 Option (4) is used to create reference (or further reading) list at any point in the the page, without hyperlinks to or from the citation. Or, just to put the reference into the text perhaps in brackets.
18
19 Option (5) simply inserts the search key text into the page. If reference text is inserted by Option (4) on the same or separate page, inserting references into the text using this macro allows them to be found by searching for the macro. Additionally, if this citation type is set at the page level (by #pragma), it can be temporarily reset to make a footnote list on the page for proof reading purposes.
20
21 These options can be selected for each instance (Argument 2, with or without 'cite=', without quotes, 'fn' 'keyfn' 'bktfn', 'keylk', 'bktlk', 'key' or 'val').
22
23 If 0 or >1 match is found a warning is inserted into the page.
24
25 <<Ref()>>
26
27 Inserts '[citation needed]' to act as a reminder and/or placeholder.
28
29 <<Ref([ref=]"key"[,[cite=]fn|keyfn|bktfn|keylk|bktlk|val|key)[,[dict=]dictpage]])>>
30
31 Argument labels (ref=, cite= and dict=) are optional. The first argument must be ref. Cite and dict arguments are optional and can appear alone, or together in any order. Keywords for cite should not be used for dictpage names.
32
33 ref="key": search key to be matched in dictpage(s), set in single or double quotes. Setting ref="" is equivalent to <<Ref()>> (see above).
34
35 cite=fn: insert a footnote into the page as a numerical link only with the found value (reference text) as the footnote.
36
37 cite=keyfn: insert a footnote into the page as the search key (reference code) followed by a numerical link to the found value (reference text) as the footnote (default).
38
39 cite=bktfn: insert a footnote into the page as the search key (reference code with the year bracketed) followed by a numerical link to the found value (reference text) as a footnote.
40
41 cite=keylk: insert a footnote into the page as the search key (reference code) as the link to the found value (reference text) as the footnote.
42
43 cite=bktlk: insert a footnote into the page as the search key (reference code with the year bracketed) as the link to the found value (reference text) as a footnote.
44
45 cite=val: insert only the found value (reference text) into the page. No link or footnote is generated.
46
47 cite=key: insert only the key (reference code) into the page. No link or footnote is created.
48
49 cite=bkt: insert only the key (reference code with the year bracketed) into the page. No link or footnote is created.
50
51 dictpage(s): dictionary page name. If it starts with ^, a regex of dictpages to include (case sensitive).
52
53 #pragma ref-cite citetype: set the default cite type for the page.
54
55 #pragma ref-year-bkt string: string to bracket year when cite=bktfn, bktlk or bkt, replacing the default ' (^)'; where ^ indicates the insertion point of the year (only one ^ can appear in the string). Set in single or double quotes, or backslash pair.
56
57 #pragma ref-super off: turns of superscripting of numerical forward link to the footnote.
58
59 #pragma ref-link-bkt string: to distinguish the link when ref-super=off, sets string to bracket footnote forward link number for cite=fn, keyfn or bktfn, replacing the default '[^]'; where ^ indicates the insertion point of the link (only one ^ can appear in the string). Set in single or double quotes, or backslash pair.
60
61 #pragma ref-ital off: stops 'et al' in key being converted to italics.
62
63 #pragma ref-dict dictpage(s): dictionary to be used by default for that page, replacing the wiki-wide default of RefDict.
64
65 #pragma ref-debug wiki: shows the wiki markup without processing it.
66
67 #pragma ref-debug html: shows the markup as html.
68
69 @copyright: 2010 Ian Riley <ian.riley@adelaide.edu.au>
70 @licence: GNU GPL, see COPYING for details.
71
72 Developed from:
73
74 (1) MoinMoin - Include macro
75
76 @copyright: 2000-2004 Juergen Hermann <jh@web.de>,
77 2000-2001 Richard Jones <richard@bizarsoftware.com.au>
78 @license: GNU GPL, see COPYING for details.
79
80 (2) http://moinmo.in/FeatureRequests/IncludeMacroInline using code of Junyx 2008-03-24 20:36:25
81
82 """
83
84 Dependencies = ["time"]
85
86 import re
87 from MoinMoin import wikiutil
88 from MoinMoin.Page import Page
89 from MoinMoin.parser.text_moin_wiki import Parser as WikiParser
90
91 # renmove character bracketing 'wrapped' if it is in 'wrappers'
92 def unwrap(wrapped,wrappers):
93 if wrapped[0] in wrappers:
94 last_chr = len(wrapped)-1
95 if wrapped[0] == wrapped[last_chr]:
96 wrapped = wrapped[1:last_chr]
97 return wrapped
98
99 _msg = u'<strong class="error">Ref(): %s</strong>'
100 _msg_bad_arg = _msg % (u'invalid arguments {%s}')
101 _msg_recursion = _msg % (u'recursive use of {%s} forbidden')
102 _msg_match_none = _msg % (u'no match for key={%s} in dict={%s}')
103 _msg_match_many = _msg % (u'%s matches for key={%s} in dict={%s}')
104 _msg_bad_insert = _msg % (u'Single insertion point ^ in {#pragma %s %s} obligatory')
105 _msg_ref_needed = u'[citation needed]'
106
107 _kw_cite = ['fn','keyfn','bktfn','keylk','bktlk','key','bkt','val']
108
109 _df_cite = u'keyfn'
110 _df_dict = u'RefDict'
111
112 _out_fn = u'<<FootNote(%s)>>'
113 _out_keyfn = u'%s' + _out_fn
114 _out_year_bkt = u' (%s)'
115 _out_esc = u'{{{%s}}}'
116 _out_link_bkt = u'[%s]'
117
118 _arg_ref = r'(\s*(ref=)?(?P<quote>[\'"])(?P<ref>.+)?(?P=quote))?'
119 _arg_cite = r'(,\s*(cite=)?(?P<cite>(fn|keyfn|bktfn|keylk|bktlk|key|val)))?'
120 _arg_dict = r'(,\s*(dict=)?(?P<dict>[^,.]+?))?'
121 _args_re_pattern = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_cite, _arg_dict, )
122 _args_re_pattern2 = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_dict, _arg_cite, )
123
124 def execute(macro, text, args_re=re.compile(_args_re_pattern)):
125 request = macro.request
126 _ = request.getText
127
128 def dec_page():
129 # decrease or remove pagelist marker
130 if this_page._macroRef_pagelist[inc_name] > 1:
131 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist[inc_name] - 1
132 else:
133 del this_page._macroRef_pagelist[inc_name]
134
135 # return immediately if getting links for the current page
136 if request.mode_getpagelinks:
137 return ('')
138
139 # parse and check arguments
140 args = text and args_re.match(text)
141 if not args and text != '':
142 args_re = re.compile(_args_re_pattern2)
143 args = text and args_re.match(text)
144 if not args and text != '':
145 return (_msg_bad_arg % (text, ))
146
147 # flag reference needed
148 if text == '':
149 return (_msg_ref_needed)
150 elif args.group('ref') == None:
151 return (_msg_ref_needed)
152
153 # get cite or apply page default
154 cite = args.group('cite')
155 if cite == None:
156 cite = macro.request.getPragma('ref-cite')
157 if not (cite in _kw_cite):
158 cite = _df_cite
159
160 # prepare page
161 result = []
162 result_pending = []
163 this_page = macro.formatter.page
164 if not hasattr(this_page, '_macroRef_pagelist'):
165 this_page._macroRef_pagelist = {}
166
167 # establish dictionary page to be searched
168 dict_name = args.group('dict')
169 if dict_name == None:
170 dict_name = macro.request.getPragma('ref-dict')
171 if dict_name == None:
172 dict_name = _df_dict
173
174 # get list of dictionary pages to search
175 inc_name = wikiutil.AbsPageName(this_page.page_name, dict_name)
176 pagelist = [inc_name]
177 if inc_name.startswith("^"):
178 try:
179 inc_match = re.compile(inc_name)
180 except re.error:
181 pass # treat as plain page name
182 else:
183 # get user filtered readable page list
184 pagelist = request.rootpage.getPageList(filter = inc_match.match)
185
186 ref_key = ''
187 ref_match_count = 0
188 val_end = '\n'
189
190 # iterate over pages
191 for inc_name in pagelist:
192 if not request.user.may.read(inc_name):
193 continue
194 if inc_name in this_page._macroRef_pagelist:
195 dec_page()
196 return (_msg_recursion % (inc_name, ))
197
198 fmt = macro.formatter.__class__(request, is_included=True)
199 fmt._base_depth = macro.formatter._base_depth
200 inc_page = Page(request, inc_name, formatter=fmt)
201 if not inc_page.exists():
202 continue
203 inc_page._macroRef_pagelist = this_page._macroRef_pagelist
204
205 # prepare for ref_key search
206 body = inc_page.get_raw_body() + '\n'
207 ref_pos = 0
208 end_pos = -1
209 ref_found = True
210
211 # need to reset ref_key within loop, as it might have been modified
212 ref_key = args.group('ref')
213
214 # remove any WikiName escape character
215 ref_key = ref_key.replace("!","")
216
217 if ref_key:
218 try:
219 ref_match = re.compile(ref_key + ':: ', re.M).search(body)
220 except re.error:
221 ref_match = re.compile(re.escape(ref_key + ':: '), re.M).search(body)
222 if ref_match:
223 ref_pos = ref_match.end()
224 else:
225 ref_found = False
226
227 if val_end:
228 try:
229 end_match = re.compile(val_end, re.M).search(body, ref_pos)
230 except re.error:
231 end_match = re.compile(re.escape(val_end), re.M).search(body, ref_pos)
232 if end_match:
233 end_pos = end_match.start()
234 else:
235 ref_found = False
236
237 if ref_found:
238 inc_page.set_raw_body(body[ref_pos:end_pos], modified=True)
239 ref_match_count = ref_match_count + 1
240
241 #TODO: loop back over remainder of body to find duplicate keys to allow user to be warned.
242 # Perhaps is would be better to use WikiDict calls to get the match,
243 # but I think this can only find the first match, not duplicates.
244
245 # set or increment pagelist marker
246 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist.get(inc_name, 0) + 1
247
248 # need to reset ref_key within loop, as it might have been modified
249 ref_key = args.group('ref')
250
251 # make et al italic unless #pragma ref-ital off
252 if macro.request.getPragma('ref-ital') != 'off':
253 ref_key = ref_key.replace("et al","''et al''")
254
255 # bracket year (last 'word' of ref key) for cite=bktfn, bktlk or bkt
256 if cite in ['bktfn', 'bktlk', 'bkt']:
257 ref_key = ref_key.rstrip()
258 ref_len = len(ref_key)
259 year_pos = ref_key.rfind(' ')
260 year_bkt = _out_year_bkt
261 if macro.request.getPragma('ref-year-bkt') != None:
262 #TODO check if the escape call really needed or does getPragma handle the html risk
263 year_bkt = wikiutil.escape(macro.request.getPragma('ref-year-bkt'))
264 if year_bkt.count("^") != 1:
265 dec_page()
266 return (_msg_bad_insert % ('ref-year-bkt', year_bkt))
267 year_bkt = year_bkt.replace("_"," ").replace("^","%s",1)
268 year_bkt = unwrap(year_bkt,"\\\"'")
269 year_str = year_bkt % (ref_key[year_pos+1:ref_len])
270 ref_key = ref_key[0:year_pos] + year_str
271
272 if ref_found:
273 # insert the ref value into the page as a footnote only
274 if cite == 'fn':
275 result_pending = _out_fn % (inc_page.get_body())
276
277 # insert the ref key (modified) into the page followed by the ref value into the page as a footnote
278 elif cite in ['keyfn','bktfn','keylk','bktlk']:
279 result_pending = _out_keyfn % (ref_key, inc_page.get_body())
280
281 # insert the ref key into the page only
282 elif cite in ['key', 'bkt']:
283 result_pending = ref_key
284
285 # insert the ref value into the page only
286 elif cite == 'val':
287 result_pending = inc_page.get_body()
288
289
290 if macro.request.getPragma('ref-debug') == 'wiki':
291 result_pending = _out_esc % (result_pending)
292
293 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
294
295 # post formating of html citation and link
296 if cite in ('keylk','bktlk'):
297 ref_key = ref_key.replace("!","")
298 ref_key = ref_key.replace("''et al''","<em>et al</em>")
299 result_pending = (result_pending.replace("<sup>","")
300 .replace("</sup>","")
301 .replace(ref_key,"")
302 .replace("</a>","")
303 .rstrip(" 0123456789") + ref_key + "</a>")
304
305 if cite in ('fn','keyfn','bktfn'):
306 if macro.request.getPragma('ref-super') == 'off':
307 link_bkt = _out_link_bkt
308 if macro.request.getPragma('ref-link-bkt') != None:
309 #TODO check if the escape call really needed or does getPragma handle the html risk
310 link_bkt = wikiutil.escape(macro.request.getPragma('ref-link-bkt'))
311 if link_bkt.count("^") != 1:
312 dec_page()
313 return (_msg_bad_insert % ('ref-link-bkt', link_bkt, ))
314 link_bkt = (unwrap(link_bkt,"\\\"'").replace("_"," ")
315 .replace("^","%s",1))
316 t = tuple(result_pending.replace("<sup>","<>")
317 .replace("</a>","</a><>")
318 .replace("</sup>","")
319 .split("<>"))
320 result_pending = ('%s' + link_bkt + '%s') % (t[0],t[1],t[2])
321
322 if macro.request.getPragma('ref-debug') == 'html':
323 result_pending = _out_esc % (result_pending)
324 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
325
326 result.append(result_pending)
327
328 # decrease or remove pagelist marker
329 dec_page()
330
331 # no match and last page in list, so insert warning message
332 # need to reset ref_key within loop, as it might have been modified
333 ref_key = args.group('ref')
334 if ref_match_count == 0:
335 result.append(_msg_match_none % (ref_key, dict_name, ))
336 elif ref_match_count > 1:
337 result.append(_msg_match_many % (ref_match_count, ref_key, dict_name, ))
338
339 return ''.join(result)
You are not allowed to attach a file to this page.