third_party/nlassert/repo/README.md

   1 [![Build Status][nlassert-travis-svg]][nlassert-travis]
   2 [![Coverage Status][nlassert-codecov-svg]][nlassert-codecov]
   3
   4 Nest Labs Assert
   5 ================
   6
   7 # Introduction
   8
   9 This package defines macros and interfaces for performing both
  10 compile- and run-time assertion checking and run-time exception
  11 handling.
  12
  13 Where exception-handing is concerned, the format of the macros are
  14 inspired by those found in Mac OS Classic and, later, Mac OS
  15 X. These, in turn, were inspired by "Living In an Exceptional
  16 World" by Sean Parent (develop, The Apple Technical Journal, Issue
  17 11, August/September 1992). See:
  18
  19     http://www.mactech.com/articles/develop/issue_11/Parent_final.html
  20
  21 for the methodology behind these error handling and assertion macros.
  22
  23 # Overview
  24
  25 The interfaces in this package come in two interface modalities:
  26
  27 * **Run-time** Interfaces that dynamically check a logical assertion and alter run-time execution on assertion firing.
  28 * **Compile-time** Interfaces that statically check a logical assertion and terminate compile-time execution on assertion firing.
  29
  30 ## Run-time
  31
  32 The run-time modality interfaces in this package come in three
  33 families:
  34
  35 * **Assertion** Similar to the traditional C Standard Library
  36     [assert()](http://pubs.opengroup.org/onlinepubs/009695399/functions/assert.html).
  37 * **Precondition** Designed to be placed at the head of an interface or
  38     method to check incoming parameters and return on assertion failure.
  39 * **Exception** Designed to jump to a local label on assertion failure
  40     to support the method of error and exception handling that advocates
  41     a single function or method return site and, by extension, consolidated
  42     points of exception and error handling as well as resource clean-up.
  43
  44 There are several styles of interfaces within each family and several
  45 potential variants within each style, all of which are summarized
  46 below and are described in detail in the following sections.
  47
  48 ## Compile-time
  49
  50 The compile-time modality interfaces in this package are simpler and
  51 come in a single family with a couple of styles and variants, all
  52 intended to provide parallelism with the run-time interfaces.
  53
  54 [nlassert-travis]: https://travis-ci.com/nestlabs/nlassert
  55 [nlassert-travis-svg]: https://travis-ci.com/nestlabs/nlassert.svg?branch=master
  56 [nlassert-codecov]: https://codecov.io/gh/nestlabs/nlassert
  57 [nlassert-codecov-svg]: https://codecov.io/gh/nestlabs/nlassert/branch/master/graph/badge.svg
  58
  59 # Interact
  60
  61 There are numerous avenues for nlassert support:
  62
  63   * Bugs and feature requests — [submit to the Issue Tracker](https://github.com/nestlabs/nlassert/issues)
  64   * Google Groups — discussion and announcements
  65     * [nlassert-announce](https://groups.google.com/forum/#!forum/nlassert-announce) — release notes and new updates on nlassert
  66     * [nlassert-users](https://groups.google.com/forum/#!forum/nlassert-users) — discuss use of and enhancements to nlassert
  67
  68 # Versioning
  69
  70 nlassert follows the [Semantic Versioning guidelines](http://semver.org/)
  71 for release cycle transparency and to maintain backwards compatibility.
  72
  73 # License
  74
  75 nlassert is released under the [Apache License, Version 2.0 license](https://opensource.org/licenses/Apache-2.0).
  76 See the `LICENSE` file for more information.