ui-coord.hpp

Go to the documentation of this file.

/*
  UI-COORD.hpp  -  generic topological location addressing scheme within the UI

   Copyright (C)
     2017,            Hermann Vosseler <Ichthyostega@web.de>

  **Lumiera** is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License as published by the
  Free Software Foundation; either version 2 of the License, or (at your
  option) any later version. See the file COPYING for further details.

*/


#ifndef STAGE_INTERACT_UI_COORD_H
#define STAGE_INTERACT_UI_COORD_H

#include "lib/error.hpp"
#include "lib/symbol.hpp"
#include "lib/path-array.hpp"
#include "lib/nocopy.hpp"
#include "lib/util.hpp"

#include <cstring>
#include <string>
#include <vector>
#include <utility>


namespace stage {
namespace interact {
  
  namespace error = lumiera::error;
  
  using std::string;
  using lib::Literal;
  using lib::Symbol;
  using util::unConst;
  using util::isnil;
  using util::min;
  
  enum {
    UIC_INLINE_SIZE = 8
  };
  
  /* === predefined DSL symbols === */
  
  enum UIPathElm
    {
      UIC_WINDOW,
      UIC_PERSP,
      UIC_PANEL,
      UIC_VIEW,
      UIC_TAB,
      UIC_PATH
    };
  
  
  extern const Symbol UIC_CURRENT_WINDOW; 
  extern const Symbol UIC_FIRST_WINDOW;   
  extern const Symbol UIC_ELIDED;         
  
  
  
