[TASK] Move documentation to reST 96/39996/2
authorFrancois Suter <francois@typo3.org>
Fri, 5 Jun 2015 15:38:22 +0000 (17:38 +0200)
committerFrancois Suter <francois@typo3.org>
Fri, 5 Jun 2015 15:39:13 +0000 (17:39 +0200)
Resolves: #67314
Releases: 2.0
Change-Id: I45c3c613814ffd8b5118fc6e4d80f0b0917d72e2
Reviewed-on: http://review.typo3.org/39996
Reviewed-by: Francois Suter <francois@typo3.org>
Tested-by: Francois Suter <francois@typo3.org>
25 files changed:
ChangeLog
Classes/Exception/Exception.php
Classes/ViewHelpers/EvaluateViewHelper.php
Documentation/.gitignore [new file with mode: 0644]
Documentation/Developer/Api/Index.rst [new file with mode: 0644]
Documentation/Developer/Exceptions/Index.rst [new file with mode: 0644]
Documentation/Developer/Hooks/Index.rst [new file with mode: 0644]
Documentation/Developer/Index.rst [new file with mode: 0644]
Documentation/Developer/NewFunctions/Index.rst [new file with mode: 0644]
Documentation/Developer/NewKeys/Index.rst [new file with mode: 0644]
Documentation/Developer/Security/Index.rst [new file with mode: 0644]
Documentation/Developer/Variables/Index.rst [new file with mode: 0644]
Documentation/Developer/ViewHelper/Index.rst [new file with mode: 0644]
Documentation/Includes.txt [new file with mode: 0644]
Documentation/Index.rst [new file with mode: 0644]
Documentation/Installation/Index.rst [new file with mode: 0644]
Documentation/Introduction/Index.rst [new file with mode: 0644]
Documentation/KnownProblems/Index.rst [new file with mode: 0644]
Documentation/Settings.yml [new file with mode: 0644]
Documentation/User/ExpressionKeys/Index.rst [new file with mode: 0644]
Documentation/User/ExpressionSyntax/Index.rst [new file with mode: 0644]
Documentation/User/FunctionKeys/Index.rst [new file with mode: 0644]
Documentation/User/Index.rst [new file with mode: 0644]
doc/manual.pdf [deleted file]
doc/manual.sxw [deleted file]

index 38a03f7..72993eb 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,6 +1,7 @@
 2015-06-05 Francois Suter (Cobweb)  <typo3@cobweb.ch>
 
        * Moved to namespaces, verified compatibility with TYPO3 CMS 7, resolves #67305
+       * Moved documentation to reST, resolves #67314
 
 2015-05-09 Francois Suter (Cobweb)  <typo3@cobweb.ch>
 
index 1531f4e..d62e222 100644 (file)
@@ -19,7 +19,7 @@ namespace Cobweb\Expressions\Exception;
  *
  * @author Francois Suter (Cobweb) <typo3@cobweb.ch>
  * @package TYPO3
- * @subpackage tx_tesseract
+ * @subpackage tx_expressions
  */
 class Exception extends \Exception {
 }
index dcaaa16..284e52c 100644 (file)
@@ -48,7 +48,7 @@ use TYPO3\CMS\Fluid\Core\ViewHelper\AbstractViewHelper;
  * = Examples =
  *
  * Assuming that namespace has been declared as follows:
- * {namespace expression = Tx_Expressions_ViewHelpers}
+ * {namespace expression = Cobweb\Expressions\ViewHelpers}
  *
  * <code title="Simple string with expression to evaluate">
  * <expression:evaluate>Current page id is \{tsfe:id\}</expression:evaluate>
diff --git a/Documentation/.gitignore b/Documentation/.gitignore
new file mode 100644 (file)
index 0000000..4940b84
--- /dev/null
@@ -0,0 +1,24 @@
+#########################
+# Git
+# global ignore file
+########################
+# ignoring temporary files (left by e.g. vim)
+# ignoring by common IDE's used directories/files
+# dont ignore .rej and .orig as we want to see/clean files after conflict resolution
+#
+# for local exclude patterns please edit .git/info/exclude
+#
+*~
+*.bak
+*.idea
+*.project
+*.swp
+.buildpath
+.cache
+.project
+.session
+.settings
+.TemporaryItems
+.webprj
+_make
+nbproject
diff --git a/Documentation/Developer/Api/Index.rst b/Documentation/Developer/Api/Index.rst
new file mode 100644 (file)
index 0000000..706d08d
--- /dev/null
@@ -0,0 +1,98 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-api:
+
+API
+^^^
+
+This section describes the API made available in the parser class
+(:code:`\Cobweb\Expressions\ExpressionParser`).
+
+All the methods are static, so there's no need to create an
+instance of the parser class. To evaluate a string, simply make a call
+like:
+
+.. code:: php
+
+       $parsedString = \Cobweb\Expressions\ExpressionParser::evaluateString($string, TRUE);
+
+
+- `evaluateExpression`_
+- `evaluateString`_
+- `setExtraData`_
+- `setVars`_
+
+
+.. _developer-api-evaluate-expression:
+
+evaluateExpression
+""""""""""""""""""
+
+This method evaluates a single expression and returns the value.
+
+Parameters
+  $expression
+    The string to parse and evaluate. This string is not
+    expected to contain subexpressions. Use :code:`evaluateString()` instead.
+
+
+.. _developer-api-evaluate-string:
+
+evaluateString
+""""""""""""""
+
+This method parses a string and evaluates every expression that it
+contains. Furthermore the resulting string itself can be evaluated as
+an expression.
+
+Parameters
+  $string
+    The string to parse. It may contain subexpressions, which
+    will be parsed appropriately.
+
+  $doEvaluation
+    Boolean, true by default. If true the string itself is
+    evaluated as an expression, after all subexpressions have been
+    evaluated. If false, the string itself is not evaluated.
+
+
+.. _developer-api-set-vars:
+
+setVars
+"""""""
+
+This method can be used to store so-called :ref:`"internal" variables <developer-variables>` inside
+a static member variable of the parser class (see below).
+
+Parameters
+  $vars
+    An array of any size.
+
+  $reset
+    Boolean. If true, the existing "internal" variables will be
+    overridden by the content of :code:`$data`. If false (which is the default),
+    the content of $data is merged with existing "internal" variables.
+
+
+.. _developer-api-set-extra-data:
+
+setExtraData
+""""""""""""
+
+This method can be used to store so-called :ref:`"external" variables <developer-variables>` inside
+a static member variable of the parser class (see below).
+
+Parameters
+  $data
+    An array of any size.
+
+  $reset
+    Boolean. If true, the existing "external" variables will be
+    overridden by the content of :code:`$data`. If false (which is the default),
+    the content of $data is merged with existing "external" variables.
diff --git a/Documentation/Developer/Exceptions/Index.rst b/Documentation/Developer/Exceptions/Index.rst
new file mode 100644 (file)
index 0000000..d86993f
--- /dev/null
@@ -0,0 +1,19 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-exceptions:
+
+Exceptions
+^^^^^^^^^^
+
+Method :code:`evaluateExpression()` may throw a number of
+exceptions. The :code:`evaluateString()` method will catch them, but
+if you call :code:`evaluateExpression()` directly you will have to
+take care of these exceptions.
+
+All exceptions will be of type :code:`\Cobweb\Expressions\Exception\Exception`.
diff --git a/Documentation/Developer/Hooks/Index.rst b/Documentation/Developer/Hooks/Index.rst
new file mode 100644 (file)
index 0000000..8b22f1d
--- /dev/null
@@ -0,0 +1,40 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-hooks:
+
+Hooks
+^^^^^
+
+There's one hook available in the parser library. It allows the
+manipulation of the value resulting from an expression. It must be
+registered with something like:
+
+.. code:: php
+
+   $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['expressions']['postprocessReturnValue'][] = 'Vendor\\MyExtension\\Hook\\MyExpressionHook';
+
+It must implement the :code:`\Cobweb\Expressions\ValuePostProcessorInterface`
+interface. Here's a sample code:
+
+.. code:: php
+
+       namespace Vendor\MyExtension\Hook;
+       class MyExpressionHook implements \Cobweb\Expressions\ValuePostProcessorInterface {
+               public function postprocessReturnValue($value) {
+                       if (is_numeric($value)) {
+                               $value += 30;
+                       }
+                       return $value;
+               }
+       }
+
+This sample code will add 30 to the given value, if it is numeric.
+
+As can be seen, the hook method receives the value itself and is
+expected to return it, even if unchanged.
diff --git a/Documentation/Developer/Index.rst b/Documentation/Developer/Index.rst
new file mode 100644 (file)
index 0000000..3734fdc
--- /dev/null
@@ -0,0 +1,31 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _developer:
+
+Developer's Guide
+-----------------
+
+This chapter describes what can be achieved using the library provided
+by this extension.
+
+
+.. toctree::
+   :maxdepth: 5
+   :titlesonly:
+   :glob:
+
+   Api/Index
+   Variables/Index
+   Exceptions/Index
+   NewKeys/Index
+   NewFunctions/Index
+   Hooks/Index
+   ViewHelper/Index
+   Security/Index
+
diff --git a/Documentation/Developer/NewFunctions/Index.rst b/Documentation/Developer/NewFunctions/Index.rst
new file mode 100644 (file)
index 0000000..9e9cf9b
--- /dev/null
@@ -0,0 +1,61 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-new-functions:
+
+Introducing new functions
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Just like with keys, it is possible to use a hook to introduce custom
+functions, which makes it possible to do pretty much whatever one
+wants with expressions. An example class is provided in
+:file:`Classes/Sample/FunctionProcessor.php` . It
+introduces a function called "offset". To make this function
+available, it must be registered as follows:
+
+.. code:: php
+
+   $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['expressions']['customFunction']['offset'] = 'Cobweb\\Expressions\\Sample\\FunctionProcessor->offset';
+
+The function itself looks like this:
+
+.. code:: php
+
+       public function offset($parameters, $parentObject) {
+               $value = intval($parameters[0]);
+               $offset = 0;
+               if (isset($parameters[1])) {
+                       $offset = intval($parameters[1]);
+               }
+               return $value + $offset;
+       }
+
+
+It receives an array containing the function call parameters and what
+would normally be a back-reference to the calling object, but is
+actually a dummy object, since the :code:`\Cobweb\Expressions\ExpressionParser`
+class is purely static. The call parameters array is an indexed array
+containing:
+
+- at index 0, the value that was calculated from the expression
+
+- at index 1 and more, any additional parameters that were defined in
+  the function call.
+
+As an example, consider the following expression using this custom
+function:
+
+.. code:: text
+
+   gp:foo->offset:5
+
+The :code:`offset()` method will receive the value of "gp:foo" in
+:code:`$parameters[0]` and "5" in :code:`$parameters[1]`.
+
+The function is expected to return the modified value, or the original
+value from the expression if no change happened.
diff --git a/Documentation/Developer/NewKeys/Index.rst b/Documentation/Developer/NewKeys/Index.rst
new file mode 100644 (file)
index 0000000..97ab16a
--- /dev/null
@@ -0,0 +1,86 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-new-keys:
+
+Introducing new keys
+^^^^^^^^^^^^^^^^^^^^
+
+Using hooks it is possible to create classes that can interpret new
+keys. The first step is to create a class that implements the
+:code:`\Cobweb\Expressions\KeyProcessorInterface` interface. This interface
+defines a single method called :code:`getValue()` which is expected to return
+some value after having interpreted the string it receives. What the
+method receives is the part of the expression that comes after the
+colon. For example, if the expression is:
+
+.. code:: text
+
+       key:value1|value2|value3...
+
+the method will received "value1\|value2\|value3" as argument. The
+method should handle that string and return whatever makes sense. It
+may throw exceptions to show that the input was not valid and didn't
+lead to a valid result.
+
+If an exception is to be thrown, it is advised to throw a
+:code:`\Cobweb\Expressions\Exception\Exception` or some
+descendant of it.
+
+The class must then be registered in your extension's :code:`ext\_localconf.php` file,
+using the following syntax:
+
+.. code:: php
+
+       $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['expressions']['keyProcessor'][key] = 'Vendor\\MyExtension\\Processor\\MyKeyProcessor';
+
+.. important::
+
+   This differs slightly from usual hooks. In this case the
+   expression key that can be interpreted by the class is used as a key
+   in the hook array. The advantage is
+   that all registered hooks are not called unnecessarily every time a
+   custom key is found. The limitation is that there can be only one
+   registered hook per custom key, but it wouldn't make sense anyway to
+   have several classes to handle the same custom key.
+
+
+.. _developer-new-keys-example:
+
+Example
+"""""""
+
+Assume the following expression must be parsed:
+
+.. code:: text
+
+   negative:yes
+
+The class to handle it will have to be registered as:
+
+.. code:: php
+
+   $GLOBALS['TYPO3_CONF_VARS']['EXTCONF']['expressions']['keyProcessor']['negative'] = 'Vendor\\MyExtension\\Processor\\MyKeyProcessor';
+
+It will receive "yes" as an input. The code of the class may be
+something like:
+
+.. code:: php
+
+       namespace Vendor\MyExtension\Processor;
+       class MyKeyProcessor implements \Cobweb\Expressions\KeyProcessorInterface {
+               public function getValue($indices) {
+                       $value = 'Yes';
+                       if ($indices == 'yes') {
+                               $value = 'No';
+                       }
+                       return $value;
+               }
+       }
+
+In the above example, it will return "No".
diff --git a/Documentation/Developer/Security/Index.rst b/Documentation/Developer/Security/Index.rst
new file mode 100644 (file)
index 0000000..bd10e81
--- /dev/null
@@ -0,0 +1,23 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-security:
+
+Security concerns
+^^^^^^^^^^^^^^^^^
+
+This library makes it possible to tap GET and POST variables. The
+safety of these values can never be ascertained. The exact risks
+depend on where this library is used. Care must be taken – once values
+are retrieved using the expressions library – to sanitize those values
+in an appropriate manner depending on how they are used (e.g. XSS, SQL
+injection, etc.). The functions that can be called on each expression
+provide some safety against this.
+
+When expressions are used inside an extension, it is also up to each
+developer to judge what additional security to implement.
diff --git a/Documentation/Developer/Variables/Index.rst b/Documentation/Developer/Variables/Index.rst
new file mode 100644 (file)
index 0000000..5fe5221
--- /dev/null
@@ -0,0 +1,54 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-variables:
+
+Internal and external variables
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The idea behind internal and external variables is to provide two
+different spaces where to store custom data, to be retrieved by the
+parser. What is available in these spaces depends on what you stored
+into them. This is really up to each extension that uses expressions.
+
+The concept is that "vars" is for values that can be considered as
+internal to the extension. For example, for a traditional FE plugin, you might
+want to load the piVars into the "vars" array, so that they can be
+used inside an expression. On the other hand, the "extra data" array
+might contain values that come from some other external source, for
+example some general TypoScript.
+
+It is up to each extension developer to decide whether to use those
+arrays or not, or also to differentiate between the two or just use a
+single one. It is really just a conceptual difference, so it must
+essentially make sense with regard to the extension itself.
+
+
+.. _developer-variables-example:
+
+Example
+"""""""
+
+.. code:: php
+
+       $data = array(
+               'foo' => 'bar'
+       );
+       \Cobweb\Expressions\ExpressionParser::setExtraData(
+               $data,
+               FALSE
+       );
+
+This will load the :code:`$data` array into the internal variables. Values
+from this array can then be retrieved with the following expression:
+
+.. code:: text
+
+       extra:foo
+
+which will return "bar".
diff --git a/Documentation/Developer/ViewHelper/Index.rst b/Documentation/Developer/ViewHelper/Index.rst
new file mode 100644 (file)
index 0000000..6c9291d
--- /dev/null
@@ -0,0 +1,46 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _developer-view-helper:
+
+Fluid View Helper
+^^^^^^^^^^^^^^^^^
+
+The extension comes with a view helper for Fluid. As curly braces
+(:code:`{` and :code:`}`) are used as markers in Fluid, they must be escaped so as not to
+break Fluid rendering.
+
+Declaration of the namespace:
+
+.. code:: text
+
+       {namespace expression = Cobweb\Expressions\ViewHelpers}
+
+Usage:
+
+.. code:: html
+
+       <expression:evaluate>Current page id is \{tsfe:id\}</expression:evaluate>
+
+Result:
+
+.. code:: text
+
+       Current page id is 1
+
+Usage (with inline notation):
+
+.. code:: text
+
+       {expression:evaluate(expression:'Current user is \{fe_user:username\}')}
+
+Result:
+
+.. code:: text
+
+       Current user is zaphod
diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt
new file mode 100644 (file)
index 0000000..a111144
--- /dev/null
@@ -0,0 +1,21 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. This is 'Includes.txt'. It is included at the very top of each and
+   every ReST source file in this documentation project (= manual).
+
+
+.. ==================================================
+.. DEFINE SOME TEXT ROLES
+.. --------------------------------------------------
+
+.. role::   typoscript(code)
+
+.. role::   ts(typoscript)
+   :class:  typoscript
+
+.. role::   php(code)
+
+.. highlight:: php
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
new file mode 100644 (file)
index 0000000..0ece2d9
--- /dev/null
@@ -0,0 +1,59 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: Includes.txt
+
+
+.. _start:
+
+=========================
+Generic expression parser
+=========================
+
+.. only:: html
+
+       :Language:
+                 en
+
+       :Version:
+                 |release|
+
+       :Description:
+                 A library for bringing into extensions something like TypoScript's getText function.
+
+       :Keywords:
+                 tesseract, expression, parser, gettext, typoscript
+
+       :Copyright:
+                 2007-2015
+
+       :Author:
+                 François Suter (Cobweb)
+
+       :Email:
+                 typo3@cobweb.ch
+
+       :License:
+                 This document is published under the Open Content License
+                 available from http://www.opencontent.org/opl.shtml
+
+       :Rendered:
+                 |today|
+
+
+The content of this document is related to TYPO3 CMS,
+a GNU/GPL CMS/Framework available from `www.typo3.org <http://www.typo3.org/>`_.
+
+
+.. toctree::
+   :maxdepth: 5
+   :titlesonly:
+   :glob:
+
+   Introduction/Index
+   Installation/Index
+   User/Index
+   Developer/Index
+   KnownProblems/Index
diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst
new file mode 100644 (file)
index 0000000..61281f9
--- /dev/null
@@ -0,0 +1,33 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _installation:
+
+Installation
+------------
+
+Just install the extension and start using it. As of version 2.0.0, TYPO3 CMS 6.2 or newer is required.
+
+
+.. _installation-update:
+
+Updating to version 2.0
+^^^^^^^^^^^^^^^^^^^^^^^
+
+With version 2.0, all PHP classes were changed to use namespaces.
+There is no backward compatibility layer. So if you used code like:
+
+.. code:: php
+
+       $foo = tx_expressions_parser::evaluateExpression('gp:bar');
+
+you must now use:
+
+.. code:: php
+
+       $foo = \Cobweb\Expressions\ExpressionParser::evaluateExpression('gp:bar');
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
new file mode 100644 (file)
index 0000000..1e0c5fc
--- /dev/null
@@ -0,0 +1,72 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _introduction:
+
+Introduction
+------------
+
+In TypoScript templates there exists a function called :ref:`getText <t3tsref:data-type-gettext>`,
+which makes it possible to retrieve values from a great number of
+sources (GET/POST, TSFE, rootline, etc.). This extension provides a
+library which aims to reproduce this capability, so that it can be
+used by developers in their own extension.
+
+This can be useful in cases where you have some kind of configuration
+but are not using TypoScript, for whatever reason.
+
+
+.. _expression:
+
+So what is an expression?
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Like for the TypoScript function, an expression – at a minimum – is
+comprised of a key, a colon (:) and a value. Example:
+
+.. code:: text
+
+       gp:no_cache
+
+The above syntax will instruct the parser to look for a GET/POST
+variable called "no\_cache". The key represents the "space" where to
+look for the value. With some special keys, the value takes a
+different meaning. This is documented below.
+
+The parser library can either parse a single expression or parse
+expressions inside strings, provided expressions are placed between
+curly braces. Example:
+
+.. code:: text
+
+       This is the value of no_cache: {gp:no_cache}
+
+
+.. _introduction-questions:
+
+Questions?
+^^^^^^^^^^
+
+If you have any questions about this extension, please ask them in the
+TYPO3 English mailing list (typo3.english), so that others can benefit
+from the answers.
+
+
+.. _introduction-happy-developer:
+
+Keeping the developer happy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you like this extension, use the social functions of the TER to
+make some buzz about it. Alternatively, if you want to give something
+back, you may consider my Amazon wish list:
+http://www.amazon.co.uk/registry/wishlist/G7DI2AN99Y4F
+
+You may also take a step back and reflect about the beauty of sharing.
+Think about how much you are benefiting and how much yourself is
+giving back to the community.
diff --git a/Documentation/KnownProblems/Index.rst b/Documentation/KnownProblems/Index.rst
new file mode 100644 (file)
index 0000000..5a29d8f
--- /dev/null
@@ -0,0 +1,17 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _problems:
+
+Known problems
+--------------
+
+None to date. Please report any problem to the TYPO3 mailing lists
+(typo3.english or typo3.dev as appropriate) or submit a bug report to
+the extension's bug tracker
+(http://forge.typo3.org/projects/extension-expressions/issues).
diff --git a/Documentation/Settings.yml b/Documentation/Settings.yml
new file mode 100644 (file)
index 0000000..c7680f8
--- /dev/null
@@ -0,0 +1,33 @@
+# This is the project specific Settings.yml file.
+# Place Sphinx specific build information here.
+# Settings given here will replace the settings of 'conf.py'.
+
+---
+conf.py:
+  copyright: 2007-2015
+  project: Context Manager
+  version: 2.0
+  release: 2.0.0
+  latex_documents:
+  - - Index
+    - context.tex
+    - Context Manager
+    - Francois Suter
+    - manual
+  latex_elements:
+    papersize: a4paper
+    pointsize: 10pt
+    preamble: \usepackage{typo3}
+  intersphinx_mapping:
+    t3tsref:
+    - http://docs.typo3.org/typo3cms/TyposcriptReference/
+    - null
+    context:
+    - http://docs.typo3.org/typo3cms/extensions/context/
+    - null
+  extensions:
+  - sphinx.ext.intersphinx
+  - t3sphinx.ext.t3extras
+  - t3sphinx.ext.t3tablerows
+  - t3sphinx.ext.targets
+...
diff --git a/Documentation/User/ExpressionKeys/Index.rst b/Documentation/User/ExpressionKeys/Index.rst
new file mode 100644 (file)
index 0000000..db88fa6
--- /dev/null
@@ -0,0 +1,265 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _user-keys:
+
+Expression keys reference
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Expressions can be used both in the the frontend and the backend, but
+some keys will obviously not be available in the backend as they rely
+on frontend object (for example, :code:`$TSFE`).
+
+It is possible to create processors for custom expression keys (see
+"Developer's Guide") and thus to extend the expression parser.
+
+- `config`_
+- `date`_
+- `extra`_
+- `env`_
+- `fe\_user`_
+- `gp`_
+- `page`_
+- `plugin`_
+- `session`_
+- `strtotime`_
+- `tsfe`_
+- `vars`_
+
+.. _user-keys-tsfe:
+
+tsfe
+""""
+
+Gets a value from the :code:`$TSFE` global variable.
+
+**Examples**
+
+Retrieve the uid of the current page:
+
+.. code:: text
+
+       tsfe:id
+
+Retrieve the username of the currently logged in user:
+
+.. code:: text
+
+       tsfe:fe_user|user|username
+
+
+.. _user-keys-page:
+
+page
+""""
+
+Gets a value related to the current page, as stored in :code:`$TSFE->page`.
+
+**Example**
+
+Retrieve the uid of the current page:
+
+.. code:: text
+
+       page:uid
+
+
+.. _user-keys-config:
+
+config
+""""""
+
+Gets a value from the "config" object, as stored in
+:code:`$TSFE->config['config']`.
+
+**Example**
+
+Retrieve the current language:
+
+.. code:: text
+
+       config:language
+
+
+.. _user-keys-feuser:
+
+fe\_user
+""""""""
+
+Gets a value for the current frontend user, as stored in
+:code:`$GLOBALS['TSFE']->fe_user->user`.
+
+**Example**
+
+Retrieve the current FE user's name:
+
+.. code:: text
+
+       fe\_user:name
+
+
+.. _user-keys-plugin:
+
+plugin
+""""""
+
+Get a TypoScript property for a plugin as stored in
+:code:`$GLOBALS['TSFE']->tmpl->setup['plugin.']`.
+
+.. note::
+
+   Remember that TS indices have an ending dot (.).
+
+**Example**
+
+Retrieve the TypoScript property :code:`plugin.tx_vgetagcloud_pi1.startPage.data`:
+
+.. code:: text
+
+       plugin:tx_vgetagcloud_pi1.|startPage.|data
+
+
+.. _user-keys-gp:
+
+gp
+""
+
+Gets a value from either the :code:`$_GET` or :code:`$_POST` superglobal arrays.
+This makes it possible to retrieve any GET or POST variable passed to the page.
+
+**Example**
+
+Retrieve the uid of a single news record:
+
+.. code:: text
+
+       gp:tx_ttnews|tt_news
+
+
+.. _user-keys-vars:
+
+vars
+""""
+
+Gets a value from :ref:`"internal" variables <developer-variables>` variables.
+This depends on what is loaded here by the extension that users the parser.
+This is meant to be equivalent to a traditional's plugin "piVars".
+
+**Example**
+
+Retrieve the "showUid" variable from the internal variables:
+
+.. code:: text
+
+       vars:showUid
+
+
+.. _user-keys-extra:
+
+extra
+"""""
+
+Same as above but for so-called :ref:`"external" variables <developer-variables>`.
+
+.. note::
+
+   This is done, for example, by the :ref:`context extension <context:start>`
+   to make context values accessible.
+
+**Example**
+
+Retrieve the value of "category" from the context:
+
+.. code:: text
+
+       extra:category
+
+
+.. _user-keys-date:
+
+date
+""""
+
+Gets values related to the current time, using formats from the PHP
+`date() <http://php.net/date>`_ function.
+
+**Example**
+
+Retrieve the current year (4 digits):
+
+.. code:: text
+
+       date:Y
+
+
+.. _user-keys-strtotime:
+
+strtotime
+"""""""""
+
+Gets a timestamp by interpreting a human-readable date, as per the
+capacities of PHP's function `strtotime() <http://php.net/strtotime>`_.
+
+**Examples**
+
+Retrieve the timestamp corresponding to Jan 1, 2009:
+
+.. code:: text
+
+       strtotime:2009-01-01
+
+Retrieve the timestamp corresponding to tomorrow, same time:
+
+.. code:: text
+
+       strtotime:tomorrow
+
+
+.. _user-keys-session:
+
+session
+"""""""
+
+Gets values from some structure stored in the temporary session (i.e.
+"ses" and **not** "user").
+
+The first item (after the "session:" key) has a special meaning. It
+corresponds to the key that was used to store into the session. The
+following indices are used normally.
+
+**Example**
+
+Retrieve index "bob" of array dummy stored into the session:
+
+.. code:: text
+
+       session:dummy|bob
+
+
+.. _user-keys-env:
+
+env
+"""
+
+Get values from the environment variables, via the use of
+:code:`\TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv()`.
+Please refer to that method for available values.
+
+.. note::
+
+   :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::getIndpEnv()` expects values to be uppercase.
+   The expressions parser takes care of uppercasing any incoming value, so
+   there's no need to worry about that.
+
+**Example**
+
+Retrieve the host name:
+
+.. code:: text
+
+       env:http_host
diff --git a/Documentation/User/ExpressionSyntax/Index.rst b/Documentation/User/ExpressionSyntax/Index.rst
new file mode 100644 (file)
index 0000000..4ca0491
--- /dev/null
@@ -0,0 +1,138 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _user-syntax:
+
+Expression syntax
+^^^^^^^^^^^^^^^^^
+
+The general syntax of an expression – at its simplest – is the
+following:
+
+.. code:: text
+
+       key:value1|value2|value3...
+
+The key defines the "domain" where to look for the value or sequence
+of values. For example, the key "page" means that values should be
+looked for in the current page record.
+
+The values can be multiple, separated by pipe symbols (\|). Each value
+normally represents a "dimension" of the "domain" where the value is
+being looked up. This can be either a dimension of an array or a
+member variable of an object. This is totally interchangeable, i.e.
+the expression parser will traverse the structure transparently
+whether any given "dimension" is an actual array dimension or some
+object property. Example:
+
+.. code:: text
+
+       tsfe:fe_user|user|uid
+
+"fe\_user" is an object and "user" is one of its member variables. But
+"user" is an array and "uid" is one its keys. As you can see in terms
+of expression syntax, this is totally transparent.
+
+If no key is found inside the string to parse, it is returned as is.
+
+:ref:`Available keys are described below <user-keys>`.
+
+
+.. _user-syntax-extended:
+
+Extended syntax
+"""""""""""""""
+
+Additions to the base syntax make it possible to call functions for
+post-processing the result of the expression. The syntax becomes:
+
+.. code:: text
+
+       key:value1|value2|value3...->function:arg1,arg2,...
+
+The function call is indicated by the "->" symbol. Then comes the
+function key, which the parser will match to an actual function or
+method call. The function will receive the value of the expression as
+an argument. It may also require additional arguments, which are
+defined after a colon (:) and separated by commas (,). Example:
+
+.. code:: text
+
+   gp:tx_myext_pi1|foo->fullQuoteStr:pages
+
+In this example, we retrieve the value of the GET/POST variable
+:code:`tx_myext_pi1[foo]` and put it through
+:code:`\TYPO3\CMS\Core\Database\DatabaseConnection::fullQuoteStr()`
+with the "pages" table name as a second argument (the first one being the value itself).
+
+Functions can be chained:
+
+.. code:: text
+
+       key:value1|value2|value3...->function1:arg1,arg2,...->function2:arg1,arg2,...->...
+
+The call order is from left to right.
+
+:ref:`Available functions are described below <user-functions>`.
+
+
+.. _user-syntax-subexpressions:
+
+Subexpressions
+""""""""""""""
+
+An expression could itself contain expressions. These are called
+"subexpressions". The syntax might look something like:
+
+.. code:: text
+
+       tsfe:fe_user|user|{gp:fe_field}
+
+In this case, the expression would first be parsed for subexpressions.
+Assuming the GET/POST var "fe\_field" contained "name" as a value, the
+expression would become
+
+.. code:: text
+
+       tsfe:fe_user|user|name
+
+which would then be parsed normally.
+
+Every feature of expressions can be used inside subexpressions, except
+further subexpressions.
+
+
+.. _user-syntax-alternative:
+
+Alternative expressions
+"""""""""""""""""""""""
+
+An expression can be made of several expressions, separated by a
+double slash (//):
+
+.. code:: text
+
+       key1:value1|value2|... // key2:value1|value2|... // ...
+
+These represent alternatives. Expressions are evaluated from left to
+right and the first one to return a value will end the process. Thus
+the expression with "key2" (in the above example) will be evaluated
+only if the first one didn't return anything.
+
+This can be used in particular to define default values, by using an
+alternate that is **not** an expression. Example:
+
+.. code:: text
+
+       gp:year // 2010
+
+In this case, the expression parser will look for a GET/POST variable
+called "year". If it does not exist, it will evaluate the next
+alternative. Since it is a simple value (it's not an expression,
+because it has not key – as marked by colon), it will be taken as is
+and the complete expression will evaluate to "2010".
diff --git a/Documentation/User/FunctionKeys/Index.rst b/Documentation/User/FunctionKeys/Index.rst
new file mode 100644 (file)
index 0000000..99e21d9
--- /dev/null
@@ -0,0 +1,192 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../../Includes.txt
+
+
+.. _user-functions:
+
+Function keys reference
+^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to create processors for custom function keys (see
+"Developer's Guide") and thus be able to call pretty much any function
+inside an expression.
+
+- `boolean`_
+- `floatval`_
+- `fullQuoteStr`_
+- `hsc`_
+- `intval`_
+- `quoteStr`_
+- `removeXSS`_
+- `strip\_tags`_
+- `strftime`_
+
+
+.. _user-functions-fullquotestr:
+
+fullQuoteStr
+""""""""""""
+
+Calls :code:`\TYPO3\CMS\Core\Database\DatabaseConnection::fullQuoteStr()`.
+
+Requires an additional argument, which corresponds to a table name
+(see the method's comments if in doubt).
+
+Will not be available if the :code:`$TYPO3_DB` global variable is not set.
+
+**Example**
+
+Call :code:`\TYPO3\CMS\Core\Database\DatabaseConnection::fullQuoteStr()` on the value,
+with "pages" as a second argument:
+
+.. code:: text
+
+       gp:tx_myext_pi1|foo->fullQuoteStr:pages
+
+
+.. _user-functions-quotestr:
+
+quoteStr
+""""""""
+
+Calls :code:`\TYPO3\CMS\Core\Database\DatabaseConnection::quoteStr()`.
+
+Requires an additional argument, which corresponds to a table name
+(see the method's comments if in doubt).
+
+Will not be available if the :code:`$TYPO3_DB` global variable is not set.
+
+**Example**
+
+Call :code:`\TYPO3\CMS\Core\Database\DatabaseConnection::quoteStr()` on the value,
+with "pages" as a second argument:
+
+.. code:: text
+
+       gp:tx_myext_pi1|foo->quoteStr:pages
+
+
+.. _user-functions-striptags:
+
+strip\_tags
+"""""""""""
+
+Calls the PHP function :code:`strip_tags()`. The additional argument
+is optional and corresponds to the list of tags to preserve
+(refer to the `PHP manual for strip_tags() <http://php.net/strip_tags>`_ for more details).
+
+**Example**
+
+Call the PHP function :code:`strip_tags()` on the value
+but preserve :code:`<p>` tags:
+
+.. code:: text
+
+       gp:tx_myext_pi1|foo->strip_tags:<p>
+
+
+.. _user-functions-removexss:
+
+removeXSS
+"""""""""
+
+Calls :code:`\TYPO3\CMS\Core\Utility\GeneralUtility::removeXSS`.
+
+**Example**
+
+.. code:: text
+
+       gp:tx\_myext\_pi1\|foo->removeXSS
+
+
+.. _user-functions-intval:
+
+intval
+""""""
+
+Calls the PHP function :code:`intval()`. The additional argument is
+optional and corresponds to the base to use for conversion
+(refer to the `PHP manual for intval() <http://php.net/intval>`_ for more details).
+
+**Example**
+
+Call the PHP function :code:`intval()` using base 8:
+
+.. code:: text
+
+       gp:tx\_myext\_pi1\|foo->intval:8
+
+
+.. _user-functions-floatval:
+
+floatval
+""""""""
+
+Calls the PHP function :code:`floatval()`
+(refer to the `PHP manual <http://php.net/floatval>`_ for more details).
+
+**Example**
+
+.. code:: text
+
+       gp:tx_myext_pi1|foo->floatval
+
+
+.. _user-functions-boolean:
+
+boolean
+"""""""
+
+This is an internal function. It's actually the opposite of the PHP
+function :code:`empty()`. This means that any value of 0 or "0", or
+an empty string will return :code:`FALSE`. Any other value will return :code:`TRUE`.
+
+**Example**
+
+Return FALSE if value is empty, TRUE otherwise:
+
+.. code:: text
+
+       gp:tx_myext_pi1|foo->boolean
+
+
+.. _user-functions-hsc:
+
+hsc
+"""
+
+Calls the PHP function :code:`htmlspecialchars()`. The additional
+arguments are all optional and correspond respectively to the
+behavior to adopt regarding single and double quotes, the character
+set to use in the conversion and what to do about existing HTML
+entities (refer to the `PHP manual for htmlspecialchars() <http://php.net/htmlspecialchars>`_ for more details).
+
+**Example**
+
+Call the PHP function htmlspecialchars(), without any additional arguments:
+
+.. code:: text
+
+       gp:tx_myext_pi1|foo->hsc
+
+
+.. _user-functions-strftime:
+
+strftime
+""""""""
+
+Calls the PHP function :code:`strftime()` . It expects a Unix
+timestamp as a value and takes a date format as an additional argument
+(refer to the `PHP manual for strftime() <http://php.net/strftime>`_ for more details).
+
+**Example**
+
+Call the PHP function strftime() to format the timestamp received:
+
+.. code:: text
+
+       gp:date->strftime:%d.%m.%Y
diff --git a/Documentation/User/Index.rst b/Documentation/User/Index.rst
new file mode 100644 (file)
index 0000000..9b1de27
--- /dev/null
@@ -0,0 +1,22 @@
+.. ==================================================
+.. FOR YOUR INFORMATION
+.. --------------------------------------------------
+.. -*- coding: utf-8 -*- with BOM.
+
+.. include:: ../Includes.txt
+
+
+.. _user:
+
+User's Guide
+------------
+
+
+.. toctree::
+   :maxdepth: 5
+   :titlesonly:
+   :glob:
+
+   ExpressionSyntax/Index
+   ExpressionKeys/Index
+   FunctionKeys/Index
diff --git a/doc/manual.pdf b/doc/manual.pdf
deleted file mode 100644 (file)
index a125c1b..0000000
Binary files a/doc/manual.pdf and /dev/null differ
diff --git a/doc/manual.sxw b/doc/manual.sxw
deleted file mode 100644 (file)
index dff6a13..0000000
Binary files a/doc/manual.sxw and /dev/null differ