TODO

LOTS TO WORK ON
---------------
Languages are complicated...

-----------------------------------------------------------------------------
NEW ISSUES

These are new issues identified but not entered into the outstanding bug list
-----------------------------------------------------------------------------

Long term Ongoing Work
----------------------

- custom error for subtype x is array... where arrays must be a type

  - error messages and additional context
    - many error messages have the source arrow 1 position to the right
      of where it should be
    - subjectLocation may not be relevant for built-in types like
      integer.  How should this be distinguised to avoid nonsense
      locations?
    - expectSymbol double spaces before "expects" in message
    - messages in present or past tense not both
    - search for appropriate remedies
    - qp() - quiet mode capitalize first - and subjectNotes in err()
    - of the core language, the compiler (err_tokenize) has not been
      converted to the new format.  Does it make sense to do so?
  - error messages addressing common problems listed in StackOverflow
  - bash comparision and making the shell more standards compliant
    - add ctrl-c to pause / fg / bg commmands to SparForte, and maybe job control?
  - coverage tests of recent changes
  - secrets detection
    - should be applied to all string literals
    - should be able to be turned off
    - should be able to read into limited variables...check
      - we need a get_line procedure since limited variables
        cannot be assigned
    - documentation and testing
  - upgrade SDL
    - need to upgrade to 2.0
    - need to fix pointer issues to SDL/OpenGL structures
    - proper error messages should be provided on unavailable
      functions
  - interfacing to more Standard Ada Libraries
  - complex data structures


Priority Issues (Fix These First)
---------------------------------

- constants can be assigned abstract types...was that intentional or
  a bug?
- can a workaround be found for mysql/mariadb not compiling on recent
  versions of Linux?
- case affirm partially implemented - tests needed
- an exception was raised that, when it finally was received at the
  top level, had lost the message.  This occurred in the SSDS washed_blocked
  script.  exceptions are not propogating to the main program exception
  handler.  exceptions.exception_info is empty.  It may be difficult to
  reproduce and determine the cause.
- missing tests
  - test for pragma restriction( no_prompt_history )...may be difficult
  - tests for ada 95 and strings package csv_field, csv_replace, field, is_slashed_date, is_typo_of, mktemp, split, to_base64, to_escaped, to_hexadecimal_digits, to_json
  - negative tests for l10n package
  - doubly linked lists parameters tests needed
- universal typeless loses its properties when a custom type or subtype
 is derived from it
- check shell dollar expansion escaping for security issues
- ubuntu container failing because l10n constants are not defined (they
  are defined in a regular ubuntu install)
- in `find ... \; ;` it becomes ; ; - is this correct?
- memory leak tests - check to make sure that resources are being cleared
- check the end-of-block usage checks and error messages
  - check each of the SDLC modes
  - review non-block tests
- box <> allowed in case when conditions needs negative tests
- ada vectors
  - complete extended subprograms (if time)
  - tests - subtypes, arrays (out param), universals
  - append/prepend to a vector (Ada naming convention) vs. an Element - mine usage and ada conflicts with each other (I think Ada is probably wrong.)
  - check handling of vectors of vectors, maps of maps, etc.
  - check enumerated vector index (it's a "TODO")
  - can I simulate a cursor for the wrong vector, raising an exception like ada?
  - "?" and vector for quick table display?
- multi-case
  - case in negative tests, type cast, refactor out idents with PareAssignment
  - static case and support multi-case
  - should <> box be replaced with *, since it's a standard and box does not
    otherwise exist in SparForte?
  - <> box statement negative tests
  - business process block that only supports case in (do this after vectors)
  - with separate policy, with separate configuration, with separate process in addition to normal with separate to load such things from non-standard locations
  - with separate policy, with separate configuration, with separate process in addition to normal with separate
- modernizing and securing console messages
  - checking error display rewrite
    - security testing
      - I should write tests that validate we're escaping
  - the error pointer arithmetic in getCommandLine assumes a 195
    character for UTF-8 but this may not always be true.  UTF-8 character
    counting should be more accurate
  - review toEscape use for foreign characters
    - the general need of better handling of variants of unbounded
      strings and ambiguity over string functions
    - UTF-8 handling needs to be rethought to support multibyte
      characters
- templates
  - templates that are not for HTTP
- check btree/hash_io get next mark the variable as written
  with the constant check
- investigate "return value" (result_value_str) vs world.adb "return result for" and ensure they are consistent throughout sparforte.
- affirms report the error location in the affirm but loses context for
  where in the code the affirm was triggered
- pragma todo
  - these do not appear in help output when in include files
- ada hash map support
  - creating cursors as out parameter on hashed_maps.find
  - check handling of universal types and hashed_maps
  - should insert be converted to insert and mark
- arrays of containers
  - array elements of vectors / doubly / hashed_maps and their cursors and
    handling in the various package subprograms
    - if cannot be done, at least provide an appropriate error when it is attempted
- errors should support err_previous
- logs package - whether or not something should be escallated
  to an "error" severity based on appearence of common stop words
  in the message (SecTor)
  - perhaps an option for adding stop words for different languages
    or a set of pre-defined stop words
  - also, the general problem that error severity is not always known at the
    time a message is logged
- better expected token messages
  - ada95 solution recommendations.  these might benefit from the better expected messages
  - declaration locations on declared-but-not-used messages
  - type checking does not have the advanced error messages
  - replace all uses of deprecated expect()
- how can design mode be improved to assist with producing design diagrams?  translating
  things into design diagrams is a costly part of design.
  - graphviz / .dot generation?
- refactor source code treasury index page
- record field identifiers erros in a record definition are reported as
  "shell words" for string or numeric literals but should not be.  record
  type declarations have nothing to do will the Bourne shell features.
- check on use of gen parameter functions vs. numeric in dht package
- in out parameters for built-in subprograms should use references
- check for TODO's
- Beader: that variables with same spelling but different cases should be an error
- provision script should search for the EPEL RPM version, not be hard-coded
- templates
  - templates that are not for HTTP
- procedure vs function
  - check detection for return value and procedures: an enclosing function
    could fool a procedure call into thinking a return statement can have
    a return value (which never gets used).  We'll need to do some redesign
    work to solve this.
- bug
  - ^-^ In primes, the end of the statement expects ';' where primes is
    a variable in assignment...is incorrect.  At least, it should be
    "in primes assigment".  It is difficult to tell you are in an
    assignment, as the procedures are designed.
- bug: logging is showing duplicate lines?
- cd should better distinguish between AdaScript and shell parameters.
  the ~ normally does not expand when in double quotes but it may
  expand anyway because old_cd() does not distinguish if the parameters
  are shell-style.

- get_line and GNU readline autocomplete options from an array of words
  provided by the user (custom autocompletions)
- shell ulimit built-in
  - include an option to timeout a script if it runs too long
- separate subprograms need parameter verification like other forward
  specifications, or the two should be harmonized to work the same way
- how can design mode be improved to assist with design diagrams?  perhaps
  a simple left-justified tree of the program like the shell tree command
  showing the program components and design notes or documentation?  One
  of the problem with design is keeping the documentation up-to-date.
- redesign source code treasury index page
- update examples with recent changes to SparForte (e.g. affirm clauses)
- update REPL on website
- check pascal's changes for supporting graphic environments
  - unifying the language I/O and do not rely on Ada.Text_IO.
- fix some of the issues with opengl support
- shell parser rewrite
  - ls("-l") | wc -l does not work (legacy compiler issue) but the
    opposite works.
- updating adascript shell commands to correspond with bourne shell changes.
  - anything to be done?
- completions
  - drill-down on empty directories probably not working
- fazing out ada.text_io for SparForte's functions to eliminate device
  errors.
- manual test cases -  can HTML be embedded as CDATA in junit xml?
- incomplete casting tests
- Research: for web to be secure, you can output raw strings to the console.
  Can this be enforced in templates?
- SQL security
    - LIKE requires parsing to understand the quote context.  A quoted
      string following a LIKE must be escaped differently.
      - check %, \, _, [ must be escaped, but it depends on the engine
      - postgresql is more complicated
        - has "SIMILAR TO" (regex)
        - has ~ regex operators
- Fix: testing validator project I noticed
  - under some conditions, the breakout prompt my have end-of-file and be
    interpreted as a return to resume execution.  I have not identified what
    those conditions are.
* Verify: waitToReveal sometimes throws an unexpected exception
- the new type qualifiers system and renaming
  - Verify: disabling qualifiers when tests are underway and special regression
    tests for the same. (tests)
  - Research: should subprogram parameters allow qualifiers?
- Research: affirm blocks
    - Research: test if HTML escaping can be implemented in an affirm block
    - Research: should affirm blocks have an expression short-form?
    - Research: should affirm blocks have storage specifications?
    - Research: move DoContracts to parser_aux?
    - Research: constant limited?
  - New: copy of aggregates and renamings
    - New: copying arrays
    - New: copying records
      - New: full copy of arrays and records
      - New: document new keyword copying
      - Research: was wasWritten obsolete with writtenByThread?
    - Verify: the affect of renamings?
    - Verify: this probably need to be run-time
- unstructured scripts
  - Docs: additional examples to be added to automated tests
- Refactor: static expressions
- Refactor: in out parameters should return references
  - why are in out parameters not references? e.g. in mysqlm and dbm, should
    arrays of database connections be possible?
- Change: csv support
     - Change: csv_replace - single quote, cr+lf ending
- Research: enforcing strong types and/or contracts
  - Research: should import require contracts rather than custom type?
- unsorted/misc
    - mysql.prepare function not implemented (proc is)
    - Verify: check that x : arraytype := (x) works correctly, both with specs
      and normal declaration.
    - Verify: finish manual test pragmas
    - Change: generally, we need to identify built-in types.  It's not enough that
      they are descended from universals.  We need to understand what a
      base type is.  That is, the difference from a standard package type.
    - Verify: an early return from the main program doesn't pull the final block,
      even if the template isn't parsed.
    - Fix: control-c is propogating to all child processes when it shouldn't
      - check SIGPIPE handling also
    - Research: btree_io.cursor should have the key type assigned when declared.  Why did
      I choose not to?  What's the reason?
    - Research: pragma risk_tolerance(amt) or pragma optimize( reliability )
      - perhaps optimize is too simplistic: these need to be ranked/rated
        (like pragma emphasize/deemphasize).
      - forcing static side-effect checking
    - Research: spell checking comments (as Windows does?)  must whitelist all
      identifiers.  See /usr/include/aspell.h for interface to spell checker.
    - Verify: a variable not declared is said to be declared but not used (this_run_on in
      ssds project) - could not duplicate in simple test
    - Research: is close_on_exec useful?
- SDL 2.0
  - requires major rewrites, no backwards compatibility
  - http://wiki.libsdl.org/MigrationGuide

Annoyances / Bugs with Workarounds / Updates
--------------------------------------------

- investigate the possibility of a simple ada-to-python code converter to
  leverage python code scanning tools which are more abundant than ada ones.
- less command issues
  - e.g. less a file.  The arrow keys work.  TERM is correct.
  - eg. run spar then less a file.  The arrow keys do not work.  TERM is
   correct.
  - but the MORE command does work.
  - tput reset does not help
  - I don't change the Linux tty settings unless I do an inkey()
  - I am not certain of the cause
    - "unable to open script file ' /usr/bin/lesspipe src/parser.adb' : file not found" error on less during an interactive session?
      - less seems to run spar after it starts.
- when displaying error message in templates, using comments may not
  be enough to stop injecting bad data...perhaps, for example, the
  error happens in q quoted string.  It is necessary to escape the
  error message as appropriate to the context of the template
  document
   - check json escaping with templates - json has no comments
     so special chars must be escaped
- colour does not always switch back to the correct colour (i.e. bright
  white may revert to dim white after showing help index)
  - it may be impossible but setting the colour to bright what by default
    may be a partial solution
  - customizable colours / dark (or light) mode
- cache the prompt script byte code to speed up prompt drawing
- embedded sql - returning sql select in % (as JSON?) or by `..`?
- constant spec negative tests
  - array constant specifications
    - array foo referencing another foo during initialization (confirm)
    - likewise records
- design
  - design affinities - should work on branches of the file include tree
- handling confidential/PII data
  - pragma secure_mode
    - all data types assumed to have secure data
    - pragma public( var ) or similar to whitelist it
  - output channels must be whitelisted to use confidential data types
  - should this be generalized so there can be different sets of data
    and related channels?
- add annotate/categories to example programs representing the example groupings
  they belong to
- attaching comments to declarations so the comments can be parsed and displayed
  by the language.  This is to make configuration and debugging easier.
- problem extracting byte code for blocks (copying whole lines)
- doubly linked lists ought to automatically JSON encode aggregates, like
  btree_io does.?
- if you bungle "end record", the fields remain declared
  => type r is record i : integer; end x;
  (error)
  => type r is record i : integer; end record;
                      ^ already declared r.i
- the search with same name problem
    procedure p is
      x : integer := 5;
      procedure put_x is
      begin
        ? x;
      end put_x;
      procedure inner is
        x : string := "inner";
      begin
        put_x;
        -- puts "inner", not 5, as there is a new x that overshadows the
        -- x of the definition.  Would "overriding" help?  Or change when/how
        -- identifiers are handled at compile time.
      end inner;
    end outer;
- btree_io/hash_io
    - negative test btree_io.replace with cursor
    - negative test to ensure subprogram exceptions are not lost to parent
    - json decode backslash good regression tests
    - relative paths not working with bdb environments...research
    - option to throw an exception on missing values (including replace, get, add (existing value)
- memcache/memcache.highread
    - update design to use new resource system
    - memecache.new_cluster and sister function cannot return a value
      if resource using types are limited
- exceptions
    - what are semantics of throwing an exception in a subscript `...`
    - exceptions that propogate to the top aren't formatted properly in the
      Apache log (single chars means single lines)
- should create a report on process resources using getrusage(2).  Also will
   need this for memory leak tests (though there are command line ways of
   doing this).
- pragmas
    - can't declare two licenses or software_models.  This is a problem for a
      redistributable library
    - check double pragma import - test case
- unit testing and teamwork
    - restricted shell tests
    - xUnit support for tests (pragma test_result - output in JUNIT format?)
- records
  - if constant records/arrays are allowed,they should have static expressions
    during declaration assignments.
- strings
  - some string functions have string, not universal_string, parameters, which
    means parameters often must be typecast.  Probably they should be universal
    types.
  - strings.index is pretty useless without a position paramter.  Can we enhance
    it?
  - strings functions could be improved. (request by CY)
- dir ops
  - can we add a parameter to disable returning "." and "..", which require
    special handling in the majority of cases (because they are not needed)?
- graphics and sound
  - SDL - hardware accelleration not working with ...why not?
  - SDL needs to be upgraded for version 2.0
- type system
  - constant records are permitted but the fields are variables...the fields should all be constants
- build system
  - David B wants me to bring back SparForte shared library
    - shared library calling mechanism and integration with other languages
- procedures can't return values is a run-time check, but should be a
  compile-time check.  Do we need to record the type of current block in a
  scanner variable so the parser has a context to know what is allowed?

    Lua's approach to being called by another language:

    http://queue.acm.org/detail.cfm?id=1983083

    Java uses JNI

    http://en.wikipedia.org/wiki/Java_Native_Interface
    http://home.pacifier.com/~mmead/jni/cs510ajp/example_details.html
    http://download.oracle.com/javase/6/docs/technotes/guides/jni/spec/intro.html#wp9502

    - you can call java from c using standard calls
    - search for a class, load a method, run it
    - http://en.wikipedia.org/wiki/Java_Native_Interface
    - http://www.ibm.com/developerworks/java/library/j-jni/index.html
    - business shell, though, only imports variables right now

- shell
    - substring substitutions not implemented yet: ${#}, ${%}
    - windows size change is not refreshing the terminal settings?
- unsorted/misc
    - err_tokenize doesn't indent properly (e.g. s := `xxx - missing backquote)
    - spitbol support
      - http://www.dmitry-kazakov.de/match/match.htm
    - text_io's get requires a file but shouldn't, or docs should be updated
    - case..is doesn't accept an array element like a(i)
    - control-z handling - fork, send a sleep signal and reset scanner
    - get_line on an out mode file gives bad file descriptor but needs a better
      error message
    - function f(p), p should not be 'already exists' if there is a p in scope
    - change pegasock to use bdb format exceptions with filename in message?
    - check pragma block with @
    - @ for a(x) gives an unexpected exception
    - Apache doesn't allow command paramenters for running CGI scripts.  There
      should be an easy way to set the SDLC mode configuration without command
      parameters or hard-coding in the shebang.
    - Ada-compatible space in front of numbers should be pragma ada_95 because
      it's annoying throwback to line printers...but every conversion of a
      number would have to take into account adding/removing a space.
    - verify type checking not in executable parts so is done at compile-time
    - after running one of my scripts, the less command doesn't work
      properly, suggesting that some characteristic of the terminal
      was not restored properly
    - in some edge cases, you can invoke procedures before they are declared.
      As Spar reads the code, it treats the procedure call as a shell
      command (unless no_external_commands is specified).  This is caught in
      test mode, but should be caught in development mode but how do you
      do that?  Perhaps a list of all simple shell commands executed and
      compare new procedures against those names (CY).

Nice to Haves / Missing Functionality
-------------------------------------

- tokenized command history
  - it would be good to maintain a separate history table with the commands
    parsed out into their expanded values.  This may be helpful with auto
    correction or security.
- when doing autocorrection for shell commands like cd, it may be beneficial
  to prioritize based on command history and then fall back on the default
  order of the various checks
- when accepting command line input from standard input, it may be beneficial
  to treat commands as comments if it is determined they are being entered
  faster than a human could and are errors (suggesting a copy-and-paste error).
  However, this may conflict with the ability to feed in commands through
  standard input.
- strings.uuid - UUID support
  - https://datatracker.ietf.org/doc/html/rfc4122.html
- restrictions on loading
  - a pragma that prevents a script from loading when certain
    criteria is not met such as
    - memory
    - disk space
  - a system that identifies deprecated or vulnerable packages
    and refuses to load them
- foreach
  - in PHP, foreach returns a pointer to the items, not a copy.
- Java-style monitor
  - a restricted shell should prohibit certain Linux command names like "nc"
    (netcat) due to security, reading /etc/passwd, etc.
- programming-by-contract
  - optimizations - mark places in type tree where we know there's no need to
    search further for contracts.
- overriding renamings
  - require overriding on renamings of same identifier name but in different scope?
    - this requires a new function to check for pre-exisiting names in a different
      scope.  It will need to apply to all variable declarations.
    - maybe just   elsif identifiers( token ).kind = new_t or identifiers( token ).deleted then
- in python,files are opened like a declaration so they close automatically
   at end-of-block. Can I do something similar?
- refactor
  - parser_tio globals should be put in a separate package, or a different
    package, to help reduce circular dependencies
- memcache/memcache.highread
    - update functionality to handle records, arrays, etc. like btree_io
    - element as an alias for "get" in memcache, etc.
- generic types
    - subtypes of generic types
- user-defined packages
  - should packages support versioning (e.g. Composer/Cargo/NPM).  Should
    the language deal with expected versions with configuration block
    pragmas?  Should I deal with this at all?
  - package specifications should be renames, not forwards, since they
    can have their qualities modified on export (abstract, limited, constant)
    .. can that work?
  - should there be an option to reload a package on a filesystem change? or
    is this not the responsibility of the programming language?  that is,
    is it a service that needs to be stopped and restarted by an orchestration
    program, in a controlled way if there is a cluster with the script?
  - should loadable files have keyword/tag requirements to denote architectural
    concerns
    - i.e. tag a file is compatible with containers/jails, or not horizontally
      scalable, not public facing, etc.
  - affirms can be thought of as a specific case of "triggers" on a variable.
    Are their other triggers that can be defined?

- pragmas
    - distinguish types of pragmas, to later separate by block or context
    - a pragma to check for the version of SparForte?  Is it a doc pragma,
      executable or both?
    - pragma no_bourne_shell
    - pragma no_universal_types
    - pragma import( rest, function, "url" )
      - define something to be called by REST protocol.  (What to do about HTTPS?)
    - pragma restriction is too restrictive.  If the goal is to migrate
      designs, we need levels of restrictions.  For example, pragma
      pending_restriction( x ), similar to pragma deprecated, which is
      an error if x is used in the design phase only, and a warning in
      the development phase.
      - a way for archictural exceptions to be recorded, audited...i.e. with
        team member that OK'ed it.
    - pragma depreciated should be a list, not a string.
    - review and improve help command reports for producing system audit reports.  Are they complete?  Usable?  Any rsh restrictions needed?  For example, we need a software_model report.
    - while we want to default to security, we also want not to be overly restrictive with pragma restriction in general.  We should probably default to secure and add exceptions...how would i code that?
    - probably need a security pragma and not relying on rsh = security
    - should disallow access to certain files or directories like /etc/password by
      default, unless security pragma allows otherwise.  This is similar to Java's
      Security Manager.
      - while URL's can be aliased, paste-bin URLs should not appear in strings.
        However, should we be doing this type of malware filtering?
    - pragma deprecated is designed for scripts, but there is no way to deprecate
      subprograms, types, etc.  In general, I need to expand end-of-life
      and migration features.
    - teams package should be redesigned so team members can be more easily
      used with pragmas (that is, team member info should be available at
      syntax-check time)
- user role blocks
    - configuration/policy/project <name> ... is separate (not with separate, which isn't
      as specific)
    - more separation of concerns
      - with configuration
      - with policy
      - with project
      - project block
      - QA concerns?
    - some way to determine if a configuration/policy/project should have been loaded.
      perhaps an architectural pragma for same.
- unit testing and teamwork
    - "status board" generation option for oustanding/in-progress work
    - burndown charts option?
    - review Test concept...what other requirements are missing?
- tinyserve
  - close tinyserve if open
  - complete tinyserve package
  - epoll_ Linux commands and threads to scale
    - see libuv
    - see node.js talk https://www.youtube.com/watch?v=P9csgxBgaZ8&t=1186
- strings package
  - blocks should probably be inside isExecutingCommand if's
- os package
  - process id
- record constant specifications
  - case of record specifcation for foo referencing an older foo variable
    during assignment of initial values
- types and expressions
  - type is new (record type) not yet implemented.
  - private qualifier means copy-only on assignment...but aggregates
    currently cannot be assigned to or copied so private hasn't been
    implemented yet.
  - return arrays and records in expressions (requires records revamp)
    -- in mode records should be supported (but first require records
       (in expressions.
  - allow users to create their own universal types
  - record system refactor (in prep for aggregate expressions)
  - thoughts on user-defined universals
    - some features are looking for root storage types, but these are currently
      equivalent to the built-in universals.
    - since aggregates have no common structure, the type contained in a
      universal variable should be the type of the value being assigned.  This
      is, in essence, polymorphism.
      - should variables change type automatically or be declared as polymorphic?
      - should the notion of extension be reversed?  In Ada, types are about
        applying restrictions.  Would it make sense to have the root type to be
        the broadest type.  e.g. "type ... withOUT record x : integer..." to
        make storage items hidden/off-limits as opposed to adding new fields?
- templates
  - need template package to set return HTTP status
- strings
  - more validation functions
- build system
  - dynamic loadable built-in packages
  - fuzz testing (i.e. oss fuzz) - testing for vulnerabilities with random data
  - memory leak testing
- packages
  - new vector or game math package (quads, etc).
  - how can we enhance packages?  Should a "service" be a collection of packages?
- unsorted/misc
    - The GPS IDE needs a .gpr project file to build SparForte, but I am using
      standard C Makefiles.
    - should using too many built-in types in a formal script produce a style error?
    - support for literals in different bases
    - syntax check on templates, -e commands, policies, profiles
    - update dynamic_hash_table functionality to handle records, arrays, etc. like btree_io
    - standardize get_first as first, etc.
    - safety check that a file cannot include itself
    - redundancy and ways of handing command line option
    - enums.last is slow...should be updated for namespaces to improve speed
    - built-in cache - memory or disk?
    - redesign is_writable, etc. so works better.
    - raise [when]
    - infinite loop detection - when variables in loop expression are not assigned
      to - this may be tricky to implement
    - new examples
       - example program of ramdisk cache
    - GitHub readme.md "badges" (see also shields)
      - you need to be able to point at Jenkins.  A URL to the shields.io site
        containing an embedded URL to your Jenkins to get the data for the
        badge
      - http://shields.io/
      - example - https://github.com/seiyria/c
    - arrays of files / files in records are not implemented but are possible
       - update FirstFileParam, etc., to work with references
       - wasWritten on arrays and records
       - rewrite references to .value to look use utility functions
     - change or alias for consistency: set -> assign, get -> element
     - with include doesn't work on the command because it is loaded at syntax check
       time and the command line has no syntax check...but it would be good to load
       libraries at the command line so can I come up with a strategy to make it work?
   - libraries to load neutral (i.e. non-sf) config file formats?
   - got a "s already declared" when using s as a function parameter and
     s is declared in the outer scope but shouldn't be an error
      - the formal parameters are declared in the same scope as the subprogram
        name.  The block is used to destroy the actual, usuable parameters
        during the syntax check.  Moving the block only destroys the formal
        parameters.
      - not sure if SparForte has an existing mechanism for this

New Unique Concepts
-------------------

  - research
    - continue learning Rust - https://www.rust-lang.org
    - revisit Go - https://golang.org/
    - checkout Indris - https://www.idris-lang.org
    - check out D - https://dlang.org/
    - checkout Erlang for ideas
  - what can be done to promote better, easier, more detailed error messages?
  - SELinux-like ability to control who access what.
    - for any function, restrict it to a list of parent functions which
      may call it.
    - for any command, restrict it to a list of parent functions which
      may call it.
    - objects more complicated but not an issue now.
    - have an option for open access
    - how to you lock the list and enforce it?
    - % functionality should be extended and made usable in more contexts
       - chould % chain objects methods?  That is, % equals @ + first param?
  - parallel blocks
    - ability to track code meant to be used in pairs (e.g. defining two
      procedures, one must appear first, one must appear last, both should
      be used in the enclosing block)
  - writing code
    - embedded SQL or
    - generally, features to allow a program to construct programs safely
      in another language (e.g. SQL, shell or other), safeguarding from
      code injection or other issues.
    - for PostreSQL, SELECT ... INTO var FROM...  SparForte could use a
      similar approach to read results into its variables.
  - sofware model + archecture
    - allow architects to apply architecture policy to groups of software by the
      software model system.  Explore what needs to be involved.  should the
      software model be exposed through System?  Currently pragmas are applied
      directly to the current program, rather than triggered by pragma
      software_model and applied through some kind of architecture system.
  - units of measure
    - units of measure should be able to be changed dynamically at run-time
      - units.get_unit_of_measure / units.set_unit_of_measure
    - units of measure should be defined as a type (not unlike an exception)
      - a unit of measure should be related to a universal type (string/numeric)
      - define a standard record type for units with singular/plural/etc.
      - e.g. kilometers : unit_of_measure of universal_numeric := ("km", "kms");
    - allow the standard record type to be extended by subtype (providing
      alternate spellings but compatible) or new types.  Allow the creation
      of unit hierarchies.  e.g. null (root) units, currencies (abstract),
      dollars (english canadian) and subtype dollars (french canadian)
      - if not a record, functions can be in the units package to get the
        singular and plura values.
      - this requires derived records to be implemented
      - e.g. distance : integer in feet := 0;
        (where feet.singular := "foot", feet.plural := "feet")
    - a unit of measure should be able to be constant (unchanging at run-time)
      - e.g. distance : integer in constant feet := 0;
        (where feet.singular := "foot", feet.plural := "feet")
    - can units be applied to strings.  e.g. x : title in spanish or
      x : title in europe_region.  Affecting concatenation.
    - should multiple units be allowed?
    -  Is this a special case of multiple inherance, where x belongs to multiple
       hierarches?  Should it be generalized?  I'm thinking generalizing it with
       this way adds confusion.
  - naming convention
    - what are the naming standards of functions.  e.g. sin(), to_sin(), sin_of()?
  - type system
    - extending enums to strings and number sets
    - what about users creating their own universal types?
    - progamming by contract features - we have functions, so we can do them
      but can we do it elegantly rather than as an add-on to the existing
      syntax?
    - the similar types problem
      - Classes/Objects partially, but do not completely, eliminate the problem
        of using similar types together (notably, factory classes as a workaround
        for "new" only able to produce one type of object).  With the Ada-based
        strong typing system, we need a better way to define similar types,
        ensuring the these concepts are not limited to objects but can be used
        throughout the language
    - basic extensibility of aggregates
      - arrays and records should be part of the core typing system, so that they
        can be easily extended.  A record type, for example, shouldn't need "tagged"
        to be extended.  An array type should be able to be extended with
        new bounds (as the element type can be separately extensible).  'class
        should not be necessary if we can trace subtypes back to originating parent
        types.  (None of this should require objects, which
        are separate features to be introduced later.)
    - privacy should probably not use a "private" package section, but be a
      keyword in declarations.
    - abstract should be usable anywhere to create a type that is not intended
      to have a variable created of that type.
    - would syntax trees help? https://en.wikipedia.org/wiki/Abstract_syntax_tree
  - relations
    - business rules should have their own block as programmers may not be the
      one updating these rules.
    - object-oriented rules (having data attached to rules)
    - the executable part of the when should not allow if or case statements
    - each relation starts a recursive search
    - investigate: SQL is very similar to rules pattern matching.  Can this be leveraged
      as SparForte understands SQL?
    - reach relation requires
      - guard conditions (dependencies needed for a relation)
      - weights
      - state data
      - timeout?
      - the scheduler must pattern match appropriate rules in the agenda,
        the table of valid relations that can be considered next
      - is it more like a grammar (flat) or prolog (recursion)?
    - other issues
      - how does the boolean shortcut become a fact?
      - how do relations function in a restricted shell
      - what is the rule conflict detection and resolution strategy
    - examples:

      In its simplest form, we need a block for business
      users to enter options.  We would like to limit what
      is visible to the business user.

      options business_settings(i, j, k : integer) is

        tax_rate : constant float := 13.5;

      end business_settings;

      An options block may only contain constants.

      The main purpose, though, is to provide a place to
      hold business rules.

      relation Male(X) return boolean is
        -- a relation is essentially a list of case/when
      begin
        when X = ken =>
           return true;
        when others =>
           return false;
      end Male;

      relation Male(X) return true when X = ken;
      -- maybe one liners

      relation Love(X,Y) return boolean is
        when others =>
           return Male(X) and not Male(Y);
      end Love;

      Relations require namespacing or all relations will
      fire.


-------------------------------------------------------------------------------
KNOWN ISSUES/IDEAS
-----------------------------------------------------------------------------
- some of these issue may have been addressed but not removed from this list
  so check if they are still a problem

ISSUES (SparForte Environment)

  * build system (SparForte Environment)

  * regression test suite (SparForte Environemnt)
    - break up good test into lesser tests (just too many for debugging
      when there's a new error in the middle after massive changes)
    - should test in-line for with ada and shell statements
    - test upper ASCII escaped characters
    - new string functions: neg tests
    - for loops no longer confused by older vars of same name - neg test
    - test suite test for var existence after declare block end, array & itself,
      array casts, array subtypes, array default assignments, cmdline redirect &
      restricted shells, -e, in / not in operator, unchecked_import tests in
      test suite
    - command line redirection tests in testsuite
    - files.is_executable, files.is_readable, files.is_writable,
      files.last_modified need negative tests
    - tests for large numbers of open/close to make sure we don't run out
      file descriptors because of improper closures
    - changes to allow for "i : integer := i" not tested for arrays...that is,
      values being assigned to arrays probably can't contain the same name as
      the array.  See ParseDeclarationPart for how to handle this.
  - dir_separator, change_dir, remove_dir, get_current_dir, dir_name,
    base_name, file_extension, file_name, format_pathname, expand_path & test
  - enum package neg tests
  - is separate tests

  * sample programs
    - update the sample programs for subprograms
    - in morph.bush example, a single newline is output when Ada is shutting
      down.  Is something flushed or what??...BUT a short sample script doesn't
      have this behaviour.  Is this still an issue?
    - random numbers
      https://github.com/adrianhoe/adamt19937
      http://adrianhoe.com/adrianhoe/projects/adamt19937/
    - benchmarks
      - http://benchmarksgame.alioth.debian.org/
    - shell examples
      - http://comp.eonworks.com/scripts/scripts.html
      - http://www.shelldorado.com/scripts/categories.html
      - http://www.linuxlots.com/~dunne/scripts.html [broken?]


ISSUES (AdaScript)

  * latest
    - SOCK_NONBLOCK - obsolete in Linux, must be replaced
    - rpmlint complains about gethostbyname (IP4-specific) -> getaddrinfo
  * terminal control character escaping isn't working on readline prompt
    - bold is turned off temporarily on prompt

  * general syntax (AdaScript Issues)
    - implement scientific notation numeric literals
    - implement overloadable enumerateds
    - implement attributes (will need to change byte code compiler)
    - do not allow declarations between begin..end in a begin block
    - a range could be a new class.  That would allow arrays.range and a general
      parseRange
    - enumerateds should be upper-case, if this doesn't conflict with type-
      sensitivity
    - vim syntax - $$ doesn't work
    - unreachable code error doesn't indent token hilight properly
    - case cases are not checked for identical cases but should be.
    - cases should support ranges but don't yet.
    - should last output (%) be assignable?

  * assignments
    - naturals and positives compatibility (intTypesOK) not handled at
      assignment...is this fixed?
    - when declaring variables, should the type be optional when a value
      is assigned (so that the type of the value is used, like a command line
      auto declaration)?  This is how the Go language does it.

  * pragmas
    - should there be a pragma that runs after every command (as in
      the special trap for BASH)?
    - dual license support for pragma license?
    - pragma restriction( no_unextended_types ); -- variables must use
      user-defined types derived from standard ones?
    - additional safety features for pragma import/export?

  * pen package (AdaScript Issues)
    - pen package fails on AMD/Linux
    - pen package fails on FreeBSD with SDL/SVGALIB (interfers with Spar
      keyboard/mouse/display functions)
    - deferred picture load
    - locking issues
    - null_rect, all_rect
    - SDL/OpenGL binding

  * database packages (AdaScript Issues)
    - select statements should be pipeline-able (probably fails because the
      child process closes database socket when the APQ library quits)
    - db.schema can result in an error error
    - db.users and related information procedures should be builtin commands
      so they can be pipelined (ie. so "| less" can be used)
    - turning off formatting in pipelines or redirection (especially SQL
      commands which are unusable in wide layout format)
    - \ at end of line will cause an error on SQL statements
    - a database connection pool
    - use ligda (GNU data access) for portable data needs?

  * numerics
   - complete complex numbers - depends on complex types in expressions but expressions do not currently return aggregate values. A resource type cannot be used in expressions either because it is a limited type.

  * Text_IO package (AdaScript issues)
    - enumerated subtypes - put_line / ? do not print the correct enum item
    - set input/output/error cannot be redirected to an file_type in an array
    - get_line doesn't strip ASCII.CR like I thought
    - should "?" should trim strings?
    - close with no filename could close all open user files (ala BASIC,
      convenient for scripts)
    - output numbers with alternative bases
    - Allow standard output, etc. to be closed.  (We dup them anyway.)
    -   Does scanner reset cause Current_Output/etc. to be double dup()'ed
    - line count for a file doesn't work if put_line doesn't include the file
      variable or if it's a built-in file (standard_output, current_output,
      etc.)
    - managing files like types, by negotiating and have spar provide a
      recommended handle.  This would make the language more cloud-ready.
      e.g. type <filehandle> for <type> range <1..num_records>... to
      return a file handle on a device that meets these size requirements,
      whether in memory, on a hard drive, etc.  Similarily, specify if it needs
      to be fast, indexed, etc.  The architect could specify the options.

  * TCP/IP client sockets
    - "file /= eof_t" is wrong: standard_input could be specified explicitly
    - linux socket calls in bush_linux
    - set_output, etc. redirection for sockets
    - optimize fd - don't need to pull it out with stringField for every DoGet
    - rate limiting (set transfer speed per second)

  * command_line package (AdaScript issues)
    - command_line.argument() cannot be used in open...get an error.  Expects
      a type not a keyword...why?
    - implement gnat command_line

  * enumerated types
    - enumerateds are declare as constants of the enumerated type BUT if the
      user declares a constant of the enumerated type (a rare occurrence) it
      will be treated as an item of the enumerated type instead of a constant
      so there needs to be a symbol table flag to identify enumerated items.

  * sound package (AdaScript issues)
    - sound.mute, sound.unmute
    - Wavplay doesn't recover gracefully from errors...need to reset defaults
      especially after an error

  * strings package (AdaScript issues)
    - strings.replace_match/glob
    - strings.cvs - comma separated values - 2, 3, "hello", ... fields
    - strings.pcre_replace

  * files package (AdaScript Issues)
    - should it handle ~?
    - should restricted shell affect?

  * System package (AdaScript Issues)
    - System_Name should be enumerated

  * OS package
    - export variables are not exported before a os.system().  Should they be?
    - os.unrestricted_system vs. restricted system?  or restricted backquotes
      and unrestricted backquotes?

  * Pen package
    - TTF (True-type Fonts)
              /* Initialize the TTF library */
        if ( TTF_Init() < 0 ) {
                fprintf(stderr, "Couldn't initialize TTF: %s\n",SDL_GetError());
                SDL_Quit();
                return(2);
        }

        /* Open the font file with the requested point size */
        font = TTF_OpenFont(argv[0], ptsize);
        if ( font == NULL ) {
                fprintf(stderr, "Couldn't load %d pt font from %s: %s\n",
                                        ptsize, argv[0], SDL_GetError());
                cleanup(2);
        }
        TTF_SetFontStyle(font, renderstyle);
        TTF_SetFontOutline(font, outline);
        TTF_SetFontKerning(font, kerning);
        TTF_SetFontHinting(font, hinting);

        TTF_CloseFont(font);

        Basically two main functions:

        text = TTF_RenderText_Solid(font, string, *forecol);
        text = TTF_RenderText_Shaded(font, string, *forecol, *backcol)
        text = TTF_RenderText_Blended(TTF_Font *font, const char *text, SDL_Color fg);

        There are other functions to get font information, do UTF-8 or set features.

  * template issues (AdaScript Issues)
    - line numbering in templates - Text_IO skips blank lines.  Template
      scripts are missing blank lines, and throws line numbers off as a
      result.  May have to go with sequential I/O or UNIX file reading.

  * subprograms (AdaScript Issues)
    - parseFunction/ProcedureCallSemicolon requires rewriting parseGeneralStatement (that is, not one expect( ; ) for all general statements)
    - expressions should be able to return records and arrays
      - functions should be able to return records and arrays
    - forward procedures broken (commented out in tests) - params are broke
      when expecting forward subprogram

  * command types (AdaScript Issues)
      - can command types be implemented using appropriate pragmas
        instead of a special type (ie. pragma command (strvar) );?
   - command vars should be &-able with backquotes.

  * Ada package bindings
    - thick binding to: Gnat.Os_Lib
    - binding to: Byte_IO (sequential)

  - aggregates (AdaScript Issues)
    - arrays probably won't work as parameters to user-defined subprograms
    - errors when expecting scalars
    - assigning records to records
    - unsetting records
    - string should be an array type, but they are not arrays in the bush sense
    - ideally, unbounded_strings should not be a subtype of universal strings
      for compatibility with Ada 95.  As a result, an unbounded_string typecast
      shouldn't work but it does in AdaScript.
    - unconstrained arrays and forced initialization
    - if array return values are implemented, arrays should be initialized with
      array expression value.

  * ZMQ support (new package)
    - see https://github.com/persan/zeromq-Ada

ISSUES (Bourne Shell)

  - redirections (Shell Issues)
    - advanced job control (control-Z, fg, bg, etc.)

  - job control (Shell Issues)
    - check sig child flag after every general statement (already done?)
    - single user mode detection, disabling job control
    - SIGHUP handler: SIGHUP should be broadcast to all children like BASH

  - other shell issues (Shell Issues)
    - whitespacing after :-, etc. is permitted in Bourne shell but is an error in SparForte - e.g. ${HOME:- x } is permitted in Bash
    - SHELL variable doesn't always initialize to spar command path.  It doesn't handle ../
    - collating order with file globbing and locales
    - remove dependency on Ada.Command_Line.Environment -- not supported in Windows GNAT
    - an error terminates all commands in an interactive semi-colon list, but
      it should continue on for POSIX compatibility.  Is this resolvable?
    - because terminal attributes are toggled on and off, slow systems
      sometimes echo characters during input, throwing off the display
    - prompt script: final cr being ignored because it users compileandrun
      proc.
    - pathname completion "/" and " " append tests should use stat(), not
      Text_IO and GNAT Dir Ops.  Perhaps another c_os function??
    - insert sometimes inserts characters wrong in the command line.  Backing
      up, deleting and retyping is OK, but cursoring over and changing
      sometimes doesn't keep line position properly. Still an issue?
   - environment problems: using putenv removes the variable from the
     environment but GNAT's command_line package still looks for it and
     returns a garbage value for that environment entry (as if it caches the
     environment)
   - now that the initial environment is loaded at scanner startup, there may
     be environment issues...haven't thought it through
   - hash clash in pipeline for builtin--this might be fixed, confirm
   - Bourne shell compatibility and syntax checking: declaring variables in
     statements.  Is it worth it?  Example:
       while i < 2 loop
         if i = 0 then
           j : integer;
         end if;
       end loop;
    doesn't work since declarations are always done even if skipped because
    the symbols need to be in the symbol table when walking through the
    syntax even when the statements aren't being executed.  This is a rare
    case, but it also raises the issue of scope with pullBlock--technically,
    j is a global but pullBlock treats all internal declarations as local.
   - an undo for unset
   - unset does not work under pragma ada_95 but should

MAJOR REDESIGNS

  - architecture
    - pragmas for business architecture.  e.g. pragma licence (gpl),
      pragma license_limit_instances( 15 ), pragam license_limit_users( 12 )
  - redesigning the symbol table to handle non-string values
    - allows byte_io package based on sequential_io
    - implement use clause
    - multi-dimensional arrays
    - records should allow nested arrays
    - arrays should support nested arrays
    - linked lists or other container types
  - ParseExpression should return a storage record, not a string, so
    arrays can be returned (and future records, objects)

 - performance enhancements
    - should the universal type (i.e. storage type - univeral_string, array,
      root_enumerated, etc.) be stored with the variable
      so SparForte doesn't have to be looked up constantly?
      - commands like getBaseType could cache the result in the variable
      - would require updating most of the built-in functions
    - lineRead still reads as unbounded_string instead of copying directly
      into script variable, causing double buffering and conversion slowdowns
    - more sophisticated byte code for speed
       - this will require the scanner and parser holding two different tables for
         identifiers (because only the parser knowns what block(s) an identifier
         belongs to).  Otherwise, the existing get_next_token can be used to
         tokenize the script file.
    - change system calls to get tput results - remove system() reliance
    - "kind" field should be a pointer for speed, not an array index
    - no type-checking after syntax-check stage for performance?  But command
      prompt has no syntax check so must be excluded?
    - a pragma inline should be created in order to cache other scripts
    - DoRunTimeStatments should probably fork and use pipes to read results
      instead of using a temp file
      - otherwise, DoRunTimeStatements only read results one char at a time
    - instead of the fast string library, just store the first character in
      the identifier record and (optionally) test on that?  Use a new record
      type to prevent string assignments without updating the first character.
    - can word_t byte code items also contain a trailing "pattern" as well as
      "word"
    - .list and .FieldOf can be combined as .Owner of aggregate sub item, where
      .owner = eof_t indicates a simple variable.  This would simplify the code.
    - review parser/child package structure.  A better way to organize?

  * Platform issues
   - Spar hangs with vt52 40x8 login, throws exception (perhaps division by
     zero because attributes like bold null strings??)  Also has ctrl-q's
     so maybe a flow of control problem