orgs 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137
  1. == Dev note ===
  2. *note, see doc ledgers for info about org ledgers.
  3. they are *not* just a message in a table anymore... they have a timestamp and more.
  4. ===============
  5. Orgs are stored in modpol.orgs by the key 'org_name'
  6. Old ledgers of deleted orgs are stored in modpol.old_ledgers,
  7. if preserve records is enabled
  8. An org is a table with the following properties:
  9. {
  10. name = '', -- a unique name...
  11. this is a reference to the key used to store the org table. Changing this does not change the org name.
  12. policies = {}, -- a table to store the org's policies
  13. members = {}, -- a table that contains the member names
  14. or the org, in no particular order (TKTK: maybe change it so that members have a name:properties table?)
  15. ledger = {}, -- a table of ledger entries. See the ledger docs
  16. parent = nil, -- the name of the org that spawned this org.
  17. removing a parent org removes its children
  18. children = {}, -- a table of strings of org names of child orgs
  19. properties = { -- good for modules to store arbitrary info about the org here.
  20. },
  21. }
  22. API functions for orgs
  23. ======================
  24. a local variable setting 'preserve_records' determines whether
  25. to store old ledgers when an org is deleted. It is set to true.
  26. It would be possible to extend this to a settings file later.
  27. --==oo888888888888888888888888888888oo==--
  28. Function: modpol.record(org_name, msg, type)
  29. -- Params: strings msg, org, type
  30. -- Outputs:
  31. -- "msg" specifies an event and/or status message.
  32. -- "org" specifies an "org" name.
  33. -- "type" -- optional type of legder entry. Could be e.g. 'election_result', 'add_member', etc
  34. -- This function adds the message to a global ledger and, if "org"
  35. -- specifies a valid "org", to an "org"-specific ledger. Both the mem-
  36. -- ory-resident and on-disk copies of the data structures used are up-
  37. -- dated.
  38. -- the type input is used to be able to search ledgers for specific events
  39. --==oo888888888888888888888888888888oo==--
  40. Function: modpol.add_org(org_name, members, parent, properties)
  41. -- Params: string name, table members, string parent, table properties
  42. -- Parent must be an existing org, defaults to 'instance', properties
  43. -- are arbitrary properties to initialize the org with
  44. -- Output:
  45. -- This function creates an "org". It returns a boolean success indicator and
  46. -- either an error message starting with "Error:" or a success message.
  47. --
  48. --
  49. -- The string parameter specifies the "org" name.
  50. --
  51. -- The members table should be an integer-indexed array of member
  52. -- names.
  53. -- parent should be nil or a valid existing org name. If nil, defaults to
  54. -- 'instance'
  55. -- properties defaults to an empty table. Use it to initialize the org
  56. -- with arbitrary properties
  57. --==oo888888888888888888888888888888oo==--
  58. -- Function: modpol.remove_org(org_name, reason)
  59. -- Params: string name, opt string reason
  60. -- Output:
  61. --
  62. -- This function removes an "org". It returns a boolean
  63. -- success indicator and either an error message
  64. -- starting with "Error:" or a success message. It also recursively
  65. -- removes all child orgs, with 'remove parent org' as reason. If
  66. -- preserve_records is enabled, it logs the removal in the org ledger,
  67. -- and stores the ledger in modpol.old_legders
  68. --
  69. -- The string parameter specifies the "org" name.
  70. --
  71. -- The reason is an optional string to additionally include in the
  72. -- log as reason for removal
  73. --==oo888888888888888888888888888888oo==--
  74. Function: modpol.list_orgs()
  75. -- Params: None
  76. -- Output:
  77. -- This function returns a text-format list of "orgs". The list shows
  78. -- one "org" per line in the following format:
  79. -- org_name (member, member, ...)
  80. -- If there are no "orgs", the output is an empty string.
  81. --==oo888888888888888888888888888888oo==--
  82. Function: modpol.reset_orgs()
  83. -- Params: None
  84. -- Removes all orgs and recreates blank org "instance" with all
  85. -- current users
  86. -- returns confirmation message
  87. -- if preserve_records is enabled, stores all org ledgers
  88. -- in modpol.old_ledgers
  89. --==oo888888888888888888888888888888oo==--
  90. Function: modpol.add_member(org_name, member)
  91. -- Params: org_name (string), member (string)
  92. -- Output:
  93. -- Adds the specified member to the specified org
  94. -- Returns a boolean success indicator and
  95. -- either a confirmation or error message
  96. --==oo888888888888888888888888888888oo==--
  97. Function: modpol.is_member
  98. -- Params: org (string), member (string)
  99. -- Output: boolean, or nil and error message if not applicable. (org nonexistent)
  100. --==oo888888888888888888888888888888oo==--
  101. Function: modpol.remove_member
  102. -- Params: org (string), member (string)
  103. -- Output:
  104. -- Removes the specified member from the specified org
  105. -- Returns confirmation or error message