[squeak-dev] Squeak 4.5: Help-Squeak-Project-kfr.10.mcz

commits at source.squeak.org commits at source.squeak.org
Fri Jan 24 20:14:05 UTC 2014


Chris Muller uploaded a new version of Help-Squeak-Project to project Squeak 4.5:
http://source.squeak.org/squeak45/Help-Squeak-Project-kfr.10.mcz

==================== Summary ====================

Name: Help-Squeak-Project-kfr.10
Author: kfr
Time: 4 January 2014, 8:00:38.548 pm
UUID: b86eb622-cc53-634d-aa65-aed2c86263f9
Ancestors: Help-Squeak-Project-cmm.9

Berts exelente introduction to working with the Squeak Image

==================== Snapshot ====================

SystemOrganization addCategory: #'Help-Squeak-Project'!

CustomHelp subclass: #SqueakHelp
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakHelp class>>bookName (in category 'accessing') -----
bookName 
	^'Squeak'!

----- Method: SqueakHelp class>>icon (in category 'accessing') -----
icon
	(self name = #SqueakHelp) ifTrue: [^HelpIcons iconNamed: #squeakIcon].
	^nil!

----- Method: SqueakHelp class>>pages (in category 'accessing') -----
pages
	^#(SqueakProjectHelp SqueakToolsHelp SqueakTutorials)!

SqueakHelp subclass: #SqueakProjectHelp
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

SqueakProjectHelp subclass: #SqueakLicenseHelp
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakLicenseHelp class>>bookName (in category 'accessing') -----
bookName 
	^'License'!

----- Method: SqueakLicenseHelp class>>licenseChange (in category 'pages') -----
licenseChange
	^HelpTopic 
		title: 'License has changed with 4.0'
		contents: 'On 23 September 1996, Apple Computer Inc. released Squeak V1.1 under the "Squeak License" (SqL).

On May 8, 2006 Apple agreed to relicense original Squeak V1.1 under the Apple Public Source License.

On October 12, 2006 Apple granted permission to relicense under Apache license 2.0.

In 2006, VPRI began to collect "Distribution Agreements" for all contributors to Squeak since V1.1 up to V3.8, asking them to relicense their contributions, which were originally licensed under SqL, to the MIT license. This was a great effort on behalf of many and VPRI has 100s of signed documents agreeing to this.

Do you want to contribute source to Squeak?All new contributions since 4.0 must be under the MIT license. When you make your code available, please state explicitly in some form such as the description on a web site or email announcement that your contribution is under the MIT license. (It doesn''t have to be exclusive; you can release it under difference licenses at the same time.)

Have you contributed source to Squeak? If you believe you have, but have not sent in an agreement to allow your submission(s) to be licensed under the MIT license then please see http://netjam.org/squeak/contributors. There you can find a list of known contributors and a PDF of the agreement with instructions. The snail mail address is found in the agreement PDF file.

Also there are a few people for which we are lacking full contact information. If you think you can help please also visit the link above and see if you can identify any of the unknown developer initials or any of the developers for whom we do not have a current email address.' !

----- Method: SqueakLicenseHelp class>>officialLicense (in category 'pages') -----
officialLicense
	^HelpTopic 
		title: 'Official License - 4.0'
		contents: 'Copyright (c) The individual, corporate, and institutional contributors who have collectively contributed elements to this software ("The Squeak Community"), 1996-2011 All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Portions of Squeak are covered by the following license


Copyright (c) Xerox Corp. 1981, 1982 All rights reserved.
Copyright (c) Apple Computer, Inc. 1985-1996 All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.'!

----- Method: SqueakLicenseHelp class>>pages (in category 'accessing') -----
pages
	^#(licenseChange officialLicense)!

----- Method: SqueakProjectHelp class>>bookName (in category 'accessing') -----
bookName 
	^'The Project'!

----- Method: SqueakProjectHelp class>>introduction (in category 'pages') -----
introduction
	^HelpTopic
		title: 'Welcome'
		icon: (HelpIcons iconNamed: #squeakIcon)
		contents:
'WELCOME

Squeak is a modern, open source, full-featured implementation of the powerful Smalltalk programming language and environment. Squeak is highly-portable - even its virtual machine is written entirely in Smalltalk making it easy to debug, analyze, and change. Squeak is the vehicle for a wide range of projects from multimedia applications, educational platforms to commercial web application development.'!

----- Method: SqueakProjectHelp class>>pages (in category 'accessing') -----
pages
	^#(introduction )!

SqueakHelp subclass: #SqueakToolsHelp
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakToolsHelp class>>basicDevelopmentTools (in category 'pages') -----
basicDevelopmentTools
	^HelpTopic 
		title: 'Basic Development Tools'
		contents: 'Smalltalk environments have some of the best user interfaces for programmers ever devised. Those who have programmed in Lisp under Emacs have some idea, but Smalltalk is even better.
		
You should learn these basic tools thoroughly:
- Workspace
- Transcript
- Browser
- Inspector
- File List
- Change Sorter
- Debugger
- Method Finder		
'!

----- Method: SqueakToolsHelp class>>bookName (in category 'accessing') -----
bookName 
	^'Tools'!

----- Method: SqueakToolsHelp class>>pages (in category 'accessing') -----
pages
	^#(basicDevelopmentTools)!

SqueakToolsHelp subclass: #SqueakToolsTranscriptHelp
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakToolsTranscriptHelp class>>bookName (in category 'accessing') -----
bookName
	^'Transcript'!

----- Method: SqueakToolsTranscriptHelp class>>pages (in category 'accessing') -----
pages
	^# (transcript)!

----- Method: SqueakToolsTranscriptHelp class>>transcript (in category 'pages') -----
transcript
	^HelpTopic 
		title: 'The Transcript window'
		contents: 'The Transcript window is often used for logging or printing results from text only code. 
To open the Transcript use TheWorldMenu and choose ''open...''. Then choose ''Transcript''.
You can also type

   Transcript open

in a Workspace and doIt.
'!

SqueakToolsHelp subclass: #SqueakToolsWorkspaceHelp
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakToolsWorkspaceHelp class>>bookName (in category 'accessing') -----
bookName 
	^'Workspace'!

----- Method: SqueakToolsWorkspaceHelp class>>openWorkspace (in category 'pages') -----
openWorkspace
	^HelpTopic 
		title: 'Open a Workspace'
		contents: 'You can open a Workspace window in any of the following ways:
		
- Keyboard Shortcut: while pointing at an empty part of the Squeak window, press alt-k (in Windows) or cmd-k (on a Mac)
- World Menu: select "Workspace"
- Tools Flap: click on the Tools Flap. When it comes out, drag the Workspace icon out.
- Doit: select inside the following quote and doit: "Workspace open"'!

----- Method: SqueakToolsWorkspaceHelp class>>pages (in category 'accessing') -----
pages
	^#(workspace openWorkspace saveWorkspace)!

----- Method: SqueakToolsWorkspaceHelp class>>saveWorkspace (in category 'pages') -----
saveWorkspace
	^HelpTopic 
		title: 'Saving Workspace to a File'
		contents: 'You can save the text content of a Workspace to a file by choosing the workspace menu (from within the workspace), then ''more...'', then ''save contents to file...''.'!

----- Method: SqueakToolsWorkspaceHelp class>>workspace (in category 'pages') -----
workspace
	^HelpTopic 
		title: 'What is a Workspace'
		contents: 'A Workspace is a window used as a scratchpad area where fragments of Smalltalk code can be entered, stored, edited, and evaluated.'!

SqueakHelp subclass: #SqueakTutorials
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakTutorials class>>bookName (in category 'accessing') -----
bookName 
	^'Tutorials'!

----- Method: SqueakTutorials class>>introduction (in category 'pages') -----
introduction
	"This method was automatically generated. Edit it using:"
	"SqueakTutorials edit: #introduction"
	^HelpTopic
		title: 'Introduction'
		contents: 
'Here you will some short tutorials on how to use Squeak for daily tasks. Feel free to add your own.!!' readStream nextChunkText!

----- Method: SqueakTutorials class>>pages (in category 'accessing') -----
pages
	^#(introduction)!

SqueakTutorials subclass: #SqueakTutorialsOnImage
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakTutorialsOnImage class>>bookName (in category 'as yet unclassified') -----
bookName 
	^'The Squeak Image'!

----- Method: SqueakTutorialsOnImage class>>pages (in category 'as yet unclassified') -----
pages
	^# (theImage)!

----- Method: SqueakTutorialsOnImage class>>theImage (in category 'as yet unclassified') -----
theImage
	^HelpTopic 
		title: 'Working with the Squeak Image'
		contents: 'Working with the ecosystem of objects in a Smalltalk image.
		
The basic tool for this is called an Inspector. Whenever you have an expression, like "3 + 4", you press cmd-i to "inspect it", which opens an inspector on the result. This works in any text area. Try for example inspecting "self" in a class browser, and you will inspect the underlying class object (which the browser shows a high-level view of).

In the Inspector you see the objects referenced by this object (via instance variables or indexed fields) in the left panel. Select any of them and choose "inspect" from the context menu (or press cmd-i again). This way you can inspect all the objects in the system.

A more modern tool than the Inspector (which was around 40 years ago already) is the Object Explorer. It presents you a tree view of an object and its "children", which again are the instance variables and indexed fields of the object. Open it with cmd-shift-i (or "explore" in the context menu).

You can also do the reverse. If you choose "objects pointing to this value" you get an inspector showing all the objects that directly point to this object. Similarly there is a "reverse explorer", which you can open by selecting "explore pointers".

There are two roots to all the objects in the system:

        Smalltalk specialObjectsArray

which basically holds everything the Virtual Machine needs to know about, and in turn almost every object in the whole image, and

        thisContext

which is the current execution context, holding onto temporary objects. When a garbage collection is performed, any object not reachable form either of these two roots is removed from memory.

An "interesting" global object to explore is

        Project current

which holds your current workspace, in particular

        Project current world

, the root of all morphs in the world. And of course

        Smalltalk

itself is the dictionary that holds all global objects, including all classes (unless they are defined in a non-global environment).

There is also a low-level way to enumerate all objects in memory. "self someObject" will return the very first object in memory (which happens to be the nil object), and "anObject nextObject" will return the next one:

        | object count |
        count := 0.
        object := self someObject.
        [0 == object]
                whileFalse: [count := count + 1.
                        object := object nextObject].
        count

Interestingly, this also finds objects that are due to be garbage-collected. For example, if you accidentally closed a text window, there is a good chance its contents will still be in memory, and can be retrieved using an expression like

        ByteString allInstances last: 10

This makes use of the someInstance/nextInstance methods, which are similar to someObject/nextObject, but restricted to instances of one class only.
'!

SqueakTutorials subclass: #SqueakTutorialsOnXML
	instanceVariableNames: ''
	classVariableNames: ''
	poolDictionaries: ''
	category: 'Help-Squeak-Project'!

----- Method: SqueakTutorialsOnXML class>>bookName (in category 'accessing') -----
bookName 
	^'XML'!

----- Method: SqueakTutorialsOnXML class>>dataRetrieval (in category 'pages') -----
dataRetrieval
	^HelpTopic 
		title: 'Retrieving XML data'
		contents: 
'Retrieving data from XML documents is simple and easy in Squeak Smalltalk. This tutorial demonstrates the fundamentals with a straightforward approach where code can be tested right away either here or in a Workspace window. The beauty of Squeak Smalltalk resides in the possibility to evaluate, inspect, print and debug code anywhere and this window is no different. 

This tutorial demonstrates how to...

	* retrieve an XML document from the World Wide Web
	* instantiate an XML document class
	* inspect and understand the content of an XML document
	* retrieve and display values from specific XML tags

Retrieve an XML document from the World Wide Web

There are many manners to retrieve data from the World Wide Web in Squeak Smalltalk. HTTPClient is among them and allows to download files in all simplicity. Select the following code snippet and inspect it (press alt-i). An Inspect window will open with the document loaded in memory. The result is a MIMEDocument object.

	HTTPClient httpGetDocument: ''http://source.squeak.org/trunk/feed.rss''.

TIP: Select HTTPClient and browse it (press alt-b) to open a System Browser window on its class. HTTPClient does not have instance methods but it has class methods. Click on class to see class methods.

Instantiate an XML Document

An instance of MIMEDocument will not allow to retrieve XML data in a comprehensive manner because it does not understand the nature of XML. For this reason, it is necessary to parse the content of MIMEDocument using XMLDOMParser. XMLDOMParser>>parseDocumentFrom: requires a stream as a parameter and ReadStream will be used for this purpose. The following code snippet instantiates an XMLDocument using the content of the downloaded file.

	| doc |
	doc := HTTPClient httpGetDocument: ''http://source.squeak.org/trunk/feed.rss''.
	XMLDOMParser parseDocumentFrom: (ReadStream on: (doc content)).

Inspect and understand the content of an XML document

XML is a flexible document format and it is necessary to understand how each given XML file is structured in order to properly search, retrieve and manipulate data. Inspecting values is critical in a dynamic programming language and environment, such as Squeak Smalltalk. Select the previous code snippet and inspect it (press alt-i).

Unfortunately, the Inspect window does not reveal a lot about the XML structure of the downloaded file. Select the previous code snippet once again and explore it (press alt and the capital letter i). An Explorer window will open with a tree outline on the instance of XMLDocument.

The Inspect and Explorer windows tell a lot about an XMLDocument. The sections are instance variables and their values are displayed aside. In the Explorer window, unfold elementsAndContents. Unfold other sections as deemed necessary to understand the XML format and the data available.

The gibberish coding is about to become clear. Open a Browser window from the world menu and right click in the first pane, select find class (press alt-f) and type XMLDocument to search for its class, or select the class name and browse it (press alt-b). However, it is suggested to read more about XMLParser and XMLParserTest first. 

Retrieve and display values from specific XML tags

The downloaded XML file contains a list of items which are denoted by the tag name "item". The Explorer window revealed the content of interest is located at the array index 1 of the elementsAndContents, which can be accessed through XMLDocument>>root.

TIP: Some XML documents have additional components contained within its file, such as XMLPI (XML Processing Instructions). For this reason, the root may lead to this rather than the data which will be indexed at 2 or more. It is necessary to use XMLNodeWithElements>>elements, e.g. (xml elements at: 2), in order to access subsequent data.

The following code snippet will display items in a Transcript window. Open a Transcript window using the world menu before selecting and executing the code. Select the code snippet and execute it (press alt-d).

	| doc xml |
	doc := HTTPClient httpGetDocument: ''http://source.squeak.org/trunk/feed.rss''.
	xml := XMLDOMParser parseDocumentFrom: (ReadStream on: (doc content)).
	xml root tagsNamed: #item do: [:e |
		Transcript show: (e asString); cr.
		].

An XML item looks like this:

	<item>
	<title>HelpSystem-Core-tbn.46.mcz</title>
	<link>http://source.squeak.org/trunk.html</link>
	<description>throw out pharo specific stuff since we are now integrated in squeak (and pharo too where squeak specific stuff was removed)</description>
	<pubDate>Sun, 02 May 2010 20:23:49 +0000</pubDate>
	<author>Torsten Bergmann &lt;Torsten.Bergmann at astares.de&gt;</author>
	<category>The Trunk</category>
	<enclosure length="27288" type="application/x-monticello" url="http://source.squeak.org/trunk/HelpSystem-Core-tbn.46.mcz"/> 
	<guid isPermaLink="false"/> </item>

The following code snippet uses information learned, retrieves each comment and displays them in a Transcript window. Notice an author can have a nil value and is handled accordingly.

	| doc xml |
	doc := HTTPClient httpGetDocument: ''http://source.squeak.org/trunk/feed.rss''.
	xml := XMLDOMParser parseDocumentFrom: (ReadStream on: (doc content)).
	xml root tagsNamed: #item do: [:e |
		Transcript 
			show: ''Date: '', ((e firstTagNamed: #pubDate) contentString); cr;
			show: ''Title: '', ((e firstTagNamed: #title) contentString); cr;
			show: ''Author: '', 
				(((e firstTagNamed: #author) notNil)
					ifTrue: [(e firstTagNamed: #author) contentString]
					ifFalse: ['''']); cr;
			show: ''Description: '', ((e firstTagNamed: #description) contentString); cr; cr.
			].

An item will now look like:

	Date: Sun, 02 May 2010 20:23:49 +0000
	Title: HelpSystem-Core-tbn.46.mcz
	Author: Torsten Bergmann <Torsten.Bergmann at astares.de>
	Description: throw out pharo specific stuff since we are now integrated in squeak (and pharo too where squeak specific stuff was removed)
'!

----- Method: SqueakTutorialsOnXML class>>pages (in category 'accessing') -----
pages
	^# (dataRetrieval)!

----- Method: HelpIcons class>>squeakIcon (in category '*help-squeak-project') -----
squeakIcon
	^(Form
	extent: 12 at 12
	depth: 32
	fromArray: #( 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 75398782 26843545 0 0 1159996452 1378823983 338044454 0 0 0 0 455682345 1295266868 1126376227 0 0 1040582150 0 1328097577 0 0 0 23488102 1277502757 0 1076834095 0 0 1075781407 0 287647013 472854319 0 0 471472666 204089898 0 1092756002 0 0 1041963803 36909875 0 1880232466 454761243 287515427 1342572038 0 104939841 974460181 0 0 270080281 354690084 86846765 3674539269 1394219546 1611599631 3557427722 86123042 388244516 204287277 0 26843545 605558808 1025055001 1008014613 1159141143 522264865 739710743 1159141143 571083274 570820102 188891714 0 942550574 1411391520 1143021857 1312241463 1428563494 3205040393 3708159494 1663576104 1511067921 1579887403 1629758500 958472481 656679972 439563059 1294608938 839913488 739644950 172246084 221459251 840900383 1075978786 1209933342 724512559 707077413 0 0 0 0 0 0 0 0 0 0 38488907 0 0 0 0 0 0 0 0 0 0 0 0 0)
	offset: 0 at 0)!



More information about the Squeak-dev mailing list