Attachment 'Ref-2.4.py'
Download 1 # -*- coding: iso-8859-1 -*-
2 """
3 MoinMoin - Ref macro, Version 2.4, 10.10.2012
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', 'val' or 'bkt').
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|bkt)[,[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 History
73
74 Version 2.4 - 10.10.2012: forced all search strings to be escaped for regex specials, to allow for example the inclusion of a '?' in the date of the reference key.
75
76 Version 2.3.- 09.05.2011: minor bug fix
77
78 Version 2.2 - 12.01.2011: streamlined the unwrap function.
79
80 Version 2.1 - 27.12.2010: some html security improvements.
81
82 Version 2.0 - 25.12.2010: dict specification optional (for cleaner markup), added key linking and display, added additional pragma to set cite type for the whole page (again for cleaner markup), to turn off superscripting and to add alternative demarkation of numbered links and to change year demarkation text. Macro call without arguments to raise a citation needed reminder.
83
84 Version 1.0 - 19.12.2010: initial version.
85
86 Developed from:
87
88 (1) MoinMoin - Include macro
89
90 @copyright: 2000-2004 Juergen Hermann <jh@web.de>,
91 2000-2001 Richard Jones <richard@bizarsoftware.com.au>
92 @license: GNU GPL, see COPYING for details.
93
94 (2) http://moinmo.in/FeatureRequests/IncludeMacroInline using code of Junyx 2008-03-24 20:36:25
95
96 """
97
98 Dependencies = ["time"]
99
100 import re
101 from MoinMoin import wikiutil
102 from MoinMoin.Page import Page
103 from MoinMoin.parser.text_moin_wiki import Parser as WikiParser
104
105 # remove character bracketing 'wrapped', if it is in 'wrappers'
106 def unwrap(wrapped,wrappers):
107 if (wrapped[0] in wrappers) and wrapped.endswith(wrapped[0]):
108 wrapped = wrapped[1:-1]
109 return wrapped
110
111 _msg = u'<strong class="error">Ref(): %s</strong>'
112 _msg_bad_arg = _msg % (u'invalid arguments {%s}')
113 _msg_recursion = _msg % (u'recursive use of {%s} forbidden')
114 _msg_match_none = _msg % (u'no match for key={%s} in dict={%s}')
115 _msg_match_many = _msg % (u'%s matches for key={%s} in dict={%s}')
116 _msg_bad_insert = _msg % (u'Single insertion point ^ in {#pragma %s %s} obligatory')
117 _msg_ref_needed = u'[citation needed]'
118
119 _kw_cite = ['fn','keyfn','bktfn','keylk','bktlk','key','val','bkt']
120
121 _df_cite = u'keyfn'
122 _df_dict = u'RefDict'
123
124 _out_fn = u'<<FootNote(%s)>>'
125 _out_keyfn = u'%s' + _out_fn
126 _out_year_bkt = u' (%s)'
127 _out_esc = u'{{{%s}}}'
128 _out_link_bkt = u'[%s]'
129
130 _arg_ref = r'(\s*(ref=)?(?P<quote>[\'"])(?P<ref>.+)?(?P=quote))?'
131 _arg_cite = r'(,\s*(cite=)?(?P<cite>(fn|keyfn|bktfn|keylk|bktlk|key|val|bkt)))?'
132 _arg_dict = r'(,\s*(dict=)?(?P<dict>[^,.]+?))?'
133 _args_re_pattern = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_cite, _arg_dict, )
134 _args_re_pattern2 = r'^%s((%s)?%s)?$' % (_arg_ref, _arg_dict, _arg_cite, )
135
136 def execute(macro, text, args_re=re.compile(_args_re_pattern)):
137 request = macro.request
138 _ = request.getText
139
140 def dec_page():
141 # decrease or remove pagelist marker
142 if this_page._macroRef_pagelist[inc_name] > 1:
143 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist[inc_name] - 1
144 else:
145 del this_page._macroRef_pagelist[inc_name]
146
147 # return immediately if getting links for the current page
148 if request.mode_getpagelinks:
149 return ('')
150
151 # parse and check arguments
152 args = text and args_re.match(text)
153 if not args and text != '':
154 args_re = re.compile(_args_re_pattern2)
155 args = text and args_re.match(text)
156 if not args and text != '':
157 return (_msg_bad_arg % (text, ))
158
159 # flag reference needed
160 if text == '':
161 return (_msg_ref_needed)
162 elif args.group('ref') == None:
163 return (_msg_ref_needed)
164
165 # get cite or apply page default
166 cite = args.group('cite')
167 if cite == None:
168 cite = macro.request.getPragma('ref-cite')
169 if not (cite in _kw_cite):
170 cite = _df_cite
171
172 # prepare page
173 result = []
174 result_pending = []
175 this_page = macro.formatter.page
176 if not hasattr(this_page, '_macroRef_pagelist'):
177 this_page._macroRef_pagelist = {}
178
179 # establish dictionary page to be searched
180 dict_name = args.group('dict')
181 if dict_name == None:
182 dict_name = macro.request.getPragma('ref-dict')
183 if dict_name == None:
184 dict_name = _df_dict
185
186 # get list of dictionary pages to search
187 inc_name = wikiutil.AbsPageName(this_page.page_name, dict_name)
188 pagelist = [inc_name]
189 if inc_name.startswith("^"):
190 try:
191 inc_match = re.compile(inc_name)
192 except re.error:
193 pass # treat as plain page name
194 else:
195 # get user filtered readable page list
196 pagelist = request.rootpage.getPageList(filter = inc_match.match)
197
198 ref_key = ''
199 ref_match_count = 0
200 val_end = '\n'
201
202 # iterate over pages
203 for inc_name in pagelist:
204 if not request.user.may.read(inc_name):
205 continue
206 if inc_name in this_page._macroRef_pagelist:
207 dec_page()
208 return (_msg_recursion % (inc_name, ))
209
210 fmt = macro.formatter.__class__(request, is_included=True)
211 fmt._base_depth = macro.formatter._base_depth
212 inc_page = Page(request, inc_name, formatter=fmt)
213 if not inc_page.exists():
214 continue
215 inc_page._macroRef_pagelist = this_page._macroRef_pagelist
216
217 # prepare for ref_key search
218 body = inc_page.get_raw_body() + '\n'
219 ref_pos = 0
220 end_pos = -1
221 ref_found = True
222
223 # need to reset ref_key within loop, as it might have been modified
224 ref_key = args.group('ref')
225
226 # remove any WikiName escape character
227 ref_key = ref_key.replace("!","")
228
229 if ref_key:
230 #try:
231 # ref_match = re.compile(ref_key + ':: ', re.M).search(body)
232 #except re.error:
233 ref_match = re.compile(re.escape(ref_key + ':: '), re.M).search(body)
234 if ref_match:
235 ref_pos = ref_match.end()
236 else:
237 ref_found = False
238
239 if val_end:
240 #try:
241 # end_match = re.compile(val_end, re.M).search(body, ref_pos)
242 #except re.error:
243 end_match = re.compile(re.escape(val_end), re.M).search(body, ref_pos)
244 if end_match:
245 end_pos = end_match.start()
246 else:
247 ref_found = False
248
249 if ref_found:
250 inc_page.set_raw_body(body[ref_pos:end_pos], modified=True)
251 ref_match_count = ref_match_count + 1
252
253 #TODO: loop back over remainder of body to find duplicate keys to allow user to be warned.
254 # Perhaps is would be better to use WikiDict calls to get the match,
255 # but I think this can only find the first match, not duplicates.
256
257 # set or increment pagelist marker
258 this_page._macroRef_pagelist[inc_name] = this_page._macroRef_pagelist.get(inc_name, 0) + 1
259
260 # need to reset ref_key within loop, as it might have been modified
261 ref_key = args.group('ref')
262
263 # make et al italic unless #pragma ref-ital off
264 if macro.request.getPragma('ref-ital') != 'off':
265 ref_key = ref_key.replace("et al","''et al''")
266
267 # bracket year (last 'word' of ref key) for cite=bktfn, bktlk or bkt
268 if cite in ['bktfn', 'bktlk', 'bkt']:
269 ref_key = ref_key.rstrip()
270 ref_len = len(ref_key)
271 year_pos = ref_key.rfind(' ')
272 year_bkt = _out_year_bkt
273 if macro.request.getPragma('ref-year-bkt') != None:
274 #TODO check if the escape call really needed or does getPragma handle the html risk
275 year_bkt = wikiutil.escape(macro.request.getPragma('ref-year-bkt'))
276 if year_bkt.count("^") != 1:
277 dec_page()
278 return (_msg_bad_insert % ('ref-year-bkt', year_bkt))
279 year_bkt = year_bkt.replace("_"," ").replace("^","%s",1)
280 year_bkt = unwrap(year_bkt,"\\\"'")
281 year_str = year_bkt % (ref_key[year_pos+1:ref_len])
282 ref_key = ref_key[0:year_pos] + year_str
283
284 if ref_found:
285 # insert the ref value into the page as a footnote only
286 if cite == 'fn':
287 result_pending = _out_fn % (inc_page.get_body())
288
289 # insert the ref key (modified) into the page followed by the ref value into the page as a footnote
290 elif cite in ['keyfn','bktfn','keylk','bktlk']:
291 result_pending = _out_keyfn % (ref_key, inc_page.get_body())
292
293 # insert the ref key into the page only
294 elif cite in ['key', 'bkt']:
295 result_pending = ref_key
296
297 # insert the ref value into the page only
298 elif cite == 'val':
299 result_pending = inc_page.get_body()
300
301
302 if macro.request.getPragma('ref-debug') == 'wiki':
303 result_pending = _out_esc % (result_pending)
304
305 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
306
307 # post formating of html citation and link
308 if cite in ('keylk','bktlk'):
309 ref_key = ref_key.replace("!","")
310 ref_key = ref_key.replace("''et al''","<em>et al</em>")
311 result_pending = (result_pending.replace("<sup>","")
312 .replace("</sup>","")
313 .replace(ref_key,"")
314 .replace("</a>","")
315 .rstrip(" 0123456789") + ref_key + "</a>")
316
317 if cite in ('fn','keyfn','bktfn'):
318 if macro.request.getPragma('ref-super') == 'off':
319 link_bkt = _out_link_bkt
320 if macro.request.getPragma('ref-link-bkt') != None:
321 #TODO check if the escape call really needed or does getPragma handle the html risk
322 link_bkt = wikiutil.escape(macro.request.getPragma('ref-link-bkt'))
323 if link_bkt.count("^") != 1:
324 dec_page()
325 return (_msg_bad_insert % ('ref-link-bkt', link_bkt, ))
326 link_bkt = (unwrap(link_bkt,"\\\"'").replace("_"," ")
327 .replace("^","%s",1))
328 t = tuple(result_pending.replace("<sup>","<>")
329 .replace("</a>","</a><>")
330 .replace("</sup>","")
331 .split("<>"))
332 result_pending = ('%s' + link_bkt + '%s') % (t[0],t[1],t[2])
333
334 if macro.request.getPragma('ref-debug') == 'html':
335 result_pending = _out_esc % (result_pending)
336 result_pending = wikiutil.renderText(request, WikiParser, result_pending).rstrip(' ')
337
338 result.append(result_pending)
339
340 # decrease or remove pagelist marker
341 dec_page()
342
343 # no match and last page in list, so insert warning message
344 # need to reset ref_key within loop, as it might have been modified
345 ref_key = args.group('ref')
346 if ref_match_count == 0:
347 result.append(_msg_match_none % (ref_key, dict_name, ))
348 elif ref_match_count > 1:
349 result.append(_msg_match_many % (ref_match_count, ref_key, dict_name, ))
350
351 return ''.join(result)
You are not allowed to attach a file to this page.