asn2md.py

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# asn1-doxygen-filter is an extension to the Doxygen utility for creating
# documents from ASN.1 files
#
# Copyright 2017 OnBoard Security, Inc.
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal 
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in 
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
# IMPLIED, INCLUDING BUTNOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
# FITNESS FOR A PARTICULAR PURPOSE ANDNONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
# SOFTWARE.

import argparse # parse arguments
import os.path  # getting extension from file
import sys      # output and stuff
import re       # for regular expressions

## extract doxygen-tag namespace
RE_MODULE = re.compile(
	'^(\w[\w-]*)[\s{](?:.|\n)*DEFINITIONS(?:.|\n)*::=\s*BEGIN'
	, re.IGNORECASE | re.VERBOSE | re.DOTALL | re.MULTILINE)
RE_EXPORTS = re.compile(
	'^\s*EXPORTS .*?;' 
	, re.VERBOSE | re.DOTALL | re.MULTILINE)

RE_IMPORTS = re.compile(
	'^\s*IMPORTS .*?;' 
	, re.VERBOSE | re.DOTALL | re.MULTILINE)

RE_END = re.compile(
	'^\s*END\s*$' 
	, re.VERBOSE | re.MULTILINE)

RE_DOXY_COMMENTS = re.compile(
	'^\s*--[-#!*]\s?'
	, re.VERBOSE | re.MULTILINE)

RE_DOXY_C_COMMENTS = re.compile(
	'^\s*/\*\*\s(.*?)\*/'
	, re.VERBOSE | re.MULTILINE)

RE_COMMENT = re.compile(
	'--.*?(?:--|$)'
	, re.VERBOSE | re.MULTILINE)

RE_TYPE = re.compile(r'(([A-Z][\w-]*)\s*::=[\w\s]+(?:{(.*?)})?.*?)\n\s*\n'
    , re.VERBOSE | re.MULTILINE | re.DOTALL)

extTypes = {}

def indentString(s, indent):
	lines = s.splitlines()
	s = ''
	for c in lines:
		s += ''.ljust(indent, ' ') + c + '\n'
	return s

def parseText(content, indent=None):
	c = RE_DOXY_COMMENTS.sub('', content)
	if c is not None:
		content = c
	c = RE_DOXY_C_COMMENTS.sub(r'\g<1>', content)
	if c is not None:
		content = c
	c = RE_COMMENT.sub('', content)
	if c is not None:
		content = c
	if indent is not None:
		content = indentString(content, indent)
	def repl_ref(m):
		return '[**{0}**]({1}#{0})'.format(m[1], extTypes.get(m[1],''))
	c = re.sub(r'@ref\s+([\w-]+)', repl_ref, content, 0, re.VERBOSE | re.MULTILINE)
	if c is not None:
		content = c
	return content
cpos=0
def parseModule(mname, content):
	global cpos
	cpos = 0
	def repl_import(m):
		global cpos
		cpos = m.start()
		ret = '## Imports:\n'
		pos = 0
		if m[1] is not None:
			s = m[1]
			for fm in re.finditer(r'^([,\s\w-]*?)FROM\s*([\w-]+)\s*({[^}]*})?', s, re.VERBOSE | re.MULTILINE):
				imName = fm[2]
				for im in re.finditer(r'[^,\s]+', fm[1], 0):
					extTypes[im[0]] = imName+'.md'
				ret += ' * **{}** *{}*<br/>\n'.format(imName, re.sub(r'\s+', ' ', fm[3] or '', 0, 0))
				ret += parseText(s[pos:fm.start()], 3)+'\n'
				pos = fm.end()
			ret += parseText(s[pos:])
		cpos += len(ret)
		return ret
	
	c = re.sub(r'^\s*IMPORTS\s*(.*?);', repl_import, content, 1, re.VERBOSE | re.DOTALL | re.MULTILINE)
	if c is not None:
		content = c

	def repl_exports(m):
		global cpos
		if cpos < m.start():
			cpos = m.start()
		return ''
	c = re.sub(r'^\s*EXPORTS.*?;', repl_exports, content, 1, re.VERBOSE | re.DOTALL | re.MULTILINE)
	if c is not None:
		content = c
	
	# parse types
	def repl_type (m, doc):
		ret = '## <a name="{0}"></a>{0}\n\n'.format(m[2])
		if doc is not None:
			ret += parseText(doc) + '\n\n'
		# parse fields and get out fields descriptions
		if m[3] is not None:
			ret += 'Fields:\n'
			pos = 0
			for fm in re.finditer('^\s*([\w-]+?)\s+(OCTET\s+STRING|BIT\s+STRING|[A-Z][.\w-]+)?(.*?)(?:,|$)', m[3], re.VERBOSE | re.MULTILINE | re.DOTALL):
				if fm[2] is not None:
					t = fm[2].strip()
					f = fm[1].strip()
					if re.match('^OCTET\s+STRING|BIT\s+STRING|BOOLEAN|INTEGER|FLOAT', t, re.VERBOSE|re.MULTILINE) is not None:
						ret += '* {0} **{1}** {2}<br>\n'.format(f, t, fm[3] or '')
					else:
						ret += '* {0} [**{1}**]({2}#{1}) {3}<br>\n'.format(f, t, extTypes.get(t,''), fm[3] or '')
				ret += parseText(fm.string[pos:fm.start()], 3)
				pos = fm.end()
		
		return ret + '```asn1\n' + re.sub(r'^\s*--.*\n', '', m[1].strip(), 0, re.MULTILINE) +'\n```\n\n'
	ret = content[:cpos]
	pos = 0
	for m in RE_TYPE.finditer(content[cpos:]):
		ret += repl_type (m, m.string[pos:m.start()])
		pos = m.end()
	return ret


def parseAsn(outDir, content) :
	# iterate modules in the file
	pos= 0
	RE_MODULE=re.compile(r'^\s*([A-Z][\w-]*)\s*({.*?})?\s*DEFINITIONS.*?::=\s*?BEGIN(.*)END', re.VERBOSE | re.MULTILINE | re.DOTALL)
	cnt = 0
	for m in RE_MODULE.finditer(content):
		ret = '# ASN.1 module {}\n OID: _{}_\n'.format(m[1], re.sub(r'\s+', ' ', m[2]))
		ret += parseText(content[pos:m.start()]) + '\n'
		if m[3] is not None:
			ret += parseModule(m[1], m[3])
		ret += '\n\n'
		open(outDir + '/' + m[1] + '.md', "w").write(ret)
		pos = m.end()
	return cnt

def main():
	argc = len(sys.argv)
	if argc < 3:
		sys.stderr.write("Usage: {} <out dir> [ASN.1 files]\n".format(sys.argv[0]))
		exit(1)
	outDir = sys.argv[1]
	cnt = 0
	for a in sys.argv[2:]:
		try:
			content = open(a).read()
			cnt += parseAsn(outDir, content)
		except IOError as e:
			sys.stderr.write(e[1]+"\n")
	print("{} modules porcessed\n".format(cnt))

if __name__ == '__main__':
	main()