Element Framework - craterdog-archives/js-bali-component-framework GitHub Wiki

Elements are primitive components that cannot be broken down into subcomponents. Each element has an immutable value. And although the value of an element cannot be changed, many elements provide functions that operate on one or more elements to produce a new element.

The following UML class diagram shows a high-level view of the elemental component types (gray).

Abstract type names are italicized whereas concrete type names are not.

An angle element represents an angular measurement in the range [<-π..π] and supports the trigonometric operations associated with geometry and complex analysis. Some example angles:

• ~π
• ~-1.601
• ~90($units: $degrees)
• ~τ tau is the same as ~2π or ~0

A binary element represents a binary byte string encoded in base 2, 16, 32 (default) or 64 string format and embedded within single quotes. Binary elements can be iterated over and support bit-wise logic operations and chaining. Some example binary strings:

• '1011010111010100'($encoding: $base2)
• '6005A83680047804A049D8018002'($encoding: $base16)
• '2STVS5X9AB5P136G10MSFX2AHBV4JC0DLJD66'
• 'gV2qMVdiG7XYRSqV6jg='($encoding: $base64)

A boolean element supports the values of false and true. Boolean elements also support all of the logic functions (i.e. NOT, AND, SANS, OR and XOR).

A duration element represents a "duration of time" represented in ISO 8601 format. A time duration may be the difference between two moments in time, and a duration may be added to or subtracted from a moment in time to give a new moment in time. Duration elements are also scalable. Some example time durations:

• ~PT27M45S is 27 minutes and 45 seconds
• ~P5W is 5 weeks
• ~P3M2DT15H31M is 3 months, 2 days, 15 hours and 31 minutes
• ~P6Y5M4DT3H2M1S is 6 years, 5 months, 4 days, 3 hours, 2 minutes and 1 second
• ~P0D is a zero duration of time

A moment element represents a "moment in time" using ISO 8601 format and may be parameterized with the location of where the moment in time occurred. Some example moments in time (and space):

• <1962-04-01> is April Fool's Day 1962
• <2018-08-24T17:30> is 5:30pm on August 24th, 2018
• <2017-12-30T13:38:35.726>($country: "Spain", $city: "Madrid")

A name element resides in a global directory structure that uses standard filesystem notation (e.g. /bali/types/List/v1) to reference documents stored in the Bali Nebula™ in Bali Document Notation™. Name elements can be iterated over and support chaining. Some global names:

• /bali/collections/Queue/v1
• /acme/accounting/reports/2019/Q3/v1.4
• /acme/accounting/transactions/MXLTJVCBAHRF2WJF5RTLL4A2VZDXLY0R

A number element supports many types of numbers including integers, real and imaginary numbers, and even complex numbers. A complex number can be in rectangular form or polar form in which case the imaginary part of the complex number is an angle. Complex elements support scaling and numerical operations. Some example complex numbers:

• 42
• e Euler's constant
• φ the golden mean
• 1.23E-56
• -5i
• (-3, 4i) in rectangular form
• (1 e^~π i) in polar form
• ∞ infinity

A pattern element captures a regular expression string pattern or a composite component template pattern that can be used to match other components. Some example patterns:

• none matches nothing
• any matches anything
• "foo[bB]ar"? matches "foobar" and "fooBar"

A percentage element represents a percentage of something. Percentage elements support scaling operations. Some example percentages:

• 0%
• -25%
• 152.7%

A probability element supports all fractions in the range [.0..1.]. Fractional values have digits on only one side of the decimal to avoid confusion with real numbers. The value .0 represents the probability of an impossible event. The value 1. represents the probability of a certain event. Probabilities also support all of the standard logic functions (i.e. NOT, AND, SANS, OR and XOR) which allows the Bali Virtual Machine™ to implement fuzzy logic. Some example probabilities:

• .0 -- an impossible event
• .5 -- even odds
• 1. -- a certain event

A resource element represents any universal resource identifier including email addresses, web addresses, and Bali documents stored in the Bali Nebula™. Some example resources:

• <https://google.com/>
• <mailto:[email protected]>

A symbol element is used to refer to a symbol in Bali Document Notation™. Symbol elements can be iterated over. Some example symbols:

• $first
• $target
• $type

A tag element defines a potentially galactically unique identifier that guarantees there will be no collisions between it and other tags, and makes the tags impossible to guess. Each tag is an arbitrary number of bytes long and is encoded using base 32 characters. Some example tags:

• #SX3TCS8X1LH7V0PW1MRSPR9K is 15 bytes long
• #6C9PN1JMWXGD4L86DMLGBTR6DND649QV is 20 bytes long
• #WAL39W7LH3YMVQDSVB77WSWKK5VTY6TFC7T83Q44 is 25 bytes long

A text element supports both inline quoted strings and format preserving narrative strings each embedded in double quotes. A narrative string begins with a double quote followed by an EOL character and is terminated by an EOL character followed by a double quote. Any character including double quotes may be part of a text block as long as the double quote is not the first non-white space character on a line (or this would terminate the narrative prematurely. Text elements can be iterated over and support chaining. Some example text strings:

• "This is a quoted text string."

• "
      This is a multiline narrative containing
      both "double" and 'single' quotes and an
      expression {list.size()} that will be
      evaluated each time the text block is used.
  "
  

A version element represents a version string (e.g. v1.2.3) in a way that makes it easy to manipulate specific version levels and enforces ordinal numbering of each level (i.e. no zeros allowed). Version elements can be iterated over. Some example version strings:

• v1 is a major release
• v2.43 is a minor release
• v31.2.6 is a bug patch