bin/list-dispatch-commands.py

   1 #!/usr/bin/env python3
   2
   3 # This file is part of the LibreOffice project.
   4 #
   5 # This Source Code Form is subject to the terms of the Mozilla Public
   6 # License, v. 2.0. If a copy of the MPL was not distributed with this
   7 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8
   9 """
  10 Script to generate https://wiki.documentfoundation.org/Development/DispatchCommands
  11 3 types of source files are scanned to identify and describe a list of relevant UNO commands:
  12 - .hxx files: containing the symbolic and numeric id's, and the respective modes and groups
  13 - .xcu files; containing several english labels as they appear in menus or tooltips
  14 - .sdi files: containing a list of potential arguments for the commands, and their types
  15 """
  16
  17 import os
  18
  19 # It is assumed that the script is called from $BUILDDIR;
  20 # and __file__ refers to the script location in $SRCDIR.
  21 # This allows to use it in separate builddir configuration.
  22 srcdir = os.path.dirname(os.path.realpath(__file__)) + '/..' # go up from /bin
  23 builddir = os.getcwd()
  24
  25 REPO = 'https://opengrok.libreoffice.org/xref/core'
  26
  27 BLACKLIST = ('_SwitchViewShell0', '_SwitchViewShell1', '_SwitchViewShell2', '_SwitchViewShell3', '_SwitchViewShell4')
  28
  29 XCU_DIR = srcdir + '/officecfg/registry/data/org/openoffice/Office/UI/'
  30 XCU_FILES = (   XCU_DIR + 'BasicIDECommands.xcu',
  31                 XCU_DIR + 'CalcCommands.xcu',
  32                 XCU_DIR + 'ChartCommands.xcu',
  33                 XCU_DIR + 'DbuCommands.xcu',
  34                 XCU_DIR + 'DrawImpressCommands.xcu',
  35                 XCU_DIR + 'GenericCommands.xcu',
  36                 XCU_DIR + 'MathCommands.xcu',
  37                 XCU_DIR + 'ReportCommands.xcu',
  38                 XCU_DIR + 'WriterCommands.xcu')
  39
  40 HXX_DIR = builddir + '/workdir/SdiTarget/'
  41 HXX_FILES = (   HXX_DIR + 'basctl/sdi/basslots.hxx',
  42                 HXX_DIR + 'sc/sdi/scslots.hxx',
  43                 HXX_DIR + 'sd/sdi/sdgslots.hxx',
  44                 HXX_DIR + 'sd/sdi/sdslots.hxx',
  45                 HXX_DIR + 'sfx2/sdi/sfxslots.hxx',
  46                 HXX_DIR + 'starmath/sdi/smslots.hxx',
  47                 HXX_DIR + 'svx/sdi/svxslots.hxx',
  48                 HXX_DIR + 'sw/sdi/swslots.hxx')
  49
  50 SDI_FILES = (   srcdir + '/sc/sdi/scalc.sdi',
  51                 srcdir + '/sd/sdi/sdraw.sdi',
  52                 srcdir + '/sfx2/sdi/sfx.sdi',
  53                 srcdir + '/starmath/sdi/smath.sdi',
  54                 srcdir + '/svx/sdi/svx.sdi',
  55                 srcdir + '/sw/sdi/swriter.sdi')
  56
  57 # Category is defined by the 1st file where the command has been found. Precedence: 1. xcu, 2. hxx, 3. sdi.
  58 MODULES = {'BasicIDE':      'Basic IDE, Forms, Dialogs',
  59             'Calc':         'Calc',
  60             'Chart':        'Charts',
  61             'Dbu':          'Base',
  62             'DrawImpress':  'Draw / Impress',
  63             'Generic':      'Global',
  64             'Math':         'Math',
  65             'Report':       'Reports',
  66             'Writer':       'Writer',
  67             'basslots':     'Basic IDE, Forms, Dialogs',
  68             'scslots':      'Calc',
  69             'sdgslots':     'Draw / Impress',
  70             'sdslots':      'Draw / Impress',
  71             'sfxslots':     'Global',
  72             'smslots':      'Math',
  73             'svxslots':     'Global',
  74             'swslots':      'Writer',
  75             'scalc':        'Calc',
  76             'sdraw':        'Draw / Impress',
  77             'sfx':          'Global',
  78             'smath':        'Math',
  79             'svx':          'Global',
  80             'swriter':      'Writer'}
  81
  82 def newcommand(unocommand):
  83     cmd = {'unocommand': unocommand,
  84            'module': '',
  85            'xcufile': -1,
  86            'xculinenumber': 0,
  87            'xcuoccurs': 0,
  88            'label': '',
  89            'contextlabel': '',
  90            'tooltiplabel': '',
  91            'hxxfile': -1,
  92            'hxxoccurs': 0,
  93            'hxxlinenumber': 0,
  94            'resourceid': '',
  95            'numericid': '',
  96            'group': '',
  97            'sdifile': -1,
  98            'sdioccurs': 0,
  99            'sdilinenumber': 0,
 100            'mode': '',
 101            'arguments': ''}
 102     return cmd
 103
 104 def get_uno(cmd):
 105     if cmd.startswith('FocusToFindbar'):
 106         cmd = 'vnd.sun.star.findbar:' + cmd
 107     else:
 108         cmd = '.uno:' + cmd
 109     return cmd
 110
 111 def analyze_xcu(all_commands):
 112     for filename in XCU_FILES:
 113         ln = 0
 114         with open(filename) as fh:
 115             popups = False
 116             for line in fh:
 117                 ln += 1
 118                 if '<node oor:name="Popups">' in line:
 119                     popups = True
 120                     continue
 121                 elif popups is True and line == '    </node>':
 122                     popups = False
 123                     continue
 124                 if '<node oor:name=".uno:' not in line and '<node oor:name="vnd.' not in line:
 125                     continue
 126
 127                 cmdln = ln
 128                 tmp = line.split('"')
 129                 command_name = tmp[1]
 130
 131                 while '</node>' not in line:
 132                     try:
 133                         line = next(fh)
 134                         ln += 1
 135                     except StopIteration:
 136                         print("Warning: couldn't find '</node>' line in %s" % filename,
 137                             file=sys.stderr)
 138                         break
 139                     if '<prop oor:name="Label"' in line:
 140                         label = 'label'
 141                     elif '<prop oor:name="ContextLabel"' in line:
 142                         label = 'contextlabel'
 143                     elif '<prop oor:name="TooltipLabel"' in line:
 144                         label = 'tooltiplabel'
 145                     elif '<value xml:lang="en-US">' in line:
 146                         labeltext = line.replace('<value xml:lang="en-US">', '').replace('</value>', '').strip()
 147
 148                 if popups is False:
 149                     if command_name not in all_commands:
 150                         all_commands[command_name] = newcommand(command_name)
 151                     #
 152                     all_commands[command_name]['xcufile'] = XCU_FILES.index(filename)
 153                     all_commands[command_name]['xculinenumber'] = cmdln
 154                     all_commands[command_name][label] = labeltext.replace('~', '')
 155                     all_commands[command_name]['xcuoccurs'] += 1
 156
 157
 158 def analyze_hxx(all_commands):
 159     for filename in HXX_FILES:
 160         with open(filename) as fh:
 161             ln = 0
 162             mode = ''
 163             for line in fh:
 164                 ln += 1
 165                 if not line.startswith('// Slot Nr. '):
 166                     continue
 167
 168                 # Parse sth like
 169                 # // Slot Nr. 0 : 5502
 170                 # SFX_NEW_SLOT_ARG( basctl_Shell,SID_SAVEASDOC,SfxGroupId::Document,
 171                 cmdln = ln
 172                 tmp = line.split(':')
 173                 command_id = tmp[1].strip()
 174
 175                 line = next(fh)
 176                 ln += 1
 177                 tmp = line.split(',')
 178                 command_rid = tmp[1]
 179                 command_group = tmp[2].split('::')[1]
 180
 181                 next(fh)
 182                 ln += 1
 183                 next(fh)
 184                 ln += 1
 185                 line = next(fh)
 186                 ln += 1
 187                 mode += 'U' if 'AUTOUPDATE' in line else ''
 188                 mode += 'M' if 'MENUCONFIG' in line else ''
 189                 mode += 'T' if 'TOOLBOXCONFIG' in line else ''
 190                 mode += 'A' if 'ACCELCONFIG' in line else ''
 191
 192                 next(fh)
 193                 ln += 1
 194                 next(fh)
 195                 ln += 1
 196                 line = next(fh)
 197                 ln += 1
 198                 if '"' not in line:
 199                     line = next(fh)
 200                 tmp = line.split('"')
 201                 try:
 202                     command_name = get_uno(tmp[1])
 203                 except IndexError:
 204                     print("Warning: expected \" in line '%s' from file %s" % (line.strip(), filename),
 205                             file=sys.stderr)
 206                     command_name = '.uno:'
 207
 208                 if command_name not in all_commands:
 209                     all_commands[command_name] = newcommand(command_name)
 210                 #
 211                 all_commands[command_name]['hxxfile'] = HXX_FILES.index(filename)
 212                 all_commands[command_name]['hxxlinenumber'] = cmdln
 213                 all_commands[command_name]['numericid'] = command_id
 214                 all_commands[command_name]['resourceid'] = command_rid
 215                 all_commands[command_name]['group'] = command_group
 216                 all_commands[command_name]['mode'] = mode
 217                 all_commands[command_name]['hxxoccurs'] += 1
 218                 mode = ''
 219
 220
 221 def analyze_sdi(all_commands):
 222     def SplitArguments(params):
 223         # Split a string like : SfxStringItem Name SID_CHART_NAME,SfxStringItem Range SID_CHART_SOURCE,SfxBoolItem ColHeaders FN_PARAM_1,SfxBoolItem RowHeaders FN_PARAM_2
 224         # in : Name (string)\nRange (string)\nRowHeaders (bool)
 225         CR = '<br>'
 226         split = ''
 227         params = params.strip(' ,').replace(', ', ',')  #   At least 1 case of ', ' in svx/sdi/svx.sdi line 3592
 228         if len(params) > 0:
 229             for p in params.split(','):
 230                 if len(split) > 0:
 231                     split += CR
 232                 elems = p.split()
 233                 if len(elems) >= 2:
 234                     split += elems[1]
 235                     if 'String' in elems[0]:
 236                         split += ' (string)'
 237                     elif 'Bool' in elems[0]:
 238                         split += ' (bool)'
 239                     elif 'Int16' in elems[0]:
 240                         split += ' (integer)'
 241                     elif 'Int32' in elems[0]:
 242                         split += ' (long)'
 243                     else:
 244                         split += ' (' + elems[0].replace('Sfx', '').replace('Svx', '').replace('Item', '').lower() + ')'
 245         return split
 246
 247     for filename in SDI_FILES:
 248         ln = 0
 249         comment, square, command, param = False, False, False, False
 250         with open(filename) as fh:
 251             for line in fh:
 252                 ln += 1
 253                 line = line.replace('  ', ' ').strip()       #   Anomaly met in svx/sdi/svx.sdi
 254                 if line.startswith('//'):
 255                     pass
 256                 elif comment is False and line.startswith('/*') and not line.endswith('*/'):
 257                     comment = True
 258                 elif comment is True and line.endswith('*/'):
 259                     comment = False
 260                 elif comment is False and line.startswith('/*') and line.endswith('*/'):
 261                     pass
 262                 elif comment is True:
 263                     pass
 264                 elif square is False and line.startswith('['):
 265                     square = True
 266                     mode = ''
 267                     command = False
 268                 elif square is True and line.endswith(']'):
 269                     all_commands[command_name]['mode'] = mode
 270                     square = False
 271                 elif square is True:
 272                     squaremode = line.strip(',;').split()
 273                     if len(squaremode) == 3:
 274                         mode += 'U' if squaremode[0] == 'AutoUpdate' and squaremode[2] == 'TRUE' else ''
 275                         mode += 'M' if squaremode[0] == 'MenuConfig' and squaremode[2] == 'TRUE' else ''
 276                         mode += 'T' if squaremode[0] == 'ToolBoxConfig' and squaremode[2] == 'TRUE' else ''
 277                         mode += 'A' if squaremode[0] == 'AccelConfig' and squaremode[2] == 'TRUE' else ''
 278                 elif comment is False and square is False and command is False and len(line) == 0:
 279                     pass
 280                 elif command is False:
 281                     command_name = get_uno(line.split(' ')[1])
 282                     if command_name not in all_commands:
 283                         all_commands[command_name] = newcommand(command_name)
 284                     all_commands[command_name]['sdifile'] = SDI_FILES.index(filename)
 285                     all_commands[command_name]['sdilinenumber'] = ln
 286                     all_commands[command_name]['sdioccurs'] += 1
 287                     if len(all_commands[command_name]['resourceid']) == 0:
 288                         all_commands[command_name]['resourceid'] = line.split(' ')[2]
 289                     command = True
 290                 elif command is True and (line == '' or line == '()'):
 291                     command = False
 292                 elif command is True and (param is True or line.startswith('(')) and line.endswith(')'):
 293                     if param:
 294                         params += line.strip(' (),').replace(', ', ',') #   At least 1 case of ", " in svx/sdi/svx.sdi line 8767
 295                                                                         #   At least 1 case of "( " in sw/sdi/swriter.sdi line 5477
 296                     else:
 297                         params = line.strip(' (),').replace(', ', ',')  #   At least 1 case in sw/sdi/swriter.sdi line 7083
 298                     all_commands[command_name]['arguments'] = SplitArguments(params)
 299                     command = False
 300                     param = False
 301                 elif command is True and line.startswith('('):  #   Arguments always on 1 line, except in some cases (cfr.BasicIDEAppear)
 302                     params = line.strip(' ()').replace(', ', ',')
 303                     param = True
 304                 elif param is True:
 305                     params += line
 306
 307
 308 def categorize(all_commands):
 309     # Clean black listed commands
 310     for command in BLACKLIST:
 311         cmd = get_uno(command)
 312         if cmd in all_commands:
 313             del all_commands[cmd]
 314     # Set category based on the file name where the command was found first
 315     for cmd in all_commands:
 316         command = all_commands[cmd]
 317         cxcu, chxx, csdi = '', '', ''
 318         fxcu = command['xcufile']
 319         if fxcu > -1:
 320             cxcu = os.path.basename(XCU_FILES[fxcu]).split('.')[0].replace('Commands', '')
 321         fhxx = command['hxxfile']
 322         if fhxx > -1:
 323             chxx = os.path.basename(HXX_FILES[fhxx]).split('.')[0]
 324         fsdi = command['sdifile']
 325         if fsdi > -1:
 326             csdi = os.path.basename(SDI_FILES[fsdi]).split('.')[0]
 327         # General rule:
 328         if len(cxcu) > 0:
 329             cat = cxcu
 330         elif len(chxx) > 0:
 331             cat = chxx
 332         else:
 333             cat = csdi
 334         # Exceptions on general rule
 335         if cat == 'Generic' and chxx == 'basslots':
 336             cat = chxx
 337         command['module'] = MODULES[cat]
 338
 339
 340 def print_output(all_commands):
 341     def longest(*args):
 342         # Return the longest string among the arguments
 343         return max(args, key = len)
 344     #
 345     def sources(cmd):
 346         # Build string identifying the sources
 347         xcufile, xculinenumber, hxxfile, hxxlinenumber, sdifile, sdilinenumber = 2, 3, 8, 10, 14, 16
 348         src = ''
 349         if cmd[xcufile] >= 0:
 350             src += '[' + REPO + XCU_FILES[cmd[xcufile]].replace(srcdir, '') + '#' + str(cmd[xculinenumber]) + ' XCU]'
 351         if cmd[sdifile] >= 0:
 352             src += ' [' + REPO + SDI_FILES[cmd[sdifile]].replace(srcdir, '') + '#' + str(cmd[sdilinenumber]) + ' SDI]'
 353         if cmd[hxxfile] >= 0:
 354             file = str(cmd[hxxfile] + 1 + len(XCU_FILES) + len(SDI_FILES))
 355             src += ' <span title="File (' + file + ') line ' + str(cmd[hxxlinenumber]) + '">[[#hxx' + file + '|HXX]]</span>'
 356         return src.strip()
 357     #
 358     # Sort by category and command name
 359     commands_list = []
 360     for cmd in all_commands:
 361         cmdlist = tuple(all_commands[cmd].values())
 362         commands_list.append(cmdlist)
 363     sorted_by_command = sorted(commands_list, key = lambda cmd: cmd[0])
 364     sorted_by_module = sorted(sorted_by_command, key = lambda cmd: cmd[1])
 365     #
 366     # Produce tabular output
 367     unocommand, module, label, contextlabel, tooltiplabel, arguments, resourceid, numericid, group, mode = 0, 1, 5, 6, 7, 18, 11, 12, 13, 17
 368     lastmodule = ''
 369     for cmd in sorted_by_module:
 370         # Format bottom and header
 371         if lastmodule != cmd[module]:
 372             if len(lastmodule) > 0:
 373                 print('\n|-\n|}\n')
 374                 print('</small>')
 375             lastmodule = cmd[module]
 376             print('=== %s ===\n' % lastmodule)
 377             print('<small>')
 378             print('{| class="wikitable sortable" width="100%"')
 379             print('|-')
 380             print('! scope="col" | Dispatch command')
 381             print('! scope="col" | Description')
 382             print('! scope="col" | Group')
 383             print('! scope="col" | Arguments')
 384             print('! scope="col" | Internal<br>name (value)')
 385             print('! scope="col" | Mode')
 386             print('! scope="col" | Source<br>files')
 387         print('|-\n')
 388         print('| ' + cmd[unocommand].replace('&amp;', '\n&'))
 389         print('| ' + longest(cmd[label], cmd[contextlabel], cmd[tooltiplabel]))
 390         print('| ' + cmd[group])
 391         print('| ' + cmd[arguments].replace('\\n', '\n'))
 392         if len(cmd[numericid]) == 0:
 393             print('| ' + cmd[resourceid])
 394         else:
 395             print('| ' + cmd[resourceid] + ' (' + cmd[numericid] + ')')
 396         print('| ' + cmd[mode])
 397         print('| ' + sources(cmd))
 398     print('|-\n|}\n')
 399     # List the source files
 400     print('== Source files ==\n')
 401     fn = 0
 402     for i in range(len(XCU_FILES)):
 403         fn += 1
 404         print(f'({fn}) {REPO}{XCU_FILES[i]}\n'.replace(srcdir, ''))
 405     print('\n')
 406     for i in range(len(SDI_FILES)):
 407         fn += 1
 408         print(f'({fn}) {REPO}{SDI_FILES[i]}\n'.replace(srcdir, ''))
 409     print('\n')
 410     for i in range(len(HXX_FILES)):
 411         fn += 1
 412         print(f'<span id="hxx{fn}">({fn}) {HXX_FILES[i]}</span>\n'.replace(builddir, ''))
 413     print('</small>')
 414
 415
 416 def main():
 417     all_commands = {}
 418
 419     analyze_xcu(all_commands)
 420
 421     analyze_hxx(all_commands)
 422
 423     analyze_sdi(all_commands)
 424
 425     categorize(all_commands)
 426
 427     print_output(all_commands)
 428
 429 if __name__ == '__main__':
 430     main()