  class UICoord
    : public lib::PathArray<UIC_INLINE_SIZE>
    {
      
    public:
      template<typename...ARGS>
      explicit
      UICoord (ARGS&& ...args) : PathArray(std::forward<ARGS> (args)...) { }
      
      UICoord (UICoord&&)                 = default;
      UICoord (UICoord const&)            = default;
      UICoord (UICoord& o)     : UICoord((UICoord const&)o) { }
      
      UICoord& operator= (UICoord const&) = default;
      UICoord& operator= (UICoord &&)     = default;
      
      
      
      /* === Builder API === */
      
      class Builder;
      
      UICoord (Builder&& builder);
      
      static Builder firstWindow();

      static Builder currentWindow();
      
      static Builder window (Literal windowID);
      
      //----- convenience shortcuts to start a copy-builder....
      Builder persp (Literal perspectiveID)  const;
      Builder panel (Literal panelID)const;
      Builder view  (Literal viewID) const;
      Builder tab   (Literal tabID)  const;
      Builder tab   (uint tabIdx)    const;
      Builder noTab ()               const;
      
      //----- convenience shortcuts to start mutation on a copy...
      Builder path (Literal pathDefinition) const;
      Builder append  (Literal elmID) const;
      Builder prepend (Literal elmID) const;
      Builder rebuild() const;
      
      
      
      /* === named component access === */
      
      Literal getWindow() const { return accesComponent (UIC_WINDOW);}
      Literal getPersp()  const { return accesComponent (UIC_PERSP); }
      Literal getPanel()  const { return accesComponent (UIC_PANEL); }
      Literal getView()   const { return accesComponent (UIC_VIEW);  }
      Literal getTab()    const { return accesComponent (UIC_TAB);   }
      
      
      
      /* === query functions === */
      
      bool
      isIncomplete()  const
        {
          return not empty()
             and isnil (getWindow());
        }
      
      bool
      isComplete()  const
        {
          return not empty()
             and not isnil (getWindow());
        }
      
      
      bool
      isExplicit()  const
        {
          return isComplete()
             and not util::contains (*this, Symbol::ANY);
        }
      
      
      bool
      isPresent (size_t idx)  const
        {
          Literal* elm = unConst(this)->getPosition(idx);
          return not isnil(elm)
             and *elm != Symbol::ANY;
        }
      
      
      bool
      isWildcard (size_t idx)  const
        {
          Literal* elm = unConst(this)->getPosition(idx);
          return elm
             and *elm == Symbol::ANY;
        }
      
      
      bool
      isExtendedBelow (UICoord const& parent)  const
        {
          size_t subSiz = this->size(),
                 parSiz = parent.size(),
                 idx    = 0;
          
          if (parSiz >= subSiz)
            return false;
          
          while (idx < parSiz
                 and (   (*this)[idx]== parent[idx]
                      or Symbol::ANY == parent[idx]
                      or isnil (parent[idx])))
            ++idx;
          
          ENSURE (idx < subSiz);
          return idx == parSiz;
        } // meaning: this goes further down
      
      
      
      /* === String representation === */
      
      explicit
      operator string()  const
        {
          if (isnil (*this))
            return "UI:?";
          
          string component = getComp();
          string path = getPath();
          
          if (isnil (component))
            return "UI:?/" + path;
          
          if (isnil (path))
            return "UI:" + component;
          else
            return "UI:" + component + "/" + path;
        }
      
      string
      getComp()  const
        {
          if (empty()) return "";
          
          size_t end = min (size(), UIC_PATH);
          size_t pos = indexOf (*begin());
          
          if (pos >= end)
            return ""; // empty or path information only
          
          string buff;
          buff.reserve(80);
          
          if (0 < pos) // incomplete UI-Coordinates (not anchored)
            buff += "?";
          
          for ( ; pos<end; ++pos )
            switch (pos) {
              case UIC_WINDOW:
                buff += getWindow();
                break;
              case UIC_PERSP:
                buff += "["+getPersp()+"]";
                break;
              case UIC_PANEL:
                buff += "-"+getPanel();
                break;
              case UIC_VIEW:
                buff += "."+getView();
                break;
              case UIC_TAB:
                if (UIC_ELIDED != getTab())
                  buff += "."+getTab();
                break;
              default:
                NOTREACHED ("component index numbering broken");
            }
          return buff;
        }
      
      string
      getPath()  const
        {
          size_t siz = size();
          if (siz <= UIC_PATH)
            return "";   // no path information
          
          string buff; // heuristic pre-allocation
          buff.reserve (10 * (siz - UIC_PATH));
          
          iterator elm = pathSeq();
          if (isnil (*elm))
            {  // irregular case : only a path fragment
              elm = this->begin();
              buff += "?/";
            }
          
          for ( ; elm; ++elm )
            buff += *elm + "/";
          
          // chop off last delimiter
          size_t len = buff.length();
          ASSERT (len >= 1);
          buff.resize(len-1);
          return buff;
        }
      
      iterator
      pathSeq()  const
        {
          return size()<= UIC_PATH? end()
                                  : iterator{this, unConst(this)->getPosition(UIC_PATH)};
        }
      
      
    private:
      friend class Builder;
      
      size_t
      findStartIdx()  const
        {
          REQUIRE (not empty());
          return indexOf (*begin());
        }
      
      Literal
      accesComponent (UIPathElm idx)  const
        {
          Literal* elm = unConst(this)->getPosition(idx);
          return elm? *elm : Symbol::EMPTY;
        }
      
      void
      setComponent (size_t idx, Literal newContent)
        {
          Literal* storage = expandPosition (idx);
          setContent (storage, newContent);
        }
      
      
      void
      setTailSequence (size_t idx, Literal newContent)
        {
          std::vector<Literal> elms;
          if (not isnil (newContent))
            {
              if (not std::strchr (newContent, '/'))
                {
                  // single element: just place it as-is
                  // and remove any further content behind
                  elms.emplace_back (newContent);
                }
              else
                { // it is actually a sequence of elements,
                  // which need to be split first, and then
                  // interned into the global symbol table
                  string sequence{newContent};
                  size_t pos = 0;
                  size_t last = 0;
                  while (string::npos != (last = sequence.find ('/', pos)))
                    {
                      elms.emplace_back (Symbol{sequence.substr(pos, last - pos)});
                      pos = last + 1;                         // delimiter stripped
                    }
                  sequence = sequence.substr(pos);
                  if (not isnil (sequence))
                    elms.emplace_back (Symbol{sequence});
            }   }
          
          setTailSequence (idx, elms);
        }
      
      void
      setTailSequence (size_t idx, std::vector<Literal>& pathElms)
        {
          size_t cnt = pathElms.size();
          expandPosition (idx + cnt); // preallocate
          for (size_t i=0 ; i < cnt; ++i)
            setContent (expandPosition(idx + i), pathElms[i]);
          size_t end = size();
          for (size_t i = idx+cnt; i<end; ++i)
            setContent (expandPosition(i), nullptr);
        }
      
      
    public: /* ===== relational operators : equality and partial order ===== */
      
      friend bool
      operator== (UICoord const& l, UICoord const& r)
      {
        return static_cast<PathArray const&> (l) == static_cast<PathArray const&> (r);
      }
      
      friend bool
      operator<  (UICoord const& l, UICoord const& r)
      {
        return l.isExtendedBelow (r);
      }
      
      friend bool operator>  (UICoord const& l, UICoord const& r) { return (r < l);             }
      friend bool operator<= (UICoord const& l, UICoord const& r) { return (l < r) or (l == r); }
      friend bool operator>= (UICoord const& l, UICoord const& r) { return (r < l) or (l == r); }
      friend bool operator!= (UICoord const& l, UICoord const& r) { return not (l == r);        }
    };
  
  
  
  
  
  /* === Builder API === */
  
  class LocationClause;
  
