rework orgs. Add various properties to orgs. Make all org functions return success boolean as well as error/success string message.

modpol/DOCS/orgs

@@ -0,0 +1,137 @@
+== Dev note ===
+*note, see doc ledgers for info about org ledgers.
+they are *not* just a message in a table anymore... they have a timestamp and more.
+===============
+
+
+Orgs are stored in modpol.orgs by the key 'org_name'
+
+Old ledgers of deleted orgs are stored in modpol.old_ledgers, 
+if preserve records is enabled
+
+An org is a table with the following properties:
+
+{
+   name = '', -- a unique name... 
+        this is a reference to the key used to store the org table. Changing this does not change the org name. 
+   policies = {}, -- a table to store the org's policies
+   members = {}, -- a table that contains the member names 
+        or the org, in no particular order (TKTK: maybe change it so that members have a name:properties table?)
+   ledger = {}, -- a table of ledger entries. See the ledger docs
+   parent = nil, -- the name of the org that spawned this org.
+        removing a parent org removes its children
+   children = {}, -- a table of strings of org names of child orgs
+   properties = { -- good for modules to store arbitrary info about the org here.
+      
+   },
+
+}
+
+
+API functions for orgs
+======================
+
+a local variable setting 'preserve_records' determines whether 
+to store old ledgers when an org is deleted. It is set to true. 
+It would be possible to extend this to a settings file later.
+
+--==oo888888888888888888888888888888oo==--
+Function: modpol.record(org_name, msg, type)
+-- Params: strings msg, org, type
+-- Outputs:
+-- "msg" specifies an event and/or status message.
+-- "org" specifies an "org" name.
+-- "type" -- optional type of legder entry. Could be e.g. 'election_result', 'add_member', etc
+
+
+-- This  function adds  the message to a  global ledger  and, if "org"
+-- specifies a valid "org", to an "org"-specific ledger. Both the mem-
+-- ory-resident and on-disk copies of the data structures used are up-
+-- dated.
+-- the type input is used to be able to search ledgers for specific events
+
+--==oo888888888888888888888888888888oo==--
+
+Function: modpol.add_org(org_name, members, parent, properties)
+-- Params:   string name, table members, string parent, table properties
+-- Parent must be an existing org, defaults to 'instance', properties 
+-- are arbitrary properties to initialize the org with
+
+-- Output:
+-- This function creates an "org".  It returns a boolean success indicator and
+-- either an error message starting with "Error:" or a success message.
+--
+--
+-- The string parameter specifies the "org" name.
+--
+-- The members table should  be an  integer-indexed array of member
+-- names.
+
+-- parent should be nil or a valid existing org name. If nil, defaults to 
+-- 'instance'
+
+-- properties defaults to an empty table. Use it to initialize the org 
+-- with arbitrary properties
+
+--==oo888888888888888888888888888888oo==--
+
+-- Function: modpol.remove_org(org_name, reason)
+-- Params:   string name, opt string reason
+-- Output:
+--
+-- This function removes an "org".  It returns a boolean
+-- success indicator and either an error message
+-- starting with "Error:" or a success message. It also recursively 
+-- removes all child orgs, with 'remove parent org' as reason. If 
+-- preserve_records is enabled, it logs the removal in the org ledger,
+-- and stores the ledger in modpol.old_legders
+--
+-- The string parameter specifies the "org" name.
+--
+-- The reason is an optional string to additionally include in the 
+-- log as reason for removal
+
+--==oo888888888888888888888888888888oo==--
+
+Function: modpol.list_orgs()
+-- Params:   None
+-- Output:
+-- This function returns a text-format list of "orgs".  The list shows
+-- one "org" per line in the following format:
+-- org_name (member, member, ...)
+-- If there are no "orgs", the output is an empty string.
+
+--==oo888888888888888888888888888888oo==--
+
+
+Function: modpol.reset_orgs()
+-- Params:   None
+-- Removes all orgs and recreates blank org "instance" with all
+-- current users
+-- returns confirmation message
+-- if preserve_records is enabled, stores all org ledgers
+-- in modpol.old_ledgers
+
+--==oo888888888888888888888888888888oo==--
+
+Function: modpol.add_member(org_name, member)
+-- Params: org_name (string), member (string)
+-- Output:
+-- Adds the specified member to the specified org
+-- Returns a boolean success indicator and
+-- either a confirmation or error message
+
+--==oo888888888888888888888888888888oo==--
+
+Function: modpol.is_member
+-- Params: org (string), member (string)
+-- Output: boolean, or nil and error message if not applicable. (org nonexistent)
+
+
+--==oo888888888888888888888888888888oo==--
+
+Function: modpol.remove_member
+-- Params: org (string), member (string)
+-- Output:
+-- Removes the specified member from the specified org
+-- Returns confirmation or error message