wiki:Macros
Last modified 5 years ago Last modified on 15.09.2013 00:25:41

Macros

What is this macro thing, anyway?

Macro is a way of retrieving information from an external system. This is crucial for dashboard application like DashWiki, as DashWiki doesn't store any state information on its own.

Macros use various protocols to retrieve information: it can be XML-RPC, plain HTTP, local file and others. Plugin API is described here: API/ProtocolPlugins?.

Macros are similar to the concept of function call in programming languages, except DashWiki provides markup language instead of programming language. Calling a macro in wiki source results in putting whatever was returned in place of the call when formatting dashboard for display.

As with functions, macro has a name, a list of arguments (may be empty), a body (protocol determines which protocol plugin is used, and plugin parameters parametrizes behaviour of the plugin; all this acts as a body) and returned value.

Components of a macro

destination URL

pfURL

accepted arguments

result type

protocol

Protocol plugins

protocol plugin parameters

pfJSON

Protocol plugins

API for protocol plugins?

pfJSON

The name stands for placeholder fancy JSON, or, if you like, printf formatted JSON.

Improvements over plain JSON:

  • comments -- who doesn't like them?
  • comma at the end of list or hash is optional, but possible
    • elements are consistently terminated
    • now go comment out the last element of a list!
  • string concatenation: "foo" "bar" is essentially the same as "foobar"
  • %(...)X placeholders (%(..)d, %(..)f, %(..)s, %(..)J), filled with macro's call parameters
    • JSON-syntax aware
    • with string concatenation, complex values are possible:
      # if "bar_value" macro argument contains "bar", this equals to
      #   "foo bar baz": ...
        "foo " %(bar_value)s " baz": ...
      

pfURL

As above, the name stands for placeholder fancy URL, or, if you like, printf formatted URL.

Placeholders syntax:

  • %(name)s
  • %(name)[opt,...]s

Unfortunately, no way of escaping placeholders at the moment.

Options are disabled by prefixing them with ! (e.g. !sub disables subdirectory enforcing). No space allowed in [...] section.

Default options:

  • sub
  • unhidden

Possible options:

  • sub (option enabled by default)
    • .. directory part is disallowed
  • direct_sub
    • no / whatsoever is allowed
    • sole . or .. as a value is disallowed, too
  • unhidden (option enabled by default)
    • any directory part beginning with period (.* in shell glob terms) is disallowed (this also means that the value itself can't begin with period)
  • url_encoded
    • all characters except for alphanumeric, underscore, dash, tilde, slash, period and comma are replaced by their %XX representation
    • NOTE: current implementation of this option is really slow; don't abuse it
  • encode_slash
    • slash itself is encoded as %2f