Skip to content

Latest commit

 

History

History
184 lines (146 loc) · 7.04 KB

README.md

File metadata and controls

184 lines (146 loc) · 7.04 KB
Raw

HDP Declarative Programming conventions, early draft

This is an draft. See #16.

Trivia:

  • HDP naming:
    • HDP = 'HDP Declarative Programming' is the default name.
    • HDP = 'Humanitarian Declarative Programming' could be one way to call when the intent of the moment is strictly humanitarian.
      • The definition of humanitarian is out of scope.

High level goals

TODO: draft this

Conteiner format

  1. The preferred container format is YAML (https://yaml.org/)
    1. Platforms specific features, like the functionality of loading native directly in HDP tools:
      1. Should be ignored in existing YAML files
      2. Should NOT be exported with HDP+YAML format, even if well behaved HDP+YAML parsers would likely to ignore.
  2. JSON, in special for compatibility with other tools or for machine-to-machine HDP exchange or for specific low level calls, can be used as additional conteiner format.

Exchange of commands with foreign interface

  1. The recommended way of exposing HDP functionality to low level data processing that already not native on HDP is both exporting and accepting JSON format, without the full semantics of HDP (like translations of vocabulary)
    1. [INFORMATIONAL] Ansible uses JSON for data exchange of plugins.

Conventions for identifiers (key names)

Tokens meaning on keys

# Quick example 1
- hsilo:           # hsilo is an verb, without additional tokens
    linguam: LAT   # linguam is also an verb, LAT is an value

Note: Remove \ from \{\{ and \}\} if this document is renderized with them.

  • HDP internationalized vocab: No token
    • Description:
      • No token means an word that is perfectly valid HDP vocab that should be able to be translated to EVERY know natural language enabled by as it is.
    • Examples:
      • hsilolinguam: LAT
        • silolinguam: ENG|SPA|LAT|POR
      • linguamlinguam: LAT
        • language linguam: ENG
        • языкlinguam: RUS
  • HDP internationalized vocab with metadata: [ prefix, [[ prefix , ] suffix, ]] suffix
    • Description:
      • TODO
    • Examples:
      • TODO
    • Notes:
      • Reserved undocumented token.
  • HDP vocab with digitaly signed values: { prefix, \{\{ prefix , } suffix, \}\} suffix
    • Description:
      • Token to explicitly mention that the content of this key are digitally signed
      • Removing the [{, \{\{, \}\}, }], the resulting term must be perfectly valid HDP vocab that should be able to be translated to EVERY know natural language enabled by as it is.
    • Notes:
      • For sake of simplicity, if an upper key already is digitally signed, interfaces do not need to show these tokens if all contents, with exception of [<, <<, >>, >>], are signed.
      • When tokes [(, ((, ), ))] are present, the explicit use of this token us not yet defined, since this meas that an outisde program also need to be evaluated.
        • Maybe this with [(!( term-here ))] this notation could be good enough?
    • Examples:
      • \{\{datum\}\}linguam: LAT contents digitally signed and recently verified
      • {?{datum}?}linguam: LAT contents digitally signed, but not verified yet or this computer can't do automated verification
      • {!!!{datum}!!!}linguam: LAT contents digitally signed, but with 1) error, 2) explicitly untrusted or 3) this environment do not tolerate {?{datum}?}
  • Eval: ( prefix, (( prefix , ) suffix, )) suffix
    • Notes:
      • Reserved undocumented token.
  • Comment: < prefix, << prefix , > suffix, >> suffix
    • Description:
      • This key can be used as comment
      • Do not evaluate. Can be safely ignored contents. Do not try to guess the core mesage
    • Examples:
      • <<COMMENT>>, <ENG<COMMENT>>, <POR<COMENTARIO>>
The << >>, <<! !>>, , <<!! !!>>, , <<!!! !!!>>

Draft from v0.8.3

  • << >>, <(.*)< >(.*)>
    • For sake of convention, we could use this more for user-related comments
    • the (.*) means that something can be put betwen <</>>, like <POR<Meu comentário aqui em Português>>
  • <<! !>>
    • When processing HDP files, internal functions often need to pass information that is essential for functionality (or at least to speed up). This extra ! could be used for this type of internal comment
      • Maybe we could allow user expose this with 'verbose' parameters?
  • <<!! !!>>, <<!!! !!!>>
    • Similar to <<! !>>, but for higher level of information that is not necessary for end user, but may be for who would work with the library
      • Maybe we could allow user expose this with 'debug' parameters?

Issue: ! character is sometimes used to mean 'encrypted', so maybe we should choose another character

Collaborative work

See collaborative-work.md

Security considerations

See security-considerations.md