first commit

customerportal/include/htmlpurify/docs/proposal-plists.txt

@@ -0,0 +1,218 @@
+THE UNIVERSAL DESIGN PATTERN: PROPERTIES
+
+Steve Yegge
+
+
+
+Implementation:
+
+    get(name)
+
+    put(name, value)
+
+    has(name)
+
+    remove(name)
+
+    iteration, with filtering [this will be our namespaces]
+
+    parent
+
+
+
+Representations:
+
+    - Keys are strings
+
+    - It's nice to not need to quote keys (if we formulate our own language,
+
+      consider this)
+
+    - Property not present representation (key missing)
+
+    - Frequent removal/re-add may have null help. If null is valid, use
+
+      another value. (PHP semantics are weird here)
+
+
+
+Data structures:
+
+    - LinkedHashMap is wonderful (O(1) access and maintains order)
+
+    - Using a special property that points to the parent is usual
+
+    - Multiple inheritance possible, need rules for which to lookup first
+
+    - Iterative inheritance is best
+
+    - Consider performance!
+
+
+
+Deletion
+
+    - Tricky problem with inheritance
+
+    - Distinguish between "not found" and "look in my parent for the property"
+
+    [Maybe HTML Purifier won't allow deletion]
+
+
+
+Read/write asymmetry (it's correct!)
+
+
+
+Read-only plists
+
+    - Allow ability to freeze [this is what we have already]
+
+    - Don't overuse it
+
+
+
+Performance:
+
+    - Intern strings (PHP does this already)
+
+    - Don't be case-insensitive
+
+    - If all properties in a plist are known a-priori, you can use a "perfect"
+
+      hash function. Often overkill.
+
+    - Copy-on-read caching "plundering" reduces lookup, but uses memory and can
+
+      grow stale. Use as last resort.
+
+    - Refactoring to fields. Watch for API compatibility, system complexity,
+
+      and lack of flexibility.
+
+    - Refrigerator: external data-structure to hold plists
+
+
+
+Transient properties:
+
+    [Don't need to worry about this]
+
+    - Use a separate plist for transient properties
+
+    - Non-numeric override; numeric should ADD
+
+    - Deletion: removeTransientProperty() and transientlyRemoveProperty()
+
+
+
+Persistence:
+
+    - XML/JSON are good
+
+    - Text-based is good for readability, maintainability and bootstrapping
+
+    - Compressed binary format for network transport [not necessary]
+
+    - RDBMS or XML database
+
+
+
+Querying: [not relevant]
+
+    - XML database is nice for XPath/XQuery
+
+    - jQuery for JSON
+
+    - Just load it all into a program
+
+
+
+Backfills/Data integrity:
+
+    - Use usual methods
+
+    - Lazy backfill is a nice hack
+
+
+
+Type systems:
+
+    - Flags: ReadOnly, Permanent, DontEnum
+
+    - Typed properties isn't that useful [It's also Not-PHP]
+
+    - Seperate meta-list of directive properties IS useful
+
+    - Duck typing is useful for systems designed fully around properties pattern
+
+
+
+Trade-off:
+
+    + Flexibility
+
+    + Extensibility
+
+    + Unit-testing/prototype-speed
+
+    - Performance
+
+    - Data integrity
+
+    - Navagability/Query-ability
+
+    - Reversability (hard to go back)
+
+
+
+HTML Purifier
+
+
+
+We are not happy with our current system of defining configuration directives,
+
+because it has become clear that things will get a lot nicer if we allow
+
+multiple namespaces, and there are some features that naturally lend themselves
+
+to inheritance, which we do not really support well.
+
+
+
+One of the considered implementation changes would be to go from a structure
+
+like:
+
+
+
+array(
+
+    'Namespace' => array(
+
+        'Directive' => 'val1',
+
+        'Directive2' => 'val2',
+
+    )
+
+)
+
+
+
+to:
+
+
+
+array(
+
+    'Namespace.Directive' => 'val1',
+
+    'Namespace.Directive2' => 'val2',
+
+)
+
+
+
+The below implementation takes more memory, however, and it makes it a bit
+