From: Ben Pfaff <blp@nicira.com>
Date: Fri, 11 Dec 2009 22:12:50 +0000 (-0800)
Subject: vswitch: Generate text file documenting the vswitch schema.
X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=45a7de56bbcb2adfabf2082b1133e768777d44d6;p=openvswitch

vswitch: Generate text file documenting the vswitch schema.

Now you can read vswitchd/vswitch-idl.txt for some textual documentation
of the OVS schema.
---

diff --git a/ovsdb/automake.mk b/ovsdb/automake.mk
index 2dcc4638..f3f5f9b9 100644
--- a/ovsdb/automake.mk
+++ b/ovsdb/automake.mk
@@ -82,7 +82,7 @@ EXTRA_DIST += \
 	ovsdb/ovsdb-idlc.in \
 	ovsdb/ovsdb-idlc.1
 DISTCLEANFILES += ovsdb/ovsdb-idlc
-SUFFIXES += .ovsidl
+SUFFIXES += .ovsidl .txt
 .ovsidl.c:
 	$(PYTHON) $(srcdir)/ovsdb/ovsdb-idlc.in c-idl-source $< > $@.tmp
 	mv $@.tmp $@
@@ -92,3 +92,6 @@ SUFFIXES += .ovsidl
 .ovsidl.ovsschema:
 	$(PYTHON) $(srcdir)/ovsdb/ovsdb-idlc.in ovsdb-schema $< > $@.tmp
 	mv $@.tmp $@
+.ovsidl.txt:
+	$(PYTHON) $(srcdir)/ovsdb/ovsdb-idlc.in doc $< | fmt -s > $@.tmp
+	mv $@.tmp $@
diff --git a/ovsdb/ovsdb-idlc.in b/ovsdb/ovsdb-idlc.in
index f33a2779..d70e5ebb 100755
--- a/ovsdb/ovsdb-idlc.in
+++ b/ovsdb/ovsdb-idlc.in
@@ -43,8 +43,9 @@ class DbSchema:
         comment = getMember(json, 'comment', [unicode], 'database')
         tablesJson = mustGetMember(json, 'tables', [dict], 'database')
         tables = {}
-        for name, tableJson in tablesJson.iteritems():
-            tables[name] = TableSchema.fromJson(tableJson, "%s table" % name)
+        for tableName, tableJson in tablesJson.iteritems():
+            tables[tableName] = TableSchema.fromJson(tableJson,
+                                                     "%s table" % tableName)
         idlPrefix = mustGetMember(json, 'idlPrefix', [unicode], 'database')
         idlHeader = mustGetMember(json, 'idlHeader', [unicode], 'database')
         return DbSchema(name, comment, tables, idlPrefix, idlHeader)
@@ -141,6 +142,47 @@ class Type:
                 d["max"] = self.max
             return d
 
+    def isScalar(self):
+        return self.min == 1 and self.max == 1 and not self.value
+
+    def isOptional(self):
+        return self.min == 0 and self.max == 1
+
+    def toEnglish(self):
+        keyName = atomicTypeToEnglish(self.key, self.keyRefTable)
+        if self.value:
+            valueName = atomicTypeToEnglish(self.value, self.valueRefTable)
+
+        if self.isScalar():
+            return atomicTypeToEnglish(self.key, self.keyRefTable)
+        elif self.isOptional():
+            if self.value:
+                return "optional %s-%s pair" % (keyName, valueName)
+            else:
+                return "optional %s" % keyName
+        else:
+            if self.max == "unlimited":
+                if self.min:
+                    quantity = "%d or more " % self.min
+                else:
+                    quantity = ""
+            elif self.min:
+                quantity = "%d to %d " % (self.min, self.max)
+            else:
+                quantity = "up to %d " % self.max
+
+            if self.value:
+                return "map of %s%s-%s pairs" % (quantity, keyName, valueName)
+            else:
+                return "set of %s%s" % (quantity, keyName)
+                
+
+def atomicTypeToEnglish(base, refTable):
+    if base == 'uuid' and refTable:
+        return refTable
+    else:
+        return base
+
 def parseSchema(filename):
     file = open(filename, "r")
     s = ""
@@ -612,6 +654,25 @@ def ovsdb_escape(string):
 def printOVSDBSchema(schema):
     json.dump(schema.toJson(), sys.stdout, sort_keys=True, indent=2)
 
+def printDoc(schema):
+    print schema.name
+    if schema.comment:
+        print schema.comment
+
+    for tableName, table in schema.tables.iteritems():
+        title = "%s table" % tableName
+        print
+        print title
+        print '-' * len(title)
+        if table.comment:
+            print table.comment
+
+        for columnName, column in table.columns.iteritems():
+            print
+            print "%s (%s)" % (columnName, column.type.toEnglish())
+            if column.comment:
+                print "\t%s" % column.comment
+
 def usage():
     print """\
 %(argv0)s: ovsdb schema compiler
@@ -623,6 +684,7 @@ One of the following actions must specified:
   c-idl-header                print C header file for IDL
   c-idl-source                print C source file for IDL implementation
   ovsdb-schema                print ovsdb parseable schema
+  doc                         print schema documentation
 
 The following options are also available:
   -h, --help                  display this help message
@@ -662,6 +724,8 @@ if __name__ == "__main__":
             printCIDLHeader(schema)
         elif action == 'c-idl-source':
             printCIDLSource(schema)
+        elif action == 'doc':
+            printDoc(schema)
         else:
             sys.stderr.write(
                 "%s: unknown action '%s' (use --help for help)\n" %
diff --git a/vswitchd/automake.mk b/vswitchd/automake.mk
index 1d9d92b1..29e4034d 100644
--- a/vswitchd/automake.mk
+++ b/vswitchd/automake.mk
@@ -38,9 +38,15 @@ EXTRA_DIST += \
 EXTRA_DIST += vswitchd/vswitch-idl.ovsidl
 BUILT_SOURCES += vswitchd/vswitch-idl.c vswitchd/vswitch-idl.h
 DISTCLEANFILES += vswitchd/vswitch-idl.c vswitchd/vswitch-idl.h
-noinst_DATA += vswitchd/vswitch-idl.ovsschema
-DISTCLEANFILES += vswitchd/vswitch-idl.ovsschema
-vswitchd/vswitch-idl.c vswitchd/vswitch-idl.h vswitchd/vswitch-idl.ovsschema: \
+noinst_DATA += vswitchd/vswitch-idl.ovsschema vswitchd/vswitch-idl.txt
+DISTCLEANFILES += vswitchd/vswitch-idl.ovsschema vswitchd/vswitch-idl.txt
+vswitchd/vswitch-idl.c vswitchd/vswitch-idl.h \
+vswitchd/vswitch-idl.ovsschema vswitchd/vswitch-idl.txt: \
 	ovsdb/ovsdb-idlc.in
 vswitchd/vswitch-idl.c: vswitchd/vswitch-idl.h
-EXTRA_DIST += vswitchd/vswitch-idl.c vswitchd/vswitch-idl.h vswitchd/vswitch-idl.ovsschema
+EXTRA_DIST += \
+	vswitchd/vswitch-idl.c \
+	vswitchd/vswitch-idl.h \
+	vswitchd/vswitch-idl.ovsschema \
+	vswitchd/vswitch-idl.txt
+