Release version 0.7

README.md

@@ -1,3 +1,115 @@
-# Debuggy\Gauger
+Gauger
+======
 
-Master: [![Build Status](https://travis-ci.org/dnsl48/Gauger.svg?branch=master)](https://travis-ci.org/dnsl48/Gauger) [![Coverage Status](https://img.shields.io/coveralls/dnsl48/Gauger.svg)](https://coveralls.io/r/dnsl48/Gauger?branch=master)
+## [![Build Status](https://travis-ci.org/dnsl48/Gauger.svg?branch=master)](https://travis-ci.org/dnsl48/Gauger)  [![Coverage Status](https://img.shields.io/coveralls/dnsl48/Gauger.svg)](https://coveralls.io/r/dnsl48/Gauger?branch=master)
+
+Tests were passing PHP 5.3, 5.4, 5.5, 5.6 and hhvm.
+
+What is Gauger?
+---------------
+
+Gauger is an extensible and comprehensive tool for measuring PHP scripts and applications. It is written rather for debugging, however it could be used for testing purposes as well.
+
+
+Installation
+------------
+
+There are two ways to install Gauger into your project: `composer` and `manual`.
+
+### Composer
+
+To install the library with composer you should put the next code into your project's composer.json:
+
+```json
+{
+	"require-dev": {
+		"debuggy/gauger": "dev-master"
+	}
+}
+```
+To see how to use composer in general, you can look at the [official documentation](https://getcomposer.org/).
+
+
+### Manual installation
+
+You can clone the repository of the library from github. Only what you need is autoloader which is compatible with `PSR-4` standard.
+The library's root namespace is `Debuggy` that is in the folder `src`.
+
+
+Documentation
+-------------
+
+The project's documentation is comments in the source code. Please, feel free to read them.
+
+However, here are some basic concepts:
+
+ * `Mark`: [Business Object](http://en.wikipedia.org/wiki/Business_object) with gathered info
+ * `Gauger`: Makes marks and keeps them
+ * `Formatter`: Transforms marks into reports (text, html, xml, php-array and others)
+ * `Filter`: Gaugers use filters to decide whether marks should be kept
+
+
+Examples
+--------
+
+Though you can make Gauger's derived class that will take any measures you need, for now there are
+two base gaugers you can use.
+
+ * `StretchAccumulator`: Accumulates all marks during its work and produces two sets of marks: Sequential and Summary
+ * `StretchCalculator`: Does not keep all regular marks during the work. Eventually produces only Summary set of marks
+
+Lets see the example with `StretchAccumulator`:
+
+```php
+<?php
+include __DIR__.'/vendor/autoload.php';
+
+use Debuggy\Gauger\StretchTimeAccumulator;
+
+$gauger = new StretchTimeAccumulator ('md5 vs sha1');
+
+for ($i = 0; $i < 2; ++$i) {
+	$gauger->mark ('md5');
+	md5 ('text');
+	$gauger->mark ('md5');
+
+	$gauger->mark ('sha1');
+	sha1 ('text');
+	$gauger->mark ('sha1');
+}
+
+echo $gauger;
+```
+
+The result will be like that:
+
+```
+********************************* md5 vs sha1 **********************************
+*********************************** Regular ************************************
+* 1. md5 ............................................................ 0.000020 *
+* 2. sha1 ........................................................... 0.000013 *
+* 3. md5 ............................................................ 0.000009 *
+* 4. sha1 ........................................................... 0.000009 *
+*********************************** Summary ************************************
+* md5 (2) ........................................................... 0.000029 *
+* sha1 (2) .......................................................... 0.000022 *
+********************************************************************************
+```
+
+Here we can see, that md5 was slower in the Summary, however in the second loop it took the same time as sha1.
+Also, in the Summary we can see that each marker was harvested twice (embraced figure).
+
+
+Anything else?
+---------------
+
+ * Easy way to gauge anything with correct Exceptions handle: `Gauger::gauge ($closure, $constructData, $marker);`
+ * Most critical parts of code can be gauged **without any overhead** with `microtime` and `Gauger::stamp`
+ * Any Run-time info can be kept. Pass it as the second attribute of `Gauger::mark` (or third of `Gauger::stamp`)
+ * Static access to any gauger by its name in any place of an Application (`Gauger::getStatic`)
+ * Filter by duration so that the report will contain only slowest parts of an Application (`Filter\Duration`)
+
+
+License
+-------
+`Apache License, Version 2.0`

src/Debuggy/Gauger.php

@@ -15,21 +15,21 @@
 
 /**
  * Base Gauger.
- * Although it has some basic methods and constructor, its other methods
- * have to be implemented in derived classes, that are to implement some
+ * Although it has some basic methods and constructor, its abstract methods
+ * have to be implemented in derived classes. They should implement some
  * specific gauging logic.
  */
 abstract class Gauger {
 	/**
-	 * A name of the default gauger
+	 * Default name for gaugers
 	 */
 	const DEFAULT_NAME = 'Unnamed Gauger';
 
 
 	/**
-	 * Makes a gauger with identifier
+	 * Constructs instance of gauger with name
 	 *
-	 * @param string $name Identifier
+	 * @param string $name Name
 	 */
 	public function __construct ($name = null) {
 		if (!isset ($name))
@@ -40,32 +40,42 @@ public function __construct ($name = null) {
 
 
 	/**
-	 * Makes new stamp with marker
+	 * Makes new mark with marker
 	 *
-	 * @param string $marker Marker that denotes the stamp
-	 * @param array $details Note for that stamp (optional)
+	 * @param string $marker Marker name
+	 * @param array $details Extra info about marker (optional)
 	 *
 	 * @return void
 	 */
 	abstract public function mark ($marker, $details = array ());
 
 
 	/**
-	 * Registers an existent stamp with marker
+	 * Stamps an existent gauge with marker
 	 *
-	 * @param float $stamp Microtime stamp
-	 * @param string $marker Marker that denotes the stamp
-	 * @param array $details Note for that stamp (optional)
+	 * @param float $stamp Gauge to stamp
+	 * @param string $marker Marker name
+	 * @param array $details Extra info about marker (optional)
 	 *
 	 * @return void
 	 */
 	abstract public function stamp ($stamp, $marker, $details = array ());
 
 
+	/**
+	 * Makes new gauge and returns it
+	 *
+	 * @param array $details Marker details
+	 *
+	 * @return mixed
+	 */
+	abstract protected function getGauge (array $details);
+
+
 	/**
 	 * Returns list of marks that represents gauger info at the moment of
-	 * this method invocation. If any filters passed, it'll be applied to
-	 * result set only, so that they shouldn't affect any durations.
+	 * the method invocation. If any filters passed, they will be applied to
+	 * result.
 	 *
 	 * @param array $sequentialFilters List of SequentialFilters
 	 * @param array $summaryFilters List of SummaryFilters
@@ -76,16 +86,15 @@ abstract public function getMarks (array $sequentialFilters = array (), array $s
 
 
 	/**
-	 * Resets all internal storages of the instance so it is going to clear
-	 * all collected data.
+	 * Reset all internal storages of the gauger
 	 *
 	 * @return void
 	 */
 	abstract public function reset ();
 
 
 	/**
-	 * Returns identifier of a gauger
+	 * Returns name of the gauger
 	 *
 	 * @return string
 	 */
@@ -95,14 +104,14 @@ public function getName () {
 
 
 	/**
-	 * Gauges the subject's evaluation speed.
-	 * If there is exception, it is going to be in details of fixed mark and thrown
-	 * forth.
+	 * Gauges the subject's evaluation.
+	 * If there is any exception, it will be kept in details of a fixed mark.
+	 * After it will be thrown forth.
 	 *
 	 * @param Closure $subject Subject to gauge
-	 * @param array $arguments Arguments for invocation
+	 * @param array $arguments Arguments for subject's invocation
 	 * @param string $marker Marker that denotes the subject
-	 * @param array $details Details for that subject (optional)
+	 * @param array $details Extra information about marker (optional)
 	 *
 	 * @return mixed Result of the subject's invocation
 	 *
@@ -150,8 +159,7 @@ public function gauge (Closure $subject, $arguments = array (), $marker, $detail
 
 
 	/**
-	 * Set sequence filter.
-	 * It will be working during the gauger's gathering of marks.
+	 * Set filter that will be working during the gauger's marks gathering.
 	 *
 	 * @param SequentialFilter $filter Filter instance
 	 *
@@ -173,7 +181,7 @@ public function getFilters () {
 
 
 	/**
-	 * Reset filters setup so that no more filters will be stored in the instance of gauger
+	 * Reset all filters
 	 *
 	 * @return void
 	 */
@@ -233,8 +241,8 @@ abstract protected function getGaugeMarkers ($originalMarker);
 
 
 	/**
-	 * Returns a gauger by name. If it hasn't been created yet, it's going to be so.
-	 * Furthermore, it's going to be stored in tha static scope of the class.
+	 * Returns a gauger by name. If it hasn't been created yet, it's going to be.
+	 * Furthermore, it's going to be kept in tha static scope of the class.
 	 * The next invocations of static::getStatic will always return the same object
 	 * that has been created in the first time.
 	 *

src/Debuggy/Gauger/Filter/Duration.php → src/Debuggy/Gauger/Filter/Between.php

@@ -10,11 +10,12 @@
 
 
 /**
- * Filter for marks by their duration
+ * Implements filtering logic by ranges of gauges
  */
-class Duration implements Sequential, Summary {
+class Between implements Sequential, Summary {
 	/**
-	 * Setup minimum and maximum duration for a mark to pass the checking
+	 * Setup minimum and maximum points. The range between them
+	 * will be pass the filter.
 	 *
 	 * @param int $min Minimum value
 	 * @param int $max Maximum value
@@ -41,12 +42,14 @@ public function checkSummary (SummaryMark $mark) {
 
 
 	/**
-	 * {@inheritdoc}
+	 * Check that mark's gauge is greater than min and lesser than max
+	 *
+	 * @param Mark $mark Mark for checking
 	 */
 	public function checkMark (Mark $mark) {
 		return
-			(!isset ($this->_min) || $mark->duration >= $this->_min)
+			(!isset ($this->_min) || $mark->gauge >= $this->_min)
 		&&
-			(!isset ($this->_max) || $mark->duration <= $this->_max);
+			(!isset ($this->_max) || $mark->gauge <= $this->_max);
 	}
 }

src/Debuggy/Gauger/Filter/Sequential.php

@@ -13,7 +13,7 @@
 interface Sequential {
 	/**
 	 * Check a sequential mark and return result whether it should be
-	 * stored for result set of marks
+	 * kept for result
 	 *
 	 * @param SequentialMark $mark Mark for checking
 	 *

src/Debuggy/Gauger/Filter/SequentialClosure.php

@@ -10,13 +10,13 @@
 
 
 /**
- * Encapsulates closure that will be invoked each time for checking a mark
+ * Encapsulates closure that will be invoked for checking marks
  */
 class SequentialClosure implements Sequential {
 	/**
-	 * Takes closure that should be invoked for each mark that should be checked
+	 * Takes closure that should be invoked for checking marks
 	 *
-	 * @param Closure $closure Closure that will be invoked for each mark
+	 * @param Closure $closure Closure that will check the marks
 	 */
 	public function __construct (Closure $closure) {
 		$this->_closure = $closure;
@@ -31,7 +31,7 @@ public function checkSequential (SequentialMark $mark) {
 	}
 
 	/**
-	 * Closure for check marks
+	 * Closure for checking marks
 	 *
 	 * @var Closure
 	 */

src/Debuggy/Gauger/Filter/Summary.php

@@ -13,7 +13,7 @@
 interface Summary {
 	/**
 	 * Check a summary mark and return result whether it should be
-	 * stored for result set of marks
+	 * kept for result
 	 *
 	 * @param SummaryMark $mark Mark for checking
 	 *

src/Debuggy/Gauger/Filter/SummaryClosure.php

@@ -10,13 +10,13 @@
 
 
 /**
- * Encapsulates closure that will be invoked each time for checking a mark
+ * Encapsulates closure that will be invoked for checking marks
  */
 class SummaryClosure implements Summary {
 	/**
-	 * Takes closure that should be invoked for each mark that should be checked
+	 * Takes closure that should be invoked for checking marks
 	 *
-	 * @param Closure $closure Closure that will be invoked for each mark
+	 * @param Closure $closure Closure that will check the marks
 	 */
 	public function __construct (Closure $closure) {
 		$this->_closure = $closure;
@@ -31,7 +31,7 @@ public function checkSummary (SummaryMark $mark) {
 	}
 
 	/**
-	 * Closure for check marks
+	 * Closure for checking marks
 	 *
 	 * @var Closure
 	 */