For a bro script that is documented like:
## ...
## bar: ...
## Returns: ...
global foo(bar: string): string;
the generated reST documentation will automatically substitute meaningful
markup (reST field lists) for the parameter and return type comments
* New script: http/file-extract.bro
* New script: http/file-ident.bro
* New script: http/file-hash.bro
* Lot of cleanup. The output logs are better than before.
The merge does not include the hack to switch back to 32-bit for
Broccoli. It does contain a version of the SSL tests converted to
btest, which however doesn't pass yet (as some of the others as well)
* origin/topic/robin/comm-ssl:
Fixing crashes when SSL is not configured correctly.
Adding a test for SSL-based communciation to the istate testsuite.
Removing everything related to trace rewriting.
(I wasn't too careful in ensuring that I catch everything in the
scripts; Seth is working on those anyway.)
(Merging by cherry-picking the corresponding commit, as the branch was
accidentally made off of the logging stuff).
Note that currently most of them don't pass because (i) the code
adding the environment variable for seeding the RNG has not been
merged into master yet; and (2) Broccoli to Bro communication is
currently broken because of the int64 problem. Once these are fixed,
then baselines need to be recreated and checked.
Therefore, the istate tests aren't activated in btest.cfg yet.
Note that I've shifted things around a little bit. The traces are now
in Traces/* (capital T), and the known-hosts-test in policy/*.
Scripts/ was meant just for helper shell scripts for the testing
framework. Also, I've not yet included "policy" in btest.cfg as a
TestDir because the corresponding script is not yet in master.
* origin/topic/appleman/unittests:
Test, trace file, and baseline for testing the known-services policy script
Baseline for KNOWN-HOSTS tesT
Initial drop of known-hosts unit test, with tracefile and directory structure, as well as c ouple of files pulled from Robin's logging branch.
A function prototype can be declared separately from where it's defined;
the doc framework should now recognize them as the same and combine
reST documentation associated with either case if both are present.
* The http.bro script only loads other scripts now.
* http/base.bro configures the analyzer in the core
and does minimal state collection.
* http/base-extended.bro adds extra state collection
that may not always be desired.
* http/detect-intel.bro is where intelligence based
detection that we ship will take place.
* http/detect.bro is where behavioral and scripted (known)
actions will be detected.
* http/utils.bro are http specific utility functions
* http/var-extraction* scripts add cookie and uri key values
to the base state collection and logging. They are also
maintained in a vector so that order is presevered.
The var-extraction* and base-extended scripts are good examples
of how the base script extension model works.
This also has an inital try at storing the "Info" state table
in the connection record.
They now appear at the bottom of generated docs.
Also, a "more info" link is added which can point to an arbitrary location
in any reST document processed by Sphinx.
The &log keyword now operates as discussed:
- When associated with individual record fields, it defines them
as being logged.
- When associated with a complete record type, it defines all fields
to be logged.
- When associated with a record extension, it defines all added
fields to be logged.
Note that for nested record types, the inner fields must likewise
be declared with &log. Consequently, conn_id is now declared with
&log in bro.init.
Vectors are now allowed to be logged and will be recorded as an
ordered set of items.
* I haven't removed handwritten analyzer code yet although it isn't built anymore.
* The ssl.bro script is just an example and doesn't keep any state yet.
A script's public API wasn't simply definable as identifiers
for which ID::IsGlobal() is true, e.g. an unexported identifier with
SCOPE_MODULE will still pass that test and (incorrectly) be considered
public API.
Also, generated reST now omits empty interface sections.
A bro script's public interface is taken to mean any identifier declared
in the global scope that optionally is exported from some namespace/module.
Or more simply: ID::IsGlobal()
This functionality is better done manually by the script writer
embedding reST into the script summary section (##! comments).
This allows flexibility in choosing between different methods
to convey the same information (e.g. ":Author: <author>" or
the ".. codeauthor:: <author>" directive that Sphinx
configurations can recognize).
It's allowed for a script to "@load example.bro", but Sphinx doesn't want
that file extension for the purposes of generating cross-referencing links
to other documentation.
The documentation framework now sees "##Text" and "## Text" as
equivalent documentation comments. This prevents unintentional
indentation in the generated reST as a result of the later style, but
still allows embedded reST markup that relies on indentation of more
than two spaces to work as expected.
Comments associated with record fields and enums values are able
to span multiple "##"-stylized comments, allowing for more robust
reST markup to be embedded.
The documentation framework now tracks record fields through
a new CommentedTypeDecl subclass of TypeDecl that the parser constructs
in parallel with the real TypeDecl.
* topic/robin/record-coercion:
Fixing a bug with nested record ctors.
Enabling automatic coercion from record type A to be B as long as A has all the types that B has.
Conflicts:
src/Expr.cc