  class UICoord::Builder
    : util::MoveOnly
    {
    protected:
      UICoord uic_;
      
      template<typename...ARGS>
      explicit
      Builder (ARGS&& ...args)      : uic_{std::forward<ARGS> (args)...} { }
      Builder (UICoord && anonRef)  : uic_{std::move(anonRef)} { }
      Builder (UICoord const& base) : uic_{base} { }
      
      friend class UICoord;

    public:
      Builder (Builder &&)  = default;
      
      size_t size() const { return uic_.size(); }
      bool empty()  const { return uic_.empty();}
      
      UICoord const&
      uiCoord()
        {
          return uic_;
        }
      
      
      /* == Builder functions == */
      
      Builder&&
      window (Literal windowID)
        {
          uic_.setComponent (UIC_WINDOW, windowID);
          return std::move (*this);
        }
      
      Builder&&
      persp (Literal perspectiveID)
        {
          uic_.setComponent (UIC_PERSP, perspectiveID);
          return std::move (*this);
        }
      
      Builder&&
      panel (Literal panelID)
        {
          uic_.setComponent (UIC_PANEL, panelID);
          return std::move (*this);
        }

      Builder&&
      view (Literal viewID)
        {
          uic_.setComponent (UIC_VIEW, viewID);
          return std::move (*this);
        }
      
      Builder&&
      tab (Literal tabID)
        {
          uic_.setComponent (UIC_TAB, tabID);
          return std::move (*this);
        }
      
      Builder&&
      tab (uint tabIdx)
        {
          uic_.setComponent (UIC_TAB, Symbol{"#"+util::toString (tabIdx)});
          return std::move (*this);
        }
      
      Builder&&
      noTab()
        {
          uic_.setComponent (UIC_TAB, UIC_ELIDED);
          return std::move (*this);
        }
      
      
      Builder&&
      append (Literal elm)
        {
          if (not isnil(elm))
            uic_.setTailSequence (uic_.size(), elm);
          return std::move (*this);
        }
      
      Builder&&
      prepend (Literal elmID)
        {
          if (not uic_.isIncomplete())
            throw error::Logic ("Attempt to prepend "+elmID
                               +" to the complete rooted path "+string(uic_));
          
          uic_.setComponent (uic_.findStartIdx() - 1, elmID);
          return std::move (*this);
        }
      
      Builder&&
      path (Literal pathDef)
        {
          uic_.setTailSequence (UIC_PATH, pathDef);
          return std::move (*this);
        }

      Builder&&
      truncateTo (size_t depth)
        {
          uic_.truncateTo (depth);
          return std::move (*this);
        }
      
      operator LocationClause();
      LocationClause create();
      
    protected:
      Builder&&
      normalise()
        {
          uic_.normalise();
          return std::move (*this);
        }
      
      Builder&&
      overwrite (size_t depth, Literal newSpec)
        {
          Literal* storage = uic_.expandPosition (depth);
          uic_.setContent (storage, newSpec);
          return std::move (*this);
        }
    };
  
  
  
  inline
  UICoord::UICoord (Builder&& builder)
    : UICoord{std::move (builder.uic_)}
    {
      PathArray::normalise();
    }
  
  
  inline UICoord::Builder
  UICoord::currentWindow()
  {
    return window (UIC_CURRENT_WINDOW);
  }
  
  inline UICoord::Builder
  UICoord::firstWindow()
  {
    return window (UIC_FIRST_WINDOW);
  }

  inline UICoord::Builder
  UICoord::window (Literal windowID)
  {
    return Builder{windowID};
  }
  
  
  inline UICoord::Builder
  UICoord::persp (Literal perspectiveID)  const
  {
    return Builder(*this).persp (perspectiveID);
  }
  
  inline UICoord::Builder
  UICoord::panel (Literal panelID)  const
  {
    return Builder(*this).panel (panelID);
  }

  inline UICoord::Builder
  UICoord::view (Literal viewID)  const
  {
    return Builder(*this).view (viewID);
  }
  
  inline UICoord::Builder
  UICoord::tab (Literal tabID)  const
  {
    return Builder(*this).tab (tabID);
  }
  
  inline UICoord::Builder
  UICoord::tab (uint tabIdx)  const
  {
    return Builder(*this).tab (tabIdx);
  }
  
  inline UICoord::Builder
  UICoord::noTab ()  const
  {
    return Builder(*this).noTab();
  }
  
  inline UICoord::Builder
  UICoord::path (Literal pathDefinition)  const
  {
    return Builder(*this).path (pathDefinition);
  }
  
  inline UICoord::Builder
  UICoord::append (Literal elmID)  const
  {
    return Builder(*this).append (elmID);
  }
  
  inline UICoord::Builder
  UICoord::prepend (Literal elmID)  const
  {
    return Builder(*this).prepend (elmID);
  }
  
  inline UICoord::Builder
  UICoord::rebuild ()  const
  {
    return Builder(*this);
  }
  
  
  
}}// namespace stage::interact
#endif /*STAGE_INTERACT_UI_COORD_H*/