Dokument och partitioner

I plattformens textramverk definieras en dokumentmodell. Text som används i denna modell kan visas i ett visningsprogram som finns i textramverket. Vi börjar med att titta på hur denna modell används i exemplet med Java-redigeraren. Vi kommer inte rikta in oss på grundmekanismen för registrering av en redigerares tillägg eftersom vi redan tagit upp detta i avsnittet org.eclipse.ui.editors. Vi kommer istället titta på specifikationerna om hur redigerarklassen implementeras i exemplet.

Dokumentproviders och dokument

I arbetsmiljön öppnas normalt en redigerare när användaren väljer ett domänelement (som t.ex. en fil eller ett element lagrad i en arkivfil) och öppnar det. När redigeraren skapas, associeras den med en redigerarinmatning (IEditorInput), som beskriver det objekt som redigeras.

Java-redigeraren öppnas när användaren öppnar en fil med tillägget "*.jav". I detta fall är inmatningen till redigeraren en IFileEditorInput. I plattformens textramverk antas lite om själva inmatningen till redigeraren. Det fungerar med en presentationsmodell som kallas IDocument, för inmatningen, så text kan effektivt visas och manipuleras.

Det innebär att en förväntad domänmodell (redigerarinmatning) på något sätt måste avbildas till presentationsmodellen. Den här mappningen definieras i IDocumentProvider. När redigeraren får en inmatning, returnerar dokumentleveratören ett lämpligt IDocument.

I exemplet med Java-redigeraren ärvs TextFileDocumentProvider som definierats i insticksprogrammet org.eclipse.ui.editors. Tillägget org.eclipse.ui.editors.documentProviders används för att definiera mappningar mellan redigerarens inmatningstyper (eller filtillägg) och dokumentproviders. I redigerarnas insticksprogram definieras aktuell dokumentprovider enligt följande:

   <extension
         point="org.eclipse.ui.editors.documentProviders">
      <provider
            class="org.eclipse.ui.editors.text.TextFileDocumentProvider"
            inputTypes="org.eclipse.ui.IStorageEditorInput"
            id="org.eclipse.ui.editors.text.StorageDocumentProvider">
      </provider>
   </extension>

Med hjälp av den här utökningspunkten kan man via insticksprogram registrera dokumentproviders och associera dem med ett filtillägg eller en redigerares inmatningsklass. Eftersom det inte definieras något tillägg för egen dokumentprovider i exemplet med Java-redigeraren, ärvs den allmänna dokumentleveratören som specificerats för alla inmatningstyper som är IStorageEditorInput. När användaren öppnar en fil för redigering, skapas korrekt förekomst av dokumentprovider i plattformen. Om en viss dokumentprovider registrerats för filtillägget, används den. Om det inte finns någon specifik dokumentprovider för filtillägget används redigerarens inmatningstyp för att hitta en lämplig provider.

Genom att använda den allmänna dokumentprovidern i plattformen, kan man i exemplet med Java-redigeraren utnyttja alla funktioner hos dokumentprovidern som t.ex. filbuffert och andra optimeringsfunktioner.

Dokumentinställning

Eftersom plattformens textdokumentprovider används i Java-redigeraren, hur kan man då få specialiserat beteende för hantering av Java-filer?

Tillägget org.eclipse.core.filebuffers.documentSetup används för definition av mappningar mellan filtillägg och en IDocumentSetupParticipant. Dokumentet ställs in med eventuella specialfunktioner när det levererats till redigeraren.

<extension
	id="ExampleJavaDocumentSetupParticipant"
	name="%documentSetupParticipantName"
	point="org.eclipse.core.filebuffers.documentSetup">
	<participant
		extensions="jav"
		class="org.eclipse.ui.examples.javaeditor.JavaDocumentSetupParticipant">
	</participant>
</extension>

Med hjälp av den här tilläggsdefinitionen kan dokumentet i exemplet ställas in för Java-specifika åtgärder. Så vad gör JavaDocumentSetupParticipant? Vi ska titta på en förenklad version av setup-metoden.

 	public void setup(IDocument document) {
		...
		IDocumentPartitioner partitioner= new FastPartitioner(JavaEditorExamplePlugin.getDefault().getJavaPartitionScanner(), JavaPartitionScanner.JAVA_PARTITION_TYPES);
		partitioner.connect(document);
		...
	}

I inställningskoden konfigureras ett objekt som kallas partitionsdelare.

Partitioner

Partitionsdelaren (IDocumentPartitioner) ansvarar för att dela in dokumentet i icke-överlappande sektioner som kallas partitioner. Partitioner (representeras av ITypedRegion) är användbara då man vill hantera olika sektioner i ett dokument på olika sätt när det gäller funktioner som syntaxmarkering eller -formatering.

I exemplet med Java-redigeraren delas dokumentet in i partitioner som representerar javadoc-kommentarer, flerradskommentarer och allting annat. Varje sektion tilldelas en innehållstyp och en position i dokumentet. Positioner uppdateras när användaren redigerar text.

Regelbaserad dokumentpartitionering

Varje redigerare bestämmer lämplig dokumentpartitionsdelare. Stöd för regelbaserad dokumentskanning finns i org.eclipse.jface.text.rules. Med hjälp av en regelbaserad skanner kan ramverkets FastPartitioner användas i en redigerare.

IDocumentPartitioner partitioner= new FastPartitioner(JavaEditorExamplePlugin.getDefault().getJavaPartitionScanner(), JavaPartitionScanner.JAVA_PARTITION_TYPES);

RuleBasedPartitionScanner är superklassen för regelbaserade skannrar. Subklasser ansvarar för uppräkning och implementering av reglerna som används för att urskilja symboler som t.ex. radavgränsare, blanktecken och allmänna mönster när ett dokument skannas. I JavaPartitionScanner i exemplet definieras regler för att urskilja enradskommentarer, teckenkonstanter, javadoc, flerradskommentarer och ord. Det görs i skanners konstruktionsmodul:

public JavaPartitionScanner() {
	super();
	IToken javaDoc= new Token(JAVA_DOC);
	IToken comment= new Token(JAVA_MULTILINE_COMMENT);

	List rules= new ArrayList();
	// Lägg till regel för enradskommentarer.
	rules.add(new EndOfLineRule("//", Token.UNDEFINED)); 

	// Lägg till regel för strängar och teckenkonstanter.
	rules.add(new SingleLineRule("\"", "\"", Token.UNDEFINED, '\\')); 
	rules.add(new SingleLineRule("'", "'", Token.UNDEFINED, '\\')); 

	// Lägg till specialfallsregel för ord.
	rules.add(new WordPredicateRule(comment));

	// Lägg till regler för flerradskommentarer och javadoc.
	rules.add(new MultiLineRule("/**", "*/", javaDoc, (char) 0, true)); 
	rules.add(new MultiLineRule("/*", "*/", comment, (char) 0, true)); 

	IPredicateRule[] result= new IPredicateRule[rules.size()];
	rules.toArray(result);
	setPredicateRules(result);
}

Mer information om definition av regler och tillgängliga regeltyper finns i avsnittet om klasserna i org.eclipse.jface.text.rules.  Vi återkommer till skannrarna när vi tittar närmare på syntaxfärgläggning.