Merge pull request #22 from jecisc/20-documentation-v110

Add documentation for v1.1.0

README.md

@@ -5,6 +5,7 @@
 A really small logger for Pharo applications.
 
   - [Installation](#installation)
+  - [Quick start](#quick-start)
   - [Documentation](#documentation)
   - [Version management](#version-management)
   - [Smalltalk versions compatibility](#smalltalk-versions-compatibility)
@@ -31,6 +32,37 @@ spec
 
 Note you can replace the #master by another branch such as #development or a tag such as #v1.0.0, #v1.? or #v1.2.? .
 
+## Quick start
+
+To create a file logger using a file `Progress.log` and records all messages as soon as the project is loaded in a a Pharo image, in the initialize method (class side) of a project put the following:
+
+```Smalltalk
+TinyLogger default 
+    addFileLoggerNamed: 'Progress.log'.
+```
+
+To create a file logger that is reset each time you run an application. Put the following in the method that is run:
+
+```Smalltalk
+TinyLogger default 
+    ensureFileLoggerNamed: 'Progress.log'; "Add the file logger only if not already"
+    clearLog "This will delete the previous 'Progress.log' file".
+```
+
+Then write a message to the log using `record`:
+
+```Smalltalk
+'Uh oh. Something happened.' record
+```
+
+Or write a message to the log for the execution of an action using `execute:recordedAs:`:
+
+```Smalltalk
+self execute: [ "Some code doing something" ] recordedAs: 'Launching bananas.'
+```
+
+Now, if you want to know more about the project, let's proceed on a more detailed documentation.
+
 ## Documentation
 
 Documentation is split into separate links as follows:
@@ -51,9 +83,9 @@ Thus, it should be safe to depend on a fixed major version and moving minor vers
 
 ## Smalltalk versions compatibility
 
-| MDL version 	| Compatible Pharo versions 	|
+| Version 	| Compatible Pharo versions 	|
 |-------------	|---------------------------	|
-| 1.x.x       	| Pharo 61, 70        				|
+| 1.x.x       	| Pharo 61, 70, 80		|
 
 ## Contact
 

documentation/DevelopmentGuide.md

@@ -45,23 +45,23 @@ Generates the accessors for the `url` variable and you can add a constructor:
 
 ```Smalltalk
 TinyHTTPLogger class>>url: aString
-  ^ self new
-      url: aString;
-      yourself
+	^ self new
+		url: aString;
+		yourself
 ```
 
 Since `TinyLogger` groups its loggers by kinds, you need to define a `kind` method on the class side.
 
 ```Smalltalk
  TinyHTTPLogger class>>kind
-  ^ 'HTTP'
+	^ 'HTTP'
 ```
 
-Next step is to define the `record:` method to actually write the log. The superclass manages the preamble and formating directly via the method `record:on:` that needs to be called in your `record:` method. 
+Next step is to define the `record:` method to actually write the log. The superclass manages the preamble and formatting directly via the method `record:on:` that needs to be called in your `record:` method. 
 
 ```Smalltalk
 TinyHTTPLogger>>record: aString
-   ZnEasy post: self url data: (String streamContents: [ :s | self record: aString on: s ])
+	ZnEasy post: self url data: (String streamContents: [ :s | self record: aString on: s ])
 ```
 
 At this point, our new logger is usable. You can add a new instance to your `TinyLogger` this way:
@@ -76,7 +76,7 @@ The first one is to create and add a new HTTP logger:
 
 ```Smalltalk
 TinyLogger>>addHTTPLogger: aString
-  self addLogger: (TinyHTTPLogger url: aString)
+	self addLogger: (TinyHTTPLogger url: aString)
 ```
 
 The logger can now be used like this:
@@ -89,20 +89,33 @@ Another method to add as extension is a method to get all the HTTP loggers:
 
 ```Smalltalk
 TinyLogger>>httpLoggers
-  ^ self loggersMap at: TinyHTTPLogger kind ifAbsentPut: [ OrderedCollection new ]
+	^ self loggersMap at: TinyHTTPLogger kind ifAbsentPut: [ OrderedCollection new ]
 ```
 
-And the last method will be used to remove all HTTP loggers of the logger:
+Now that we have `httpLoggers`, we can easily add an `ensureHTTPLogger:` method matching `addHTTPLogger:`:
 
 ```Smalltalk
- TinyLogger>>removeHTTPLoggers
-	self httpLoggers removeAll
+TinyLogger>>ensureHTTPLogger: aString
+	self httpLoggers
+		detect: [ :e | e url = aString ]
+		ifNone: [ self addHTTPLogger: aString ]
 ```
 
-At this point you have one new logger kind available!
-
-
+And the last method to add as extension will be used to remove all HTTP loggers of the logger:
 
+```Smalltalk
+ TinyLogger>>removeHTTPLoggers
+	self httpLoggers removeAll
+```
 
+One last method to implement is `clearLogger` to clean the previous logs if the user want it:
 
+```Smalltalk
+TinyHTTPLogger>>record: aString
+	ZnClient new
+		beOneShot;
+		url: self url;
+		delete
+```
 
+At this point you have one new logger kind available!

documentation/UserGuide.md

@@ -8,14 +8,16 @@ For specific cases, a specialized logger can be used.
 
 - [User documentation of TinyLogger](#user-documentation-of-tinylogger)
   * [Configure your logger](#configure-your-logger)
-    + [Add sub-loggers to your `TinyLogger`](#add-sub-loggers-to-your--tinylogger-)
+    + [Add sub-loggers to your `TinyLogger`](#add-sub-loggers-to-your-tinylogger-)
     + [Remove sub-loggers](#remove-sub-loggers)
     + [List the sub-loggers](#list-the-sub-loggers)
     + [Configure the timestamp format](#configure-the-timestamp-format)
   * [Record with your logger](#record-with-your-logger)
     + [Record a single line log](#record-a-single-line-log)
     + [Recording the execution of a task](#recording-the-execution-of-a-task)
   * [Use another logger than the global logger](#use-another-logger-than-the-global-logger)
+  * [Clear your logger](#clear-your-logger)
+
 
 ## Configure your logger
 
@@ -50,9 +52,22 @@ TinyLogger default
 	addFileLoggerNamed: '../logs/MyOtherLog.log'.
 ```
 
+Additionaly to those methods, `TinyLogger` also propose ways to add loggers only if they have no equivalent already registered.
+
+To archieve this result, use the equivalent of the methods previously explained, replacing `add` by `ensure`:
+```Smalltalk
+TinyLogger default
+	ensureStdoutLogger;
+	ensureTranscriptLogger;
+	ensureFileLogger;
+	ensureFileLoggerNamed: '../logs/MyOtherLog.log'.
+```
+
+With those methods, Transcript and Stdout loggers will be limited to one, and file loggers will be limited to one by file name.
+
 ### Remove sub-loggers
 
-If at some point you wants to remove one or multiple loggers, `TinyLogger` has some API elements to do that. 
+If at some point you want to remove one or multiple loggers, `TinyLogger` has an API for that. 
 
 The first way to remove loggers is with the method `removeAllLoggers`, which removes all the loggers of each kind.
 
@@ -212,3 +227,15 @@ TinyCurrentLogger value: customLogger during: [
 	TinyCurrentLogger value record: 'Test2'
 ]
 ```
+
+## Clear your logger
+
+Each logger understands the method `#clearLog`. This method will have as effect to clear the output of the loggers. The actual effect is different depending on the kind of logger:
+- `TinyLogger` will send the message to all its sub loggers
+- `Transcript` logger will clear the Transcript of Pharo
+- `Stdout` logger will do nothing because it is not possible to clean a stdout
+- `File` logger will erase the file used to log
+
+```Smalltalk
+TinyLogger default clearLogger
+```

src/TinyLogger-Tests/TinyAbstractLoggerTest.class.st

@@ -32,7 +32,7 @@ TinyAbstractLoggerTest >> skipInPharo6 [
 ]
 
 { #category : #test }
-TinyAbstractLoggerTest >> testClearLogger [
+TinyAbstractLoggerTest >> testClearLog [
 	self subclassResponsibility
 ]
 

src/TinyLogger-Tests/TinyFileLoggerTest.class.st

@@ -32,13 +32,13 @@ TinyFileLoggerTest >> testCanHaveDefaultFile [
 ]
 
 { #category : #test }
-TinyFileLoggerTest >> testClearLogger [
+TinyFileLoggerTest >> testClearLog [
 	log := (self fileNameNumber: 1) asFileReference.
 	logger := self actualClass for: parentLogger named: log basename.
 	logger record: 'this is a test'.
 
 	self assert: log exists.
-	logger clearLogger.
+	logger clearLog.
 	self deny: log exists
 ]
 

src/TinyLogger-Tests/TinyLoggerTest.class.st

@@ -77,7 +77,7 @@ TinyLoggerTest >> testAddTranscriptLogger [
 ]
 
 { #category : #test }
-TinyLoggerTest >> testClearLogger [
+TinyLoggerTest >> testClearLog [
 	logger
 		addTranscriptLogger;
 		addFileLoggerNamed: 'testFileForTinyLogger.log';
@@ -86,7 +86,7 @@ TinyLoggerTest >> testClearLogger [
 	logger record: 'Test'.
 	self assert: (logger fileLoggers allSatisfy: [ :fileLogger | fileLogger fileReference exists ]).
 
-	logger clearLogger.
+	logger clearLog.
 	self assert: (logger fileLoggers noneSatisfy: [ :fileLogger | fileLogger fileReference exists ])
 ]
 

src/TinyLogger-Tests/TinyStdoutLoggerTest.class.st

@@ -13,8 +13,8 @@ TinyStdoutLoggerTest >> actualClass [
 ]
 
 { #category : #test }
-TinyStdoutLoggerTest >> testClearLogger [
-	self shouldnt: [ logger clearLogger ] raise: Error
+TinyStdoutLoggerTest >> testClearLog [
+	self shouldnt: [ logger clearLog ] raise: Error
 ]
 
 { #category : #test }

src/TinyLogger/TinyAbstractLogger.class.st

@@ -13,8 +13,9 @@ Users should configure a `TinyLogger` with the concrete loggers they want and u
 Public API and Key Messages
 --------------------
 
-- #record: 	Takes a string and record it.
-- #<< 			Alias of #record:
+- #record: 		Takes a string and record it.
+- #<< 				Alias of #record:.
+- #clearLog 		Clear the output of the logger. Will have different effect depending on the logger.
 
 "
 Class {
@@ -34,7 +35,7 @@ TinyAbstractLogger >> << aString [
 ]
 
 { #category : #logging }
-TinyAbstractLogger >> clearLogger [
+TinyAbstractLogger >> clearLog [
 	"Whe called, this method should clear the previous logs"
 
 	self subclassResponsibility

src/TinyLogger/TinyFileLogger.class.st

@@ -56,7 +56,7 @@ TinyFileLogger class >> named: aString [
 ]
 
 { #category : #logging }
-TinyFileLogger >> clearLogger [
+TinyFileLogger >> clearLog [
 	self fileReference ensureDelete
 ]
 

src/TinyLogger/TinyLogger.class.st

@@ -12,12 +12,14 @@ The user can configure the timestamp formating via the #timestampFormatBlock par
 Public API and Key Messages
 --------------------
 
-- #record: 						Log the parameter we the sub loggers.
-- #execute:recordedAs: 		Execute a block and log the task when it beging and ends. This will increase the identation of the logging.
+- #record: 						Log the parameter of the sub loggers
+- #clearLog 						Clear the output of the sub loggers
+- #execute:recordedAs: 		Execute a block and log the task when it beging and ends. This will increase the identation of the logging
 - #addStdoutLogger 			Add a logger on Stdout
 - #addTrascriptLogger 		Add a logger on the Transcript
 - #addFileLogger 				Add a logger that will log in a file named `TinyLogger.log`
 - #addFileLoggerNamed: 		Add a logger on a file whose name is passed as parameter
+- #ensure: 						Variant of all previous #addX message. This one will add the new logger only if there is not equivalent logger already present
 - #timestampFormatBlock: 	Give as parameter a block taking a stream as parameter and writing the timestamp you want
 
 Examples
@@ -127,8 +129,8 @@ TinyLogger >> addTranscriptLogger [
 ]
 
 { #category : #logging }
-TinyLogger >> clearLogger [
-	self loggers do: #clearLogger
+TinyLogger >> clearLog [
+	self loggers do: #clearLog
 ]
 
 { #category : #nesting }

src/TinyLogger/TinyStdoutLogger.class.st

@@ -26,7 +26,7 @@ TinyStdoutLogger class >> kind [
 ]
 
 { #category : #logging }
-TinyStdoutLogger >> clearLogger [
+TinyStdoutLogger >> clearLog [
 	"We do nothing here since we cannot clear stdout"
 
 

src/TinyLogger/TinyTranscriptLogger.class.st

@@ -23,7 +23,7 @@ TinyTranscriptLogger class >> kind [
 ]
 
 { #category : #logging }
-TinyTranscriptLogger >> clearLogger [
+TinyTranscriptLogger >> clearLog [
 	Transcript clear
 ]