From c03ef308c919947f1f017f8d13e4754e3364a687 Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Wed, 3 Jul 2019 11:03:07 -0700 Subject: [PATCH] Improve Zeekygen output for long attribute expressions Long inline-literals often don't wrap pleasantly in HTML renders and we had a few &default or &deprecated attributes whose expressions evaluate to a value long enough to warrant different formatting or even truncation. --- CHANGES | 4 ++++ VERSION | 2 +- doc | 2 +- src/Attr.cc | 44 ++++++++++++++++++++++++++++++++++---------- src/Attr.h | 4 ++-- src/ID.cc | 2 +- 6 files changed, 43 insertions(+), 15 deletions(-) diff --git a/CHANGES b/CHANGES index 8138b1df94..525c88a89b 100644 --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,8 @@ +2.6-566 | 2019-07-03 11:08:24 -0700 + + * Improve Zeekygen output for long attribute expressions (Jon Siwek, Corelight) + 2.6-565 | 2019-07-03 09:32:34 -0700 * GH-446: Deprecate rfb_event. (Johanna Amann, Corelight) diff --git a/VERSION b/VERSION index 647b89b7e9..8b96eff2a8 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.6-565 +2.6-566 diff --git a/doc b/doc index be223b7e2f..80c0cb3d9d 160000 --- a/doc +++ b/doc @@ -1 +1 @@ -Subproject commit be223b7e2fe9e2cfcfe8df4d594a6255276c6317 +Subproject commit 80c0cb3d9db1cea6661b3d3c79d17e3b67533507 diff --git a/src/Attr.cc b/src/Attr.cc index 079c125f9e..36050d2262 100644 --- a/src/Attr.cc +++ b/src/Attr.cc @@ -45,8 +45,33 @@ void Attr::Describe(ODesc* d) const } } -void Attr::DescribeReST(ODesc* d) const +void Attr::DescribeReST(ODesc* d, bool shorten) const { + auto add_long_expr_string = [](ODesc* d, const std::string& s, bool shorten) + { + constexpr auto max_expr_chars = 32; + constexpr auto shortened_expr = "*...*"; + + if ( s.size() > max_expr_chars ) + { + if ( shorten ) + d->Add(shortened_expr); + else + { + // Long inline-literals likely won't wrap well in HTML render + d->Add("*"); + d->Add(s); + d->Add("*"); + } + } + else + { + d->Add("``"); + d->Add(s); + d->Add("``"); + } + }; + d->Add(":zeek:attr:`"); AddTag(d); d->Add("`"); @@ -57,7 +82,6 @@ void Attr::DescribeReST(ODesc* d) const d->Add("="); d->SP(); - if ( expr->Tag() == EXPR_NAME ) { d->Add(":zeek:see:`"); @@ -74,14 +98,15 @@ void Attr::DescribeReST(ODesc* d) const else if ( expr->Tag() == EXPR_CONST ) { - d->Add("``"); - expr->Describe(d); - d->Add("``"); + ODesc dd; + dd.SetQuotes(1); + expr->Describe(&dd); + string s = dd.Description(); + add_long_expr_string(d, s, shorten); } else { - d->Add("``"); Val* v = expr->Eval(0); ODesc dd; v->Describe(&dd); @@ -92,8 +117,7 @@ void Attr::DescribeReST(ODesc* d) const if ( s[i] == '\n' ) s[i] = ' '; - d->Add(s); - d->Add("``"); + add_long_expr_string(d, s, shorten); } } } @@ -211,14 +235,14 @@ void Attributes::Describe(ODesc* d) const } } -void Attributes::DescribeReST(ODesc* d) const +void Attributes::DescribeReST(ODesc* d, bool shorten) const { loop_over_list(*attrs, i) { if ( i > 0 ) d->Add(" "); - (*attrs)[i]->DescribeReST(d); + (*attrs)[i]->DescribeReST(d, shorten); } } diff --git a/src/Attr.h b/src/Attr.h index f32c11e50f..efbac63747 100644 --- a/src/Attr.h +++ b/src/Attr.h @@ -51,7 +51,7 @@ public: { return tag == ATTR_REDEF || tag == ATTR_OPTIONAL; } void Describe(ODesc* d) const override; - void DescribeReST(ODesc* d) const; + void DescribeReST(ODesc* d, bool shorten = false) const; bool operator==(const Attr& other) const { @@ -88,7 +88,7 @@ public: void RemoveAttr(attr_tag t); void Describe(ODesc* d) const override; - void DescribeReST(ODesc* d) const; + void DescribeReST(ODesc* d, bool shorten = false) const; attr_list* Attrs() { return attrs; } diff --git a/src/ID.cc b/src/ID.cc index ad7f345667..c249697b4d 100644 --- a/src/ID.cc +++ b/src/ID.cc @@ -412,7 +412,7 @@ void ID::DescribeReSTShort(ODesc* d) const if ( attrs ) { d->SP(); - attrs->DescribeReST(d); + attrs->DescribeReST(d, true); } }