A new Perl API

Goal

The goal of the new Perl API is to be able to refactor the Perl code away from its current global-state-centric approach (which works for webapps) into a more generic library which can be used to develop e.g. command line applications or special-purpose extensions.

Elimination of current global state

Problematic classes

• SOLVED LedgerSMB::Sysconfig
  Currently holds the configuration for the entire Perl image.
  This class used to require a configuration file in the current directory - which is a big red flag for a library type of setup - but this problem has been addressed with recent changes.
• LedgerSMB::App_State
  Holds in its global state the current database connection and the preferences for the currently logged in user. This setup is too restrictive in a library-setup, because a library might want to create multiple connections to the same or different companies.
• SOLVED LedgerSMB::Company_Config
  Holds the configuration of the currently connected company; similar to LedgerSMB::App_State, this restricts the library to one active connection.
  This functionality is a wrapper around LedgerSMB::Setting->get(), getting all settings at once.
• LedgerSMB::PGObject
  This class (role) uses the global state of LedgerSMB::App_State and injects that in each of its derived classes. Other than that, it's a simple wrapper around PGObject::Simple::Role.
• SOLVED LedgerSMB::PGDate, LedgerSMB::PGNumber
  These classes depend on global state from LedgerSMB::App_State for formatting/parsing of input.
  Consensus has it that (user-)input parsing and (user-)output formatting belongs elsewhere; these classes serve as database-serializable representations of their in-memory parent classes

Problematic patterns

1. The most problematic pattern is the pattern used by LedgerSMB::PGObject, because of the fact that it underlies a lot of classes and it affects all code instantiating any of these classes.

2. SOLVED The formatting/parsing pattern of LedgerSMB::PGDate and LedgerSMB::PGNumber looks like a major problem at first, but the grep statement output below indicates that the impact of a replacement should be manageable as all the occurrences in Scripts/ and old/ should have access to the request object (providing a means to pass a parser/formatter):

[ grep results removed since the pattern is resolved... ]

Proposed alternative

The alternative is an API with a single entry point. This entry point is created with a pre-connected database and (run-context configuration; i.e. Sysconfig). This entry point propagates the database connection and configuration to objects that need it. This entry point provides access to all parts of the application through methods returning encapsulation of parts of the application (note that this does not need to coincide with class definitions):

  <main entry>
     -> me()            # connected user
        -> prefs()
     -> configuration() # company global configuration
        -> users()
        -> COANodes()
        -> GIFIs()
        -> warehouses()
        -> settings()
     -> entities()      # involved parties
        -> sics()
     -> goods()         # goods & services (including inventory?)
     -> timecards()     # time cards
     -> sales()
        -> customers()  # ECAs!
        -> quotes()
        -> orders()
        -> transactions()
        -> shipments()
     -> purchases()
        -> (same)
...