Modpol/modpol/DOCS/orgs

== 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_id', a unique integer

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_id, msg, type)
-- Params: strings msg, type, org_id (number)
-- 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_id, members, parent, properties)
-- Params:   org)id (number), 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_id, reason)
-- Params:   org_id (number), 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_id, member)
-- Params: org_id (number), 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 (number), member (string)
-- Output: boolean, or nil and error message if not applicable. (org nonexistent)


--==oo888888888888888888888888888888oo==--

Function: modpol.remove_member
-- Params: org (number), member (string)
-- Output:
-- Removes the specified member from the specified org
-- Returns confirmation or error message