&TC.Hollingsworth; &TC.Hollingsworth.mail;
Emir
SARI

    emir_sari@icloud.com

Çeviri

# &katepart;'ı genişletmek

## Giriş

Herhangi bir gelişmiş metin düzenleyicisi bileşeni gibi &katepart; da işlevselliğini genişletmek için çeşitli yollar sunar. &javascript; ile basit betikler yazarak yeni özellikler ekleyebilirsiniz. Son olarak, &katepart; için yeni özellikler yazdıktan sonra bize katılın ve iyileştirmelerinizi dünyanın geri kalanıyla paylaşın!

## Sözdizim Vurgulama ile çalışmak

### Genel Bakış

Sözdizim Vurgulama, dosyanın amacına göre dizinin işlevine bağlı olarak düzenleyicinin metni kendiliğinden farklı biçemlerde/renklerde görüntülemesini sağlayan şeydir. Örneğin program kaynak kodunda, denetim ifadeleri kalın harflerle gösterilebilirken, veri türleri ve yorumlar metnin geri kalanından farklı renkler alır. Bu, metnin okunabilirliğini büyük ölçüde artırır ve böylece yazarın daha verimli ve üretken olmasına yardımcı olur.

Sözdizim vurgulama ile gösterilen bir C++ işlevi.

Sözdizim vurgulama ile gösterilen bir C++ işlevi.

Aynı C++ işlevi, vurgulama olmadan.

Aynı C++ işlevi, vurgulama olmadan.

İki örnekten hangisini okuması daha kolay?

&kappname;, sözdizim vurgulaması yapmak için esnek, yapılandırılabilir ve yetenekli bir sistemle birlikte gelir ve standart dağıtım, çok çeşitli programlama, komut dosyası yazma ve işaretleme dilleri ve diğer metin dosyası biçimleri için tanımlar sağlar. Ayrıca basit &XML; dosyalarında kendi tanımlarınızı da sağlayabilirsiniz.

&kappname;, bir dosyayı açtığınızda onun doğru sözdizim kurallarını sırasıyla &MIME; türü, dosya uzantısı veya bunlardan ikisi de yoksa içeriğine bakarak algılayacaktır. Yanlış bir seçimle karşı karşıya kalırsanız Araçlar Vurgulama menüsünden elle bir vurgulama türü seçebilirsiniz.

Sözdizim vurgulamaları tarafından kullanılan biçemler ve renkler yapılandırma iletişim kutusunun Vurgulanan Metin Biçemleri sekmesinden düzenlenebilirken, &MIME; türleri ve kullanması gereken dosya uzantıları ise Kipler ve Dosya Türleri sekmesinden ayarlanır.

Sözdizim vurgulama, doğru metnin okunabilirliğini artırmak için vardır; ancak metninizi doğrulamak için ona güvenemezsiniz. Kullandığınız biçime bağlı olarak metni sözdizimi için işaretlemek zordur ve bazı durumlarda sözdizim kurallarının yazarları metnin %​98’i doğru şekilde oluşturulursa gurur duyacaktır; ancak çoğunlukla yanlış %​2’yi görmek için nadir bir biçeme gereksiniminiz vardır.

### &kappname; Sözdizim Vurgulama Sistemi

Bu bölümde &kappname; sözdizim vurgulama mekanizmasını daha ayrıntılı olarak ele alacağız. Bu konuda bilgi sahibi olmak istiyor ve sözdizim tanımlarını değiştirmek veya yeni bir tane oluşturmak istiyorsanız tam size göre.

#### Nasıl Çalışır

Bir dosyayı açtığınızda &kappname; düzenleyicisinin yaptığı ilk şeylerden biri, dosya için hangi sözdizim tanımının kullanılacağını algılamaktır. Dosya metnini okurken ve siz dosyaya bir şeyler yazarken, sözdizim vurgulama sistemi, sözdizim tanımıyla tanımlanan kuralları kullanarak metni çözümleyecek ve farklı bağlamların ve biçimlerin başladığı ve bittiği yerleri imleyecektir.

Belgeye bir şeyler yazdığınızda, yeni metin anında çözümlenir ve imlenir; böylece, bir bağlamın başlangıcı veya sonu olarak imlenen bir karakteri silerseniz çevreleyen metnin biçemi buna göre değişir.

&kappname; Sözdizim Vurgulama Sistemi tarafından kullanılan sözdizim tanımları &XML; dosyalarıdır ve şunları içerir:

- Bağlam blokları halinde düzenlenmiş metnin rolünü algılamaya yönelik kurallar

- Anahtar sözcük listeleri

- Biçem ögesi tanımları

Metin çözümlenirken algılama kuralları tanımlandıkları sıraya göre değerlendirilir ve geçerli dizinin başlangıcı bir kuralla eşleşiyorsa ilgili bağlam kullanılır. Metindeki başlangıç noktası, kuralın eşleştiği son noktaya taşınır ve eşleşen kural tarafından belirlenen bağlamdan başlayarak yeni bir kurallar döngüsü başlar.

#### Kurallar

Algılama kuralları, vurgulama algılama sisteminin kalbidir. Kural, çözümlenen metinle eşleştirilecek bir dizi, karakter veya düzenli ifadedir. Metnin eşleşen kısmı için hangi biçemin kullanılacağı hakkında bilgi içerir. Sistemin çalışma bağlamını ya açıkça belirtilen bir bağlama ya da metin tarafından kullanılan önceki bağlama çevirebilir.

Kurallar bağlam gruplarında düzenlenir. Bir bağlam grubu, biçim içindeki ana metin kavramları için kullanılır; örneğin, alıntılanan metin dizileri veya program kaynak kodundaki yorum blokları. Bu, vurgulama sisteminin gerekli olmadığında tüm kurallar arasında döngü yapmasına gerek kalmamasını ve metindeki bazı karakter dizilerinin geçerli bağlama bağlı olarak farklı şekilde ele alınabilmesini sağlar.

Örneklere özgü verinin kurallarda kullanılmasına izin vermek için bağlamlar devingen olarak oluşturulabilir.

#### Bağlam Biçemleri ve Anahtar Sözcükler

Bazı programlama dillerinde tamsayılar, derleyici (kaynak kodunu ikili yürütülebilir dosyaya dönüştüren program) tarafından kayan noktalı sayılardan farklı şekilde ele alınır ve tırnak içine alınan bir dizi içinde özel bir anlama sahip karakterler olabilir. Bu gibi durumlarda, metni okurken kolayca tespit edilebilmeleri için onları çevreden farklı kılmak mantıklıdır. Dolayısıyla, özel bağlamları temsil etmeseler bile sözdizim vurgulama sistemi tarafından bu şekilde görülebilirler, böylece farklı sunum için imlenebilirler.

Bir sözdizim tanımı, kullanıldığı biçimin kavramlarını kapsayacak kadar çok sayıda biçem içerebilir.

Pek çok biçimde belirli bir kavramı temsil eden sözcük listeleri bulunur. Örneğin, programlama dillerinde, denetim ifadeleri bir kavramdır, veri türü adları başka bir kavramdır ve dilin yerleşik işlevleri üçüncüsüdür. &kappname; Sözdizim Vurgulama Sistemi, metin biçimlerinin kavramlarını vurgulamak amacıyla metindeki sözcükleri tespit etmek ve imlemek için bu tür listeleri kullanabilir.

#### Öntanımlı Biçemler

&kappname;'de bir C++ kaynak dosyası, bir &Java; kaynak dosyası ve bir &HTML; belgesi açarsanız biçimler farklı olsa ve dolayısıyla özel işlem için farklı sözcükler seçilse bile, kullanılan renklerin aynı olduğunu göreceksiniz. Bunun nedeni, &kappname;'in ayrı ayrı sözdizimi tanımları tarafından kullanılan, önceden tanımlanmış bir Öntanımlı Biçemler listesine sahip olmasıdır.

Bu, farklı metin biçimlerindeki benzer kavramların tanınmasını kolaylaştırır. Örneğin, yorumlar hemen hemen her programlama, komut dosyası veya biçimlendirme dilinde bulunur ve tüm dillerde aynı biçem kullanılarak oluşturulduklarında, bunları metin içinde bunların ne olduğunu tanımlamaya çalışmakla vakit kaybetmezsiniz.

Bir sözdizim tanımındaki tüm biçemler, öntanımlı biçemlerden birini kullanır. Birkaç sözdizim tanımı, öntanımlılardan daha çok biçem kullanır; bu nedenle, bir biçimi sık sık kullanıyorsanız bazı kavramların aynı biçemi kullanıp kullanmadığını görmek için yapılandırma iletişim kutusunu açmanız faydalı olabilir. Örneğin, diziler için yalnızca bir öntanımlı biçem vardır; ancak Perl programlama dili iki tür diziyle çalıştığından, bunları biraz farklı olacak şekilde yapılandırarak vurgulamayı geliştirebilirsiniz. Tüm kullanılabilir öntanımlı biçemler daha sonra açıklanacaktır.

### &XML; Vurgu Tanımı Biçimi

#### Genel Bakış

&kappname;, &kde-frameworks;'ten Syntax-Highlighting kitaplığını kullanır. &kappname; ile verilen öntanımlı &XML; vurgulama dosyaları, Syntax-Highlighting tarafından öntanımlı olarak derlenirler.

Bu bölüm, &XML; Vurgu Tanımı biçimine genel bir bakış sunar. Küçük bir örneğe dayanarak ana bileşenleri, bunların anlamlarını ve kullanımlarını açıklayacağız. Bir sonraki bölümde vurgu algılama kurallarının ayrıntılarına girilecektir.

XSD olarak da bilinen resmi tanım, Sözdizim Vurgulama deposundaki `language.xsd` dosyasında bulunabilir

`.xml` vurgu tanımlama dosyaları, kullanıcı klasörünüzde genelde ``$HOME`/.local/share/` ve `/usr/share/` olan ``qtpaths``--paths GenericDataLocation`` ile `org.kde.syntax-highlighting/syntax/` konumunda bulunur.

Flatpak ve Snap paketlerinde, yukarıdaki dizin işe yaramaz; çünkü her bir uygulamanın veri konumları farklıdır. Bir Flatpak uygulamasında, özel &XML; dosyalarının konumu genellikle ``$HOME`/.var/app/flatpak-package-name/data/org.kde.syntax-highlighting/syntax/` olup Snap uygulamalarında ise ``$HOME`/snap/snap-package-name/current/.local/share/org.kde.syntax-highlighting/syntax/` olur.

&Windows;'ta bu dosyalar genelde `C:\Users\user` `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax` olarak genişleyen %USERPROFILE% konumundadır.

Özetle, çoğu yapılandırma için özel &XML; dosyalarının dizini aşağıdaki gibidir:

Yerel kullanıcı için | ``$HOME`/.local/share/org.kde.syntax-highlighting/syntax/`
Tüm kullanıcılar için | `/usr/share/org.kde.syntax-highlighting/syntax/`
Flatpak paketleri için | ``$HOME`/.var/app/flatpak-package-name/data/org.kde.syntax-highlighting/syntax/`
Snap paketleri için | ``$HOME`/snap/snap-package-name/current/.local/share/org.kde.syntax-highlighting/syntax/`
&Windows; üzerinde | `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\syntax`

Aynı dil için birden çok dosya varsa `language` ögesindeki en yüksek `version` özniteliğine sahip dosya yüklenir.

##### &kappname; Vurgu Tanımı dosyalarının ana bölümleri

Vurgulama dosyası, &XML; sürümünü ayarlayan bir üstbilgi içerir:

      <?xml version="1.0" encoding="UTF-8"?>

Tanım dosyasının kökü öge `dilidir`. Kullanılabilir öznitelikler şunlardır:

  Zorunlu öznitelikler:

  `name`, dilin adını ayarlar. Sonrasında menülerde ve iletişim kutularında görünür.

  `section`, kategoriyi belirtir.

  `extensions`, dosya uzantılarını tanımlar, "*.cpp;*.h" gibi

  `version`, tanım dosyasının geçerli revizyonunu bir tamsayı türünden belirtir. Vurgu tanımı dosyasını değiştirdiğinizde bu sayıyı artırdığınızdan emin olun.

  `kateversion`, en son desteklenen &kappname; sürümünü belirtir.

  İsteğe bağlı öznitelikler:

  `mimetype`, dosyaların &MIME; türlerini ilişkilendirir.

  `casesensitive`, anahtar sözcüklerin BÜYÜK/küçük harf duyarlı olup olmadığını tanımlar.

  `priority`, başka bir vurgu tanım dosyası aynı uzantıları kullanıyorsa gereklidir. Daha yüksek öncelik kazanır.

  `author`, yazarın adını ve e-posta adresini içerir.

  `license`, lisansı içerir. Yeni sözdizim vurgulama dosyaları için genelde MIT lisansıdır.

  `style`, sağlanan dili içerir ve `required-syntax-style` özniteliği için olan girintileyiciler tarafından kullanılır.

  `indenter`, öntanımlı olarak hangi girintileyicinin kullanılacağını tanımlar. Kullanılabilir girintileyiciler: ada, normal, cstyle, cmake, haskell, latex, lilypond, lisp, lua, pascal, python, replicode, ruby ve xml.

  `hidden`, adın &kappname; menülerinde görünüp görünmeyeceğini tanımlar.

  Böylece, bir sonraki satır böyle görünebilir:

      <language name="C++" version="1" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" />

Sonrasında `highlighting` ögesi gelir. Bu öge, isteğe bağlı `list` ögesini ve zorunlu `contexts` ve `itemDatas` ögelerini içerir.

  `list` ögeleri bir anahtar sözcükler listesi içerir. Bu durumda, anahtar sözcükler class ve const olur. İstediğiniz kadar liste ekleyebilirsiniz.

  &kde-frameworks; 5.53 sürümünden bu yana, bir liste, başka bir listeden ve/veya dilden/dosyadan `include` ögesini kullanarak anahtar sözcükler içerebilirler. `IncludeRules` kuralında olduğu gibi, `##`, liste adını ve dil tanımını ayırmak için kullanılır. Bu, başka bir dilin/dosyanın anahtar sözcüklerini içermeniz gerekiyorsa yinelenen anahtar sözcük listelerini önlemek için yararlıdır. Örneğin, othername listesi, ISO C++ diline ait olan str anahtar sözcüğünü ve types listesinin tüm anahtar sözcüklerini içerir.

  `contexts` ögesi tüm bağlamları içerir. İlk bağlam, öntanımlı olarak, vurgulamanın başlangıcıdır. Normal Text adlı bağlamda iki adet kural vardır: somename adındaki bir kuralla eşleşen anahtar sözcükler ve bir tırnağı algılayıp bağlamı string yapan başka bir tanesi. Kurallar hakkında daha fazla bilgi almak için sonraki fasılı okuyun.

  Üçüncü kısımsa `itemDatas` ögesidir. Bağlamlar ve kurallar tarafından gereksinim duyulan tüm renk ve yazıtipi biçemlerini içerir. Bu örnekte, `itemData` Normal Text, String ve Keyword kullanılmıştır.

      <highlighting>
          <list name="somename">
            <item>class</item>
            <item>const</item>
          </list>
          <list name="othername">
            <item>str</item>
            <include>types##ISO C++</include>
          </list>
          <contexts>
            <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" >
              <keyword attribute="Keyword" context="#stay" String="somename" />
              <keyword attribute="Keyword" context="#stay" String="othername" />
              <DetectChar attribute="String" context="string" char="&quot;" />
            </context>
            <context attribute="String" lineEndContext="#stay" name="string" >
              <DetectChar attribute="String" context="#pop" char="&quot;" />
            </context>
          </contexts>
          <itemDatas>
            <itemData name="Normal Text" defStyleNum="dsNormal" />
            <itemData name="Keyword" defStyleNum="dsKeyword" />
            <itemData name="String" defStyleNum="dsString" />
          </itemDatas>
        </highlighting>

Bir vurgu tanımının son kısmı ise isteğe bağlı olan `general` bölümüdür. Anahtar sözcükler, kod katlama, yorumlar, girintileme, boş satırlar ve yazım denetim üzerine bilgiler içerir.

  `comment` bölümü, tek bir satırlık bir yorumun hangi diziye konulduğunu tanımlar. Ayrıca, ek end özniteliği ile multiLine kullanarak çok satırlı bir yorum da tanımlayabilirsiniz. Bu, kullanıcı comment/uncomment ile ilişkili kısayola bastığı zaman kullanılır.

  `keywords` bölümü, anahtar sözcük listelerinin BÜYÜK/küçük harf duyarlı olup olmadığını tanımlar. Diğer öznitelikler daha sonra açıklanacaktır.

  `folding`, `emptyLines` ve `spellchecking` bölümleri genelde gerekli değildir ve daha sonra açıklanacaklardır.

      <general>
          <comments>
            <comment name="singleLine" start="#"/>
            <comment name="multiLine" start="###" end="###" region="CommentFolding"/>
          </comments>
          <keywords casesensitive="1"/>
          <folding indentationsensitive="0"/>
          <emptyLines>
            <emptyLine regexpr="\s+"/>
            <emptyLine regexpr="\s*#.*"/>
          </emptyLines>
          <spellchecking>
            <encoding char="á" string="\'a"/>
            <encoding char="à" string="\`a"/>
          </spellchecking>
        </general>
      </language>

#### Ayrıntılı Olarak Bölümler

Bu kısım; bağlamlar, itemData’lar, anahtar sözcükler, yorumlar, kod katlama ve girintileme ile ilgili tüm öznitelikleri açıklar.

`context` ögesi, `contexts` grubuna aittir. Bağlamın kendisi, vurgu sistemi bir satırın sonuna ulaştığında ne olması gerektiği gibi bağlama özgü kuralları tanımlar. Kullanılabilir özellikler şunlardır:

  `name`, bağlam adını belirtir. Kurallar, kuralın eşleşmesi durumunda geçiş yapılacak bağlamı belirtmek için bu adı kullanır.

  `attribute`, hiçbir kural eşleşmediğinde veya bir kural özniteliği belirtilmediğinde bir karakter için kullanılacak biçemi tanımlar. Sonraki durumda, kuralın context'inde belirtilen attribute kullanılır.

  `lineEndContext`, vurgu sistemi satırın sonuna geldiğinde geçiş yapılacak bağlamı tanımlar. Bu, ya başka bir bağlam adı, bağlamı değiştirmemek (bir şey yapmamak) için `#stay` veya bağlamdan çıkış yapmak için `#pop` olabilir. Örneğin, üç kez `#pop#pop#pop` yapmak veya hatta iki kez `#pop#pop!OtherContext` ve `OtherContext` adlı başka bağlama geçiş yapmak da olabilir. Ayrıca başka bir dil tanımına ait olan başka bir bağlama geçiş yapmak da olanaklıdır. Bu, `IncludeRules` kuralları ile aynı tarzdadır; &eg;, `SomeContext##JavaScript`. Bağlam anahtarları ek olarak içinde açıklanırlar. Öntanımlı: #stay.

  `lineEmptyContext`, boş bir satıra rastlandığındaki bağlamı tanımlar. Bağlam anahtarlarının terminolojisi daha önce lineEndContext'te açıklananla aynıdır. Öntanımlı: #stay.

  `fallthroughContext`, hiçbir kural eşleşmediğinde geçiş yapılacak sonraki bağlamı belirtir. Bağlam anahtarlarının terminolojisi daha önce lineEndContext'te açıklananla aynıdır. Öntanımlı: #stay.

  `fallthrough`, hiçbir kural eşleşmediğinde sistemin `fallthroughContext` içinde belirtilen geçiş yapacağı bağlamı belirtir. &kde; &frameworks; 5.62 sürümünden bu yana bu özniteliğin `fallthroughContext` namına kullanımdan kaldırıldığını aklınızdan çıkarmayın. Özellikle, `fallthroughContext` özniteliği varsa örtük olarak `fallthrough` değerinin true olacağı anlaşılır. Öntanımlı: false.

  `noIndentationBasedFolding`, bu bağlamdaki girintileme tabanlı katlamayı devre dışı bırakır. Girintileme tabanlı katlama etkinleştirilmemişse bu öznitelik bir işe yaramaz. Bu, general grubunun folding ögesinde tanımlanmıştır. Öntanımlı: false.

`itemData` ögesi, `itemDatas` grubundadır. Yazıtipi biçemini ve renklerini tanımlar. Böylece, kendi biçemlerinizi ve renklerinizi tanımlamanız olanaklıdır. Ancak biz yine de öntanımlı biçemlere sadık kalmanızı öneririz; böyle yaparsanız kullanıcı farklı dillerde de aynı renkleri görür. Bazen başka bir şansınız olmaz ve yazıtipi/renk özniteliklerini değiştirmeniz gerekebilir. name ve defStyleNum öznitelikleri zorunludur, diğerleri isteğe bağlıdır. Kullanılabilir öznitelikler şunlardır:

  `name`, itemData’nın adını ayarlar. Bağlamlar ve kurallar, attribute özniteliğinde bir itemData’ya başvurmak için bu adı kullanırlar.

  `defStyleNum`, hangi öntanımlı biçemin kullanılacağını tanımlar. Kullanılabilir öntanımlı biçemler ilerde daha ayrıntılı açıklanır.

  `color`, bir renk tanımlar. Geçerli biçimler '#rrggbb' veya '#rgb' dir.

  `selColor`, seçim rengini tanımlar.

  `italic` true ise metin yatık olur.

  `bold` true ise metin kalın olur.

  `underline` true ise metnin altı çizili olur.

  `strikeOut` true ise metnin üzeri çizili olur.

  `spellChecking` true ise metnin yazımı denetlenir.

`general` grubundaki `keywords` ögesi, anahtar sözcük özelliklerini tanımlar. Kullanılabilir öznitelikler şunlardır:

  `casesensitive`, true veya false olabilir. true ise tüm anahtar sözcükler BÜYÜK/küçük harf duyarlı olarak eşlenirler.

  `weakDeliminator`, sözcük sınırlandırıcısı olarak davranmayan bir karakterler listesidir. Örneğin, `'.'` noktası bir sözcük sınırlandırıcısıdır. `list` içindeki bir anahtar sözcüğün bir nokta içerdiğini varsayalım; bu, noktayı eğer yalnızca bir zayıf sınırlandırıcı olarak tanımlarsanız eşleştirir.

  `additionalDeliminator`, ek sınırlandırıcılar tanımlar.

  `wordWrapDeliminator`, ardından bir satır kaydırma oluşabilecek karakterleri tanımlar.

  Öntanımlı sınırlandırıcılar ve sözcük kaydırma sınırlandırıcıları şunlardır: `.():!+,-<=>%&*/;?[]^{|}~\`, boşluk (`' '`) ve sekmelendirici (`'\t'`).

`comments` grubundaki `comment` ögesi; Araçlar Yorum, Araçlar Yorumu Kapat ve Araçlar Yorumu Aç/Kapat seçenekleri için kullanılan yorum özelliklerini tanımlar. Kullanılabilir öznitelikler şunlardır:

  `name`, ya singleLine ya da multiLine olabilir. multiLine seçerseniz end ve region öznitelikleri zorunludur. singleLine seçerseniz isteğe bağlı olan position özniteliğini ekleyebilirsiniz.

  `start`, bir yorum başlatmak için kullanılan diziyi tanımlar. C++ için bu, çoklu satır yorumlarda "/*" olur. Bu öznitelik, multiLine ve singleLine türleri için zorunludur.

  `end`, bir yorum kapatmak için kullanılan diziyi tanımlar. C++ için bu, çoklu satır yorumlarda "*/" olur. Bu öznitelik, yalnızca multiLine türü yorumlar için kullanılabilir ve onun için zorunludur.

  `region`, katlanabilir çoklu satır yorumun adı olmalıdır. Kurallarınızda beginRegion="Comment" ... endRegion="Comment" olduğunu varsayalım; o zaman region="Comment" kullanmalısınız. Böylece, çoklu satır yorumun tüm metnini seçmeseniz bile yorumu kapatmak çalışır. Yalnızca, imleç çoklu satır yorumun içerisinde olmalıdır. Bu öznitelik, yalnızca multiLine türü için kullanılabilirdir.

  `position`, tek satırlık yorumun nereye eklendiğini tanımlar. Öntanımlı olarak, tek satırlık yorum satırın başında 0. sütuna koyulur; ancak position="afterwhitespace" kullanırsanız yorum, ilk boş olmayan karakterden sonra sağa doğru boşluk bırakılarak eklenir. Bu; örneğin, Python veya YAML gibi girintilemenin önemli olduğu diller için kullanışlıdır. Bu öznitelik isteğe bağlıdır ve tek olası değeri afterwhitespace'dir. Bu, yalnızca singleLine türü için kullanılabilirdir.

`general` grubundaki `folding` ögesi, kod katlama özelliklerini tanımlar. Kullanılabilir öznitelikler şunlardır:

  `indentationsensitive` true ise kod katlama imleyicileri girintileme tabanlı olarak eklenir. Örnek olarak yine Python verilebilir. Genelde öntanımlı olarak false olduğundan pek ayarlamanıza gerek olmaz.

`emptyLines` grubundaki `emptyLine` ögesi, hangi satırlara boş satır gibi davranılması gerektiğini tanımlar. Bu, `context` ögelerindeki lineEmptyContext özniteliğinin davranışının değiştirilmesine olanak tanır. Kullanılabilir öznitelikler şunlardır:

  `regexpr`, boş bir satır olarak davranılacak bir düzenli ifade tanımlar. Öntanımlı olarak, boş satırlar hiçbir karakter içermezler, dolayısıyla, bu ek boş satırlar ekler; örneğin, boşluklar içeren satırların da boş satırlar olarak kabul edilmesini istiyorsanız yararlıdır. Çoğu sözdizim tanımında bu özniteliği ayarlamanız gerekmez.

`spellchecking` grubundaki `encoding` ögesi, yazım denetimi için bir karakter kodlaması tanımlar. Kullanılabilir öznitelikler şunlardır:

  `char`, bir kodlanmış karakterdir.

  `string`, yazım denetimindeki char karakteri olarak kodlanacak karakterler dizisidir. Örneğin, LaTeX için `\"{A}` dizisi `Ä` karakterini temsil eder.

#### Kullanılabilir Öntanımlı Biçemler

Öntanımlı Biçemler daha önce halihazırda kısa bir özet olarak açıklammıştı: Öntanımlı biçemler, önceden tanımlanan yazıtipi ve renk biçemleridir.

Genel öntanımlı biçemler:

  Özel bir vurgulama gerekmediğinde `dsNormal`.

  `dsKeyword`, yerleşik dil anahtar sözcükleri.

  `dsFunction`, işlev çağrıları ve tanımları.

  `dsVariable`, kullanılabiliyorsa değişken adları (&eg;., PHP/Perl için $someVar).

  `dsControlFlow`; if, else, switch, break, return, yield, vb. denetim akışı anahtar sözcükleri.

  `dsOperator`, + - * / :: < > gibi işleçler.

  `dsBuiltIn`, yerleşik işlevler, sınıflar ve nesneler.

  `dsExtension`, ortak uzantılar; örneğin, C++ ve Python içindeki &Qt; sınıfları ve işlevler/makrolar.

  `dsPreprocessor`, önişlemci ifadeleri veya makro tanımları.

  `dsAttribute`, @override ve __declspec(...) gibi açıklamalar.

Dizi ile ilgili öntanımlı biçemler:

  `dsChar`, 'x' gibi tekli karakterler.

  `dsSpecialChar`, kaçışlar, yer değiştirmeler, veya düzenli ifade işleçleri gibi özel anlama sahip diziler.

  `dsString`, "merhaba dünya" gibi diziler.

  `dsVerbatimString`, Perl, CoffeeScript ve kabuklardaki ’raw \backlash’ ve Python’daki r’\raw’ gibi gerçek veya ham diziler.

  `dsSpecialString`, SQL, regex’ler, HERE belgeleri, &latex; matematik kipi, ...

  `dsImport`; modüllerin import, include, require ifadeleri.

Sayı ile ilgili öntanımlı biçemler:

  `dsDataType`; int, void, u64 gibi yerleşik veri türleri.

  `dsDecVal`, ondalık değerler.

  `dsBaseN`, 10 dışında tabana sahip değerler.

  `dsFloat`, kayan noktalı değerler.

  `dsConstant`, Pİ gibi yerleşik ve kullanıcı tanımlı sabitler.

Yorum ve belgelendirmeyle ilgili öntanımlı biçemler:

  `dsComment`, yorumlar.

  `dsDocumentation`, /** Belgelendirme yorumları */ veya """docstrings""".

  `dsAnnotation`, @param, @brief gibi belgelendirme komutları.

  `dsCommentVar`, yukarıdaki komutlarda kullanılan değişken adları; @param foobar’daki "foobar" gibi.

  `dsRegionMarker`; yorumlardaki //BEGIN, //END gibi bölge imleyicileri.

Diğer öntanımlı biçemler:

  `dsInformation`, doxygen içindeki @note gibi notlar ve ipuçları.

  `dsWarning`, doxygen’deki @warning gibi uyarılar.

  `dsAlert`; TODO, FIXME, XXXX gibi özel sözcükler.

  `dsError`, hata vurgulaması ve yanlış sözdizim.

  `dsOthers`, başka hiçbir şey uymadığında kullanılır.

### Vurgu Algılama Kuralları

Bu bölüm, sözdizim algılama kurallarını tanımlar.

Her kural, sınandıkları dizinin başlangıcındaki sıfır veya daha fazla karakterle eşleşebilir. Kural eşleşirse eşleşen karakterlere kural tarafından tanımlanan biçem veya öznitelik atanır ve bir kural, geçerli bağlamın değiştirilmesini isteyebilir.

Kural şuna benzer:

    <KuralAdı attribute="(tanımlayıcı)" context="(tanımlayıcı)" [kurala özel öznitelikler] />

attribute, eşleşen karakterlerle kullanılacak biçemi ada göre tanımlar ve context ise buradan sonra kullanılacak bağlamı tanımlar.

context, şöyle tanımlanabilir:

- identifier, bu diğer bağlamın adıdır.

- Bir order, işletkeye geçerli bağlamda kalmasını (`#stay`) veya dizide kullanılan bir önceki bağlama geri gitmesini (`#pop`) söyler. Boş veya var olmayan bir bağlam `#stay` ile eşdeğerdir.

  Daha çok adım geri gitmek için #pop anahtar sözcüğü yinelenebilir: `#pop#pop#pop`

- Bir ünlem işareti (!) ve tanımlayıcı tarafından izlenen bir sıra, işletkenin ilk sırayı izlemesini ve başka bir bağlama geçmesini söyler; örneğin, `#pop#pop!OtherContext`.

- Bir bağlam adı olan, iki adet kare tarafından izlenen (`##`) ve sonrasında başka bir tanımlayıcı olan bir tanımlayıcı, bir dil tanımının adıdır. Bu adlandırma, `IncludeRules` kurallarında kullanılana benzerdir ve başka bir sözdizim vurgulama tanımında kullanılan bağlama geçiş yapmanıza olanak tanır; örneğin, `SomeContext##JavaScript`.

Kurala özgü öznitelikler farklılık gösterir ve aşağıdaki bölümlerde açıklanmaktadır.

#### Ortak öznitelikler

Tüm kurallar aşağıdaki ortak özelliklere sahiptir ve `(ortak özellikler)` göründüğünde kullanılabilir. Tüm özellikler isteğe bağlıdır.

- attribute: Bir tanımlı ile itemData eşlemlenen öznitelik. Öntanımlı: context özniteliğinde tanımlanan attribute.

- context: Kural eşleşirse vurgulama sisteminin geçiş yapacağı bağlamı belirtir. Öntanımlı: #stay.

- beginRegion: Bir kod katlama bloku başlatın. Öntanımlı: Ayarsız.

- endRegion: Bir kod katlama blokunu kapatın. Öntanımlı: Ayarsız.

- lookAhead: true ise vurgulama sistemi eşleşmelerin uzunluğunu dikkate almaz.Öntanımlı: false.

- firstNonSpace: Dizi, satırdaki ilk boşluk olmayan karakterse eşleşir. Öntanımlı: false.

- column: Yalnızca sütun eşleşirse eşleşir. Öntanımlı: Ayarsız.

#### Devingen kurallar

Bazı kurallar, öntanımlı olarak false olan isteğe bağlı Boole türündeki `dynamic` özniteliğine izin verirler. Dynamic true ise bir kural bir regular expression ile eşleşen metni temsil eden yer tutucular kullanabilir. Bunlar kendi `string` veya `char` özniteliklerinde geçerli bağlama geçiş yaparlar. Bir `string`'de, %N yer tutucusu (N bir sayıdır), çağırdığı düzenli ifadede ilişkili olduğu N ile değiştirilir. Bir `char`'da, yer tutucu bir N sayısı olmalıdır ve çağıran düzenli ifadedeki ilişkili olduğu N ile değiştirilir. Bir kural bu özniteliğe izin veriyorsa bir (dynamic) içerir.

- dynamic: (true|false) olabilir.

`Nasıl çalışır:`

`RegExpr` kuallarının düzenli ifadelerinde, basit süslü ayraçlar arasındaki tüm metin `(PATTERN)` yakalanır ve anımsanır. Bu yakalamalar, geçiş yapıldıkları bağlama göre kullanılabilirler. Bu, `dynamic` özniteliği true iken ve %N (String içinde) veya N (char içinde) iken geçerlidir.

Bir `RegExpr` kuralında yakalanan metnin, `context` özniteliğinde belirtildiği üzere, yalnızca geçiş yapıldığı bağlam için depolandığını belirtmek önemlidir.

- Yakalamalar, hem devingen kurallar hem de düzenli ifadeler tarafından kullanılmayacaksa `yakalamayan gruplar` kullanılmalıdır: `(?:PATTERN)`

  `(?=PATTERN)`, `(?!PATTERN)` or `(?<=PATTERN)` gibi lookahead veya lookbehind grupları yakalanmazlar. Daha fazla bilgi için Düzenli İfadeler bölümüne bakın.

- Yakalama grupları, %N yerine \N kullanılarak aynı düzenli ifadede kullanılabilirler. Daha fazla bilgi için Düzenli İfadeler içindeki Eşleşen metni yakalamak (geriye başvurular) bölümüne bakın.

Örnek 1:

Bu basit örnekte, `=*` düzenli ifadesi ile eşleşen metin yakalanır ve devingen kuralda %1 yerine yerleştirilir. Bu, yorumun başlangıçta aynı sayıda `=` ile bitmesine olanak tanır. Şu tür metinlerle eşleştirilir: `[[ comment ]]`, `[=[ comment ]=]`veya `[=====[ comment ]=====]`.

Ek olarak, yakalamalar yalnızca geçilen Multi-line Comment bağlamında kullanılabilirdir.

    <context name="Normal" attribute="Normal Text" lineEndContext="#stay">
      <RegExpr context="Multi-line Comment" attribute="Comment" String="\[(=*)\[" beginRegion="RegionComment"/>
    </context>
    <context name="Multi-line Comment" attribute="Comment" lineEndContext="#stay">
      <StringDetect context="#pop" attribute="Comment" String="]%1]" dynamic="true" endRegion="RegionComment"/>
    </context>

Örnek 2:

Devingen kuralda; %1, `#+` ve %2, `&quot;+` ile eşleşen yakalamalara karşılık gelir. Bu, şu tür metinlerle eşleşir: `#etiket""""bağlamın içi""""#`.

Bu yakalamalar; OtherContext, FindEscapes veya SomeContext gibi başka bağlamlarda kullanılabilir olmayacaktır.

    <context name="SomeContext" attribute="Normal Text" lineEndContext="#stay">
      <RegExpr context="#pop!NamedString" attribute="String" String="(#+)(?:[\w-]|[^[:ascii:]])(&quot;+)"/>
    </context>
    <context name="NamedString" attribute="String" lineEndContext="#stay">
      <RegExpr context="#pop!OtherContext" attribute="String" String="%2(?:%1)?" dynamic="true"/>
      <DetectChar context="FindEscapes" attribute="Escape" char="\"/>
    </context>

Örnek 3:

Bu, şunun gibi metinlerle eşleşir: `Class::function<T>( ... )`.

    <context name="Normal" attribute="Normal Text" lineEndContext="#stay">
      <RegExpr context="FunctionName" lookAhead="true"
                  String="\b([a-zA-Z_][\w-]*)(::)([a-zA-Z_][\w-]*)(?:&lt;[\w\-\s]*&gt;)?(\()"/>
    </context>
    <context name="FunctionName" attribute="Normal Text" lineEndContext="#pop">
      <StringDetect context="#stay" attribute="Class" String="%1" dynamic="true"/>
      <StringDetect context="#stay" attribute="Operator" String="%2" dynamic="true"/>
      <StringDetect context="#stay" attribute="Function" String="%3" dynamic="true"/>
      <DetectChar context="#pop" attribute="Normal Text" char="4" dynamic="true"/>
    </context>

#### Yerel sınırlandırıcılar

Bazı kurallar, aynı adlı `keywords` etiketinin öznitelikleriyle birleştirilen `weakDeliminator` ve `additionalDeliminator` gibi isteğe bağlı özniteliklere izin verirler. Örneğin, `'%'`, `keywords`'ün zayıf bir sınırlandırıcısıysa yalnızca onun `additionalDeliminator` özniteliğine konularak bir sözcük sınırlandırıcısı olabilir. Ne zaman bir kural bu özniteliklere izin veriyorsa o bir (local deliminators) (yerel sınırlandırıcılar) içerir.

- weakDeliminator: Sözcük sınırlandırıcısı olarak davranmayan karakterlerin listesi.

- additionalDeliminator: Ek sınırlandırıcılar tanımlar.

#### Ayrıntılı Olarak Kurallar

DetectChar

  Tek bir belirli karakteri algılar. Genellikle kapatma tırnaklarını bulmak için kullanılır.

      <DetectChar char="(karakter)" (ortak öznitelikler) (devingen) />

  `char` özniteliği, eşleştirilecek karakteri tanımlar.

Detect2Chars

  Tanımlı bir sırada iki belirli karakteri algılar.

      <2KarakterAlgıla char="(karakter)" char1="(karakter)" (ortak öznitelikler) />

  `char` özniteliği, eşleştirilecek ilk karakteri, `char1` ise ikincisini tanımlar.

  Bu kural tarihsel nedenlerden dolayı buradadır; okunabilirlik açısından `StringDetect` kullanılması tercih nedenidir.

AnyChar

  Belirli bir karakter kümesinden tek bir karakteri algılar.

      <AnyChar String="(dizi)" (ortak öznitelikler) />

  `String` özniteliği, karakterlerin kümesini tanımlar.

StringDetect

  Kesin bir diziyi algılar.

      <StringDetect String="(dizi)" [insensitive="true|false"] (ortak öznitelikler) (devingen) />

  `String` özniteliği, eşleştirilecek diziyi tanımlar. `insensitive` özniteliği öntanımlı olarak false'tur ve dizi karşılaştırma işlevine geçirilir. Değer true ise duyarsız karşılaştırma kullanılır.

WordDetect

  Tam bir diziyi algılar; ancak sözcük başlangıcında ve sonunda `'.'` veya boşluk gibi sözcük sınırlarına gereksinim duyar. Bir düzenli ifade kapsamında `\b<string>\b` gibi düşünün; ancak `RegExpr` kuralından daha hızlıdır.

      <SözcükAlgıla String="(dizi)" [insensitive="true|false"] (ortak öznitelikler) (yerel sınırlandırıcılar) />

  `String` özniteliği, eşleştirilecek diziyi tanımlar. `insensitive` özniteliği öntanımlı olarak false'tur ve dizi karşılaştırma işlevine geçirilir. Değer true ise duyarsız karşılaştırma kullanılır.

  &kate; 3.5 (&kde; 4.5) sürümünden bu yana

RegExpr

  Bir düzenli ifade ile eşleşir.

      <RegExpr String="(dizi)" [insensitive="true|false"] [minimal="true|false"] (ortak öznitelikler) (devingen) />

  `String` özniteliği, düzenli ifadeyi tanımlar.

  `insensitive` öntanımlı olarak false'tur ve düzenli ifade işletkesine geçirilir.

  `minimal` öntanımlı olarak false'tur ve düzenli ifade işletkesine geçirilir.

  Kurallar her zaman geçerli dizinin başlangıcına göre eşleştirildiğinden, düzeltme işaretiyle (`^`) başlayan düzenli ifade, kuralın yalnızca satırın başlangıcına göre eşleştirilmesi gerektiğini belirtir.

  Bunlar hakkında daha fazla bilgi için Düzenli İfadeler bağlantısına bakın.

keyword

  Belirli bir listeden bir anahtar sözcüğü algılar.

      <anahtar sözcük String="(liste ado)" (ortak öznitelikler) (yerel sınırlandırıcılar) />

  `String` özniteliği, adıyla anahtar sözcük listesini tanımlar. Bu ada sahip bir liste var olmalıdır.

  Vurgulama sistemi, anahtar sözcük kurallarını oldukça eniyilenmiş bir biçimde işler. Bu, eşleştirilecek tüm anahtar sözcüklerin, örtük biçimde (öntanımlı sınırlandırıcılar) veya keywords etiketinin additionalDeliminator özelliğiyle açıkça belirtilmiş bir biçimde tanımlı sınırlandırıcılarla eşleştirilmiş olmasını bir gereklilik kılar.

  Eşleştirilecek bir anahtar sözcükte sınırlandırıcı bir karakter varsa bu ilgili karakter keywords etiketinin weakDeliminator özelliğine eklenmelidir. Sonrasında bu karakter tüm keyword kurallarında sınırlandırıcı kimliğini kaybeder. Aynı zamanda, keyword'ün weakDeliminator özniteliği de kullanılabilir; böylece bu değişiklik yalnızca bu kural için geçerli olur.

Int

  Bir tamsayıyı algılar (şu düzenli ifade gibi: `\b[0-9]+`).

      <Int (ortak öznitelikler) (yerel sınırlandırıcılar) />

  Bu kuralın belirli bir özniteliği yoktur.

Float

  Bir kayan noktalı sayıyı algılar (şu düzenli ifade gibi: `(\b[0-9]+\.[0-9]*|\.[0-9]+)([eE][-+]?[0-9]+)?`).

      <Float (ortak öznitelikler) (yerel sınırlandırıcılar) />

  Bu kuralın belirli bir özniteliği yoktur.

HlCOct

  Bir sekizlik noktalı sayı temsilini algılar (şu düzenli ifade gibi: `\b0[0-7]+`).

      <HlCOct (ortak öznitelikler) (yerel sınırlandırıcılar) />

  Bu kuralın belirli bir özniteliği yoktur.

HlCHex

  Bir onaltılık sayı temsilini algılar (şu düzenli ifade gibi: `\b0[xX][0-9a-fA-F]+`).

      <HlCHex (ortak öznitelikler) (yerel sınırlandırıcılar) />

  Bu kuralın belirli bir özniteliği yoktur.

HlCStringChar

  Kaçırılan bir karakteri algılar.

      <HlCStringChar (ortak öznitelikler) />

  Bu kuralın belirli bir özniteliği yoktur.

  Program kodunda sıkça kullanılan karakterlerin gerçek temsilleriyle eşleşir; örneğin, `\n` (yenisatır) veya `\t` (SEKME).

  Eğer bir ters eğik çizgi (`\`) sonrasında geliyorlarsa aşağıdaki karakterler eşleşir: `abefnrtv"'?\`. Ek olarak, kaçırılan onaltılık (örneğin, `\xff`) ve sekizlik (örneğin, `\033`) karakterler de eşleşir.

HlCChar

  Bir C karakterini algılar.

      <HlCChar (ortak öznitelikler) />

  Bu kuralın belirli bir özniteliği yoktur.

  Bir kesme işareti çifti içine alınmış C karakterleriyle eşleşir (Örnek: `'c'`). Kesme işaretleri normal bir karakter veya kaçırılmış bir karakter olabilir. Eşleştirilen kaçırılmış karakter dizileri hakkında daha fazla bilgi için HlCStringChar bölümüne bakın.

RangeDetect

  Tanımlı bir başlangıç ve bitiş karakterleri olan bir diziyi algılar.

      <RangeDetect char="(karakter)"  char1="(karakter)" (ortak öznitelikler) />

  `char`, erimi başlatan karakteri, `char1` ise bitiren karakteri tanımlar.

  Örneğin küçük alıntılanmış dizileri ve benzerlerini algılamak için kullanışlıdır; ancak vurgulama işletkesi her kerede bir satır üzerinde çalıştığından, bunun bir satır sonu boyunca uzanan dizileri bulmayacağını unutmayın.

LineContinue

  Satırın sonundaki belirli bir karakterle eşleşir.

      <LineContinue (ortak öznitelik) [char="\"] />

  `char` isteğe bağlı eşleştirilecek karakterdir, öntanımlısı ise ters eğik çizgidir (`'\'`). &kde; sürümünden bu yana eklidir.

  Bu kural, satırın sonunda bağlamı değiştirmek için kullanışlıdır. Bu, örneğin C/C++'da makroları veya dizileri sürdürmek için gereklidir.

IncludeRules

  Başka bir bağlamdan, dilden veya dosyadan kuralları içerir.

      <IncludeRules context="contextlink" [includeAttrib="true|false"] />

  `context` özniteliği, hangi bağlamın içerileceğini tanımlar.

  Basit bir diziyse tanımlı tüm kuralları geçerli bağlama içerir; örneğin:

      <IncludeRules context="anotherContext" />

  Dizi bir `##` içeriyorsa vurgu sistemi, verilen adda başka bir dilden bir bağlam arar; örneğin,

      <IncludeRules context="String##C++" />

  , C++ vurgulama tanımından String bağlamını içerir.

  `includeAttrib` özniteliği true ise hedef özniteliği kaynağın olanına değiştirin. Bu; örneğin dahil edilen bağlamla eşleşen metnin ana bilgisayar bağlamından farklı bir vurgu olması durumunda yorum yapma işleminin gerçekleştirilmesi için gereklidir.

DetectSpaces

  Boşlukları algılar.

      <DetectSpaces (ortak öznitelikler) />

  Bu kuralın belirli bir özniteliği yoktur.

  İleride birkaç boşluk olabileceğini biliyorsanız; örneğin, girintili çizgilerin başında bu kuralı kullanın. Bu kural, birden fazla kuralı sınamak ve eşleşme olmaması nedeniyle birer birer atlamak yerine, tüm boşlukları tek kerede atlayacaktır.

DetectIdentifier

  Tanımlayıcı dizilerini algılar (şu düzenli ifade gibi: `[a-zA-Z_][a-zA-Z0-9_]*`).

      <DetectIdentifier (ortak öznitelikler) />

  Bu kuralın belirli bir özniteliği yoktur.

  Birden çok kuralla sınamak ve eşleşme olmaması nedeniyle birer birer atlamak yerine, bir dizi sözcük karakterini aynı anda atlamak için bu kuralı kullanın.

#### İpuçları ve Kolaylıklar

Bağlam değiştirmenin nasıl çalıştığını anladıktan sonra vurgu tanımlarını yazmak kolay olacaktır. Hangi durumda hangi kuralı seçtiğinizi dikkatlice denetlemelisiniz. Düzenli ifadeler çok güçlüdür; ancak diğer kurallara göre yavaştırlar. Bu nedenle aşağıdaki ipuçlarını dikkate alabilirsiniz.

- Düzenli ifadelerin kullanımı kolaydır ancak çoğu zaman aynı sonucu elde etmenin çok daha hızlı başka bir yolu vardır. Satırdaki ilk karakter ise `'#'` karakterini eşleştirmek istediğinizi varsayalım. Düzenli ifade tabanlı bir çözüm şöyle görünecektir:

      <RegExpr attribute="Macro" context="macro" String="^\s*#" />

  Aynısını çok daha hızlıca şunu kullanarak elde edebilirsiniz:

      <DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" />

  . `'^#'` düzenli ifadesini eşleştirmek istiyorsanız hâlâ `column="0"` özniteliğiyle `DetectChar` kullanabilirsiniz. `column` özniteliği karakterleri sayar, bu nedenle, sekme karakteri yalnızca bir karakter olarak geçer.

- `RegExpr` kurallarında, `^PATTERN` dizgisi satırın başındaki metni eşleştirmek için kullanılacaksa `column="0"` özniteliğini kullanın. Geri kalan sütunlarda arama yapmayacağından bu, başarımı önemli ölçüde iyileştirir.

- Düzenli ifadelerde, yakalamalar aynı düzenli ifadeler içinde veya devingen kurallarda kullanılmayacaklarsa `(PATTERN)` yakalayan grupları yerine yakalamayan `(?:PATTERN)` gruplarını kullanın. Bu, gereksiz yere yakalamaları depolamayı önler.

- Karakterleri işlemeden bağlamlar arasında geçiş yapabilirsiniz. `*/` dizisiyle karşılaştığınızda bağlamı değiştirmek istediğinizi; ancak bu diziyi bir sonraki bağlamda işlemeniz gerektiğini varsayalım. Aşağıdaki kural eşleşecektir ve `lookAhead` özelliği, vurgulayıcının eşleşen diziyi bir sonraki bağlam için tutmasını sağlar.

      <StringDetect attribute="Comment" context="#pop" String="*/" lookAhead="true" />

- Çok sayıda boşluk oluşacağını biliyorsanız `DetectSpaces` kullanın.

- `'[a-zA-Z_]\w*'` düzenli ifadesi yerine `DetectIdentifier` kullanın.

- Olabildiğince öntanımlı biçemleri kullanın. Böylece, kullanıcı tanıdık bir ortam bulacaktır.

- Başkalarının karmaşık kuralları nasıl uyguladıklarını görmek için diğer &XML; dosyalarına bakın.

- `validatehl.sh mySyntax.xml` komutunu kullanarak tüm &XML; dosyalarını doğrulayabilirsiniz. `validatehl.sh` dosyası, her ikisi de Sözdizim Vurgulaması deposunda bulunabilen `language.xsd` dosyalarını kullanır.

- Karmaşık düzenli ifadeleri pek sık yineliyorsanız ENTITIES kullanabilirsiniz. Örnek:

      <?xml version="1.0" encoding="UTF-8"?>
      <!DOCTYPE language
      [
              <!ENTITY myref    "[A-Za-z_:][\w.:_-]*">
      ]>

  Şimdi, düzenli ifade yerine &myref; kullanabilirsiniz.

- Kate’de, yerleşik komut satırını (öntanımlı kısayolu `F7`) ve `reload-highlighting` komutunu kullanarak sözdizimleri yenileyebilirsiniz.

- Bir sözdizimi sınamak ve biçemi ve metnin her bir kısmıyla ilgili bölgeleri görüntülemek için `ksyntaxhighlighter6` (eski sürümlerde `kate-syntax-highlighter`) adlı komut satırı izlencesini kullanabilirsiniz.

  `ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp` sonucu.

  `ksyntaxhighlighter6 --output-format=ansi --syntax-trace=format test.cpp` sonucu.

  Daha çok seçenek için `ksyntaxhighlighter6 -h` kullanın.

## Renk Temalarıyla Çalışmak

### Genel Bakış

Renk temaları, metin düzenleme alanının ve sözdizim vurgulamanın renklerini tanımlar. Bir renk teması, aşağıdakileri içerir:

- Öntanımlı biçemler öznitelikleri ile sözdizim vurgulamada kullanılan metin biçemi. Örneğin, metin rengi ve seçili metin rengi.

- Metin düzenleme alanının arka planı; metin seçimi ve geçerli satır içerilmek üzere.

- Metin alanının simge kenarlıkları: Arka planları, ayırıcı çizgisi, satır numaraları, satır sözcük kaydırma imleyicileri, değiştirilen satır imleri ve kod katlama.

- Arama imleyicileri, girintileme ve sekme/boşluk çizgisi imleri, ayraç eşleştirme ve yazım denetimi gibi metin dekorasyonları.

- Yer imleri ve parçacıklar.

Kafa karışıklığını önlemek adına, aşağıdakiler kapsam dışında bırakılmıştır:

- Yazıtipi türü ve yazıtipi boyutu.

- Metin düzenleme uygulamasının renkleri; örneğin, sarma çubuğu haritası, menüler, sekme çubuğu, pencere rengi vb. &kate; veya &kdevelop; gibi &kde; uygulamalarında, bu renkler `&kde; &plasma; global renk şemalarında` tanımlıdır. Bu alana, &systemsettings; içindeki Renkler modülünde veya uygulamanın kendisinde Ayarlar Renk Şeması ögesinden ulaşılabilir.

C++ sözdizim vurgulamasında Esinti Açık ve Esinti Koyu renk temaları.

C++ sözdizim vurgulamasında Esinti Açık ve Esinti Koyu renk temaları.

### KSyntaxHighlighting Renk Temaları

KSyntaxHighlighting sözdizim vurgulaması işletkesi, `renk temalarını sağlayan ve yöneten` çatıdır. Bu, &kde; &frameworks;'ün bir parçasıdır ve &kate;, &kwrite;, &kile; ve &kdevelop; gibi &kde; metin düzenleyicilerinde kullanılır. Bağımlılıkları aşağıdaki gibidir:

Metin düzenleyicilerinde &kde; &frameworks; 5 kitaplıkları.

Metin düzenleyicilerinde &kde; &frameworks; 5 kitaplıkları.

KSyntaxHighlighting içinde, Kate düzenleyicisinin web sayfasının Renk Temaları bölümünde görüntülenen çeşitli yerleşik temalar vardır.

KTextEditor metin düzenleme işletkesi çatısı, renk temaları oluşturmak ve düzenlemek için içe/dışa aktarma araçları da içerilmek üzere bir kullanıcı arayüzü sağlar. Bu, renk temaları oluşturmanın ve düzenlemenin en basit yoludur; buna metin düzenleyicisinin Yapılandırma iletişim kutusundan erişebilirsiniz. Daha fazla ayrıntı için bölümüne bakın.

&kate; ayarlarında renk temalarını yönetmek için kullanılan arayüz.

&kate; ayarlarında renk temalarını yönetmek için kullanılan arayüz.

&kate; veya &kdevelop; gibi &kde; metin düzenleyicilerinde kullanılan KSyntaxHighlighting renk temaları, 10 Ekim 2020 tarihinde yayımlanan &kde; &frameworks; 5.75 sürümüyle kullanılmaya başlanmıştır. Öncesinde, &kate;'in kendi renk şemaları (KConfig tabanlı şema yapılandırması) kullanılıyordu; artık bunlar kullanılmıyor. Yine de, eski &kate; şemalarını KSyntaxHighlighting renk şemalarına dönüştürmek olanaklıdır. KSyntaxHighlighting deposunda, bu iş için kullanılan `utils/kateschema_to_theme_converter.py` betiği ve `utils/schema-converter/` izlencesi bulunur.

### Renk Temaları &JSON; Biçimi

#### Genel Bakış

Renk temaları, &JSON; biçimli dosyalarda `.theme` uzantısıyla depolanır.

KSyntaxHighlighting kaynak kodunda, yerleşik temaların &JSON; dosyaları `data/themes/` dizininde bulunur. Metin düzenleyicilerinde yerleşik temaların KSyntaxHighlighting kitaplığıyla derlendiğine dikkat edin; dolayısıyla, onlara erişmek ya kaynak kodundan ya da KTextEditor temalarını yönetmek üzere grafik arayüzden dışa aktarılarak olanaklıdır.

Dosya sisteminden, ek veya özel temaları kolaylıkla eklemek olanaklıdır. Kullanıcılar tarafından özelleştirilen tema dosyaları, kullanıcı klasörünüzdeki `org.kde.syntax-highlighting/themes/` dizininde bulunur; bu dizini ``qtpaths``--paths GenericDataLocation`` komutuyla bulabilirsiniz ve genellikle ``$HOME`/.local/share/` ve `/usr/share/` dizinleridir.

Flatpak ve Snap paketlerinde, yukarıdaki dizin işe yaramaz; çünkü her uygulamanın veri konumu farklıdır. Bir Flatpak uygulamasında, özel dosyaların konumu genellikle ``$HOME`/.var/app/flatpak-paketi-adı/data/org.kde.syntax-highlighting/themes/` ve bir Snap uygulamasında ise ``$HOME`/snap/snap-paketi-adı/current/.local/share/org.kde.syntax-highlighting/themes/` olarak kullanılır.

&Windows;'ta bu dosyalar genelde `C:\Users\user-name` `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes` olarak genişleyen %USERPROFILE% konumundadır.

Özet olarak, çoğu yapılandırmada özel tema dizinleri aşağıdaki gibidir:

Yerel kullanıcı için | ``$HOME`/.local/share/org.kde.syntax-highlighting/themes/`
Tüm kullanıcılar için | `/usr/share/org.kde.syntax-highlighting/themes/`
Flatpak paketleri için | ``$HOME`/.var/app/flatpak-paketi-adı/data/org.kde.syntax-highlighting/themes/`
Snap paketleri için | ``$HOME`/snap/snap-paketi-adı/current/.local/share/org.kde.syntax-highlighting/themes/`
&Windows; üzerinde | `%USERPROFILE%\AppData\Local\org.kde.syntax-highlighting\themes`

Aynı adlı birden çok tema dosyası varsa en yüksek `revision`'a (revizyona) sahip dosya yüklenir.

#### &JSON; Yapısı

Bir &JSON; dosyasının yapısı web sitelerinde açıklanmıştır. Temel olarak, bir &JSON; biçimi şunlardan oluşur:

- Adına nesneler dediğimiz ve `{ }` ile gruplanan anahtar/değer çiftleri koleksiyonları.

- Adına diziliş dediğimiz ve `[ ]` ile gruplanan sıralı değerler listeleri.

Bu yazıda, anahtar, değer, nesne ve diziliş ögeleri kullanılacaktır. &JSON; dosyalarıyla ilk tanışmanız ise onları anlamanın en kolay yolu aşağıdaki örneklere bakmaktır.

#### &JSON; Renk Teması Dosyalarının Ana Bölümleri

&JSON; renk teması dosyalarının kök nesnesi aşağıdaki şema anahtarlarını içerir:

- `metadata`: Zorunlu. Değer, temanın üst verisi olan bir nesnedir; örneğin, adı, revizyonu ve lisansı.

  Ayrıntılı bilgi için bölümüne bakın.

- `editor-colors`: Zorunlu. It is mandatory. Değer; arka plan, simge kenarlığı ve metin dekorasyonu gibi metin düzenleme alanının renklerine sahip bir nesnedir.

  Ayrıntılı bilgi için bölümüne bakın.

- `text-styles`: Zorunlu. Değer, sözdizim vurgulamanın öntanımlı metin biçemi öznitelikleriyle bir nesnedir. Her bir öznitelik; örneğin, kendi metin rengini, seçili metin rengini veya onun kalın veya yatık olup olmadığını tanımlar. Metin biçemlerine &XML; sözdizim vurgulama dosyalarından başvurulabilir.

  Ayrıntılı bilgi için bölümüne bakın.

- `custom-styles`: İsteğe bağlı. Belirli sözdizim vurgulama tanımlarının öznitelekleri için metin biçemlerini tanımları. Örneğin, `Python` veya `Markdown` vurgulama tanımlarında, `text-styles` içinde tanımlı metin biçemini geçersiz kılacak bir metin biçemi tanımlayabilirsiniz.

  Ayrıntılı bilgi için bölümüne bakın.

&JSON; dili yorumları desteklemez. Ancak, yorumlar yazmak için kök nesnede isteğe bağlı `_comments` anahtarını kullanabilirsiniz. Bu örneğin, önceden var olan bir temayı uyarlıyorsanız özgün deponun URL’sini buraya koyabilirsiniz. En pratik yolu, diziler içeren dizilişler kullanmaktır.

Aşağıda Esinti Açık teması için bir örnek dosyayı görebilirsiniz. Örneğin pek büyük olmasını engellemek için `editor-colors` ve `text-styles` nesnelerinin tüm gerekli anahtarları içermediğine dikkat edin. Esinti Açık temasının tam arşivini KSyntaxHighlighting deposunda bulabilirsiniz.

    {
        "_comments": [
            "Bu bir yorumdur.",
            "Bu tema bir başkasından uyarlanmışsa özgün deponun bağlantısını buraya koyun."
        ],
        "metadata": {
            "name" : "Esinti Açık",
            "revision" : 5,
            "copyright": [
                "SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
                "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
            ],
            "license": "SPDX-License-Identifier: MIT"
        },
        "editor-colors": {
            "BackgroundColor" : "#ffffff",
            "CodeFolding" : "#94caef",
            "BracketMatching" : "#ffff00",
            "CurrentLine" : "#f8f7f6",
            "IconBorder" : "#f0f0f0",
            "IndentationLine" : "#d2d2d2",
            "LineNumbers" : "#a0a0a0",
            "CurrentLineNumber" : "#1e1e1e",
            Diğer düzenleyici renk anahtarları...

        },
        "text-styles": {
            "Normal" : {
                "text-color" : "#1f1c1b",
                "selected-text-color" : "#ffffff",
                "bold" : false,
                "italic" : false,
                "underline" : false,
                "strike-through" : false
            },
            "Keyword" : {
                "text-color" : "#1f1c1b",
                "selected-text-color" : "#ffffff",
                "bold" : true
            },
            "Function" : {
                "text-color" : "#644a9b",
                "selected-text-color" : "#452886"
            },
            "Variable" : {
                "text-color" : "#0057ae",
                "selected-text-color" : "#00316e"
            },
            Diğer metin biçemi anahtarları...

        },
        "custom-styles": {
            "ISO C++": {
                "Data Type": {
                    "bold": true,
                    "selected-text-color": "#009183",
                    "text-color": "#00b5cf"
                },
                "Keyword": {
                    "text-color": "#6431b3"
                }
            },
            "YAML": {
                "Attribute": {
                    "selected-text-color": "#00b5cf",
                    "text-color": "#00b5cf"
                }
            }
        }
    }

#### Üst Veri

`metadata` anahtarının &JSON; nesnesi, tema üzerine aşağıdaki ilgili bilgiyi içerir. Bu nesnedeki anahtarlar aşağıdaki gibidir:

- `name`: Dilin adını ayarlayan bir dizidir. Daha sonra menülerde ve iletişim kutularında görünür. Bu, zorunludur.

- `revizyon`: Tema dosyasının geçerli revizyonunu belirten bir tamsayı'dır. Bir renk teması dosyasını güncellediğinizde bu sayıyı artırdığınızdan emin olun. Bu zorunludur.

- `license`: Temanın lisansını, standart SPDX lisans iletişim biçiminden alınan `SPDX-License-Identifier` tanımlayıcısını kullanarak belirten bir dizidir. İsteğe bağlıdır.

  SPDX lisans tanımlayıcılarının tam listesini buradan görebilirsiniz.

- `copyright`: Temanın telif hakkını, standart SPDX lisans iletişim biçiminden alınan `SPDX-License-Identifier` tanımlayıcısını kullanarak belirten bir diziler dizilişidir. İsteğe bağlıdır.

    "metadata": {
        "name" : "Esinti Açık",
        "revision" : 5,
        "copyright": [
            "SPDX-FileCopyrightText: 2016 Volker Krause <vkrause@kde.org>",
            "SPDX-FileCopyrightText: 2016 Dominik Haumann <dhaumann@kde.org>"
        ],
        "license": "SPDX-License-Identifier: MIT"
    }

### Ayrıntılarla Renkler

Bu bölüm, tüm kullanılabilir renk özniteliklerini ve ayarlarını ayrıntılandırır.

#### Düzenleyici Renkleri

Metin düzenleme alanı renklerine karşılık gelir.

&JSON; tema dosyasında, ilgili `editor-colors` anahtarının, her bir anahtarın metin düzenleyicisinin renk özniteliğine başvurduğu bir object değeri vardır. Burada, `tüm anahtarlar zorunludur`, değerleri ise #00B5CF gibi onaltılık renk değerlerine sahip `dizilerdir`.

KTextEditor tema yönetim arayüzünde, bu öznitelikler `Renkler` sekmesinde yapılandırılabilir.

Kullanılabilir anahtarlar aşağıdaki gibidir; &JSON; dosyasında kullanılan anahtarlar kalın ile, grafik arayüzde kullanılan adlar parantez içinde gösterilirler.

Düzenleyici Arka Plan Renkleri
  `BackgroundColor` (Metin Alanı)

    Bu, düzenleyici alanı için varsayılan arka plandır, düzenleyici alanındaki baskın renk olacaktır.

  `TextSelection` (Seçili Metin)

    Bu, seçili metnin arka planıdır.

  `CurrentLine` (Geçerli Satır)

    Geçerli satırın rengini ayarlayın. Bunu normal metin arka planından biraz farklı bir şekilde ayarlamak, odağın geçerli satırda kalmasına yardımcı olur.

  `SearchHighlight` (Arama Vurgusu)

    Son aramanızla eşleşen metnin rengini ayarlayın.

  `ReplaceHighlight` (Değiştirme Vurgusu)

    Son değiştirme işleminizle eşleşen metnin rengini ayarlayın.

Simge Kenarlığı
  `IconBorder` (Arka Plan Alanı)

    Bu renk, görüntülendiğinde düzenleyici görünümünün sol tarafındaki imleyiciler, satır numaraları ve katlama imleyicisi kenarlıkları için kullanılır.

  `LineNumbers` (Satır Numaraları)

    Bu renk, görüntülendiğinde görünümün sol tarafındaki satır numaralarını çizmek için kullanılır.

  `CurrentLineNumber` (Geçerli Satır Numarası)

    Bu renk, görüntülendiğinde görünümün sol tarafına geçerli satırın satır numarasını çizmek için kullanılır. Bunu LineNumbers'tan biraz farklı bir şekilde ayarlamak, geçerli satıra odaklanmaya yardımcı olur.

  `Separator` (Ayırıcı)

    Bu renk, simge kenarlığını metin alanının arka planından ayıran dikey çizgiyi çizmek için kullanılır.

  `WordWrapMarker` (Sözcük Kaydırma İmleyicisi)

    Bu renk, dikey olarak hizalandığında devingen olarak kaydırılan çizgilerin soluna bir desen çizmek ve durgun sözcük kaydırma imleyicisi için kullanılır.

  `CodeFolding` (Kod Katlama)

    Bu renk, bir belgenin solundaki kod katlama okuna tıkladığınızda katlanacak kod bölümünü vurgulamak için kullanılır. Daha fazla bilgi için kod katlama belgelendirmesine bakın.

  `ModifiedLines` (Değiştirilen Satırlar)

    Bu renk, değiştirilmiş ancak henüz kaydedilmemiş bir belgenin sol tarafındaki satırları vurgulamak için kullanılır. Daha fazla bilgi için bölümüne bakın.

  `SavedLines` (Kaydedilen Satırlar)

    Bu renk, bu oturumda değiştirilen ve kaydedilen belgenin sol tarafındaki satırları vurgulamak için kullanılır. Daha fazla bilgi için bölümüne bakın.

Metin Dekorasyonları
  `SpellChecking` (Yazım Yanlışı Satırı)

    Bu renk, yazım yanlışlarını belirtmek için kullanılır.

  `TabMarker` (Sekme ve Boşluk İmleyicileri)

    Bu renk, etkinleştirildiğinde beyaz alan göstergelerini çizmek için kullanılır.

  `IndentationLine` (Girintileme Satırı)

    Bu renk, bu özellik etkinse girintili blokların soluna bir çizgi çizmek için kullanılır.

  `BracketMatching` (Ayraç Vurgusu)

    Bu renk, eşleşen ayraçların arka planını çizmek için kullanılır.

İmleyici Renkleri
  `MarkBookmark` (Yer İmi)

    Bu renk, yer imlerini belirtmek için kullanılır. Bu rengin arka plana göre %​22 (ve geçerli çizgi için %​33) matlığa sahip olduğunu unutmayın.

  `MarkBreakpointActive` (Etkin Kesme Noktası)

    Bu renk, GDB eklentisi tarafından etkin bir kesme noktasını belirtmek için kullanılır. Bu rengin arka planının mat olduğuna dikkat edin. Daha fazla bilgi için GDB eklentisi belgelendirmesine bakın.

  `MarkBreakpointReached` (Ulaşılan Kesme Noktası)

    Bu renk GDB eklentisi tarafından hata ayıklama sırasında ulaştığınız bir kesme noktasını belirtmek için kullanılır. Bu rengin arka planının mat olduğuna dikkat edin. Daha fazla bilgi için GDB eklentisi belgelendirmesine bakın.

  `MarkBreakpointDisabled` (Devre Dışı Kesme Noktası)

    Bu renk, GDB eklentisi tarafından etkin olmayan bir kesme noktasını belirtmek için kullanılır. Bu rengin arka planının mat olduğuna dikkat edin. Daha fazla bilgi için GDB eklentisi belgelendirmesine bakın.

  `MarkExecution` (Yürütme)

    Bu renk, şu anda yürütülen satırdaki GDB eklentisi tarafından kullanılır. Bu rengin arka planının mat olduğuna dikkat edin. Daha fazla bilgi için GDB eklentisi belgelendirmesine bakın.

  `MarkWarning` (Uyarı)

    Bu renk, yapı eklentisi tarafından derleyici uyarısına neden olan bir satırı belirtmek için kullanılır. Bu rengin arka planının mat olduğuna dikkat edin. Daha fazla bilgi için yapı eklentisi belgelendirmesine bakın.

  `MarkError` (Hata)

    Bu renk, yapı eklentisi tarafından derleyici hatasına neden olan bir satırı belirtmek için kullanılır. Bu rengin arka planının mat olduğuna dikkat edin. Daha fazla bilgi için yapı eklentisi belgelendirmesine bakın.

Metin Şablonları ve Parçacıkları
  `TemplateBackground` (Arka Plan)

    Bu renk &kate; parçacıkları eklentisi tarafından bir parçacığın arka planını imlemek için kullanılır. Daha fazla bilgi için &kate; parçacıkları belgelendirmesine bakın.

  `TemplatePlaceholder` (Düzenlenebilir Yer Tutucu)

    Bu renk, &kate; parçacıklar eklentisi tarafından elle düzenlemek üzere tıklayabileceğiniz bir yer tutucuyu imlemek için kullanılır. Daha fazla bilgi için &kate; parçacıkları belgelendirmesine bakın.

  `TemplateFocusedPlaceholder` (Odaklı Düzenlenebilir Yer Tutucu)

    Bu renk, &kate; parçacıklar eklentisi tarafından şu anda düzenlediğiniz yer tutucuyu imlemek için kullanılır. Daha fazla bilgi için &kate; parçacıkları belgelendirmesine bakın.

  `TemplateReadOnlyPlaceholder` (Düzenlenemez Yer Tutucu)

    Bu renk, &kate; parçacıklar eklentisi tarafından düzenlenemez olan bir yer tutucuyu; örneğin, kendiliğinden doldurulan tutucular gibi, imlemek için kullanılır. Daha fazla bilgi için &kate; parçacıkları belgelendirmesine bakın.

#### Öntanımlı Metin Biçemleri

Öntanımlı metin biçemleri, vurgulanan metin biçemleri tarafından devralınır ve bu, düzenleyicinin metni çok tutarlı bir biçimde sunmasına olanak tanır; örneğin, yorum metni, KSyntaxHighlighting’in vurgulayabildiği hemen hemen tüm metin biçimlerinde aynı biçemi kullanır.

Bu metin biçemlerine, sözdizim vurgulama &XML; tanım dosyalarında kullanılan `öntanımlı biçemlerden` başvurulabilir; örneğin, Normal özniteliği, &XML; dosyalarındaki dsNormal özniteliğine ve DataType ise dsDataType'a eşdeğerdir. Daha fazla bilgi için sözdizim vurgulama belgelendirmesindeki bölümüne bakın.

Özellikle `Düzenleyici Renkleri` ile kombine edildiğinde iyi karşıtlık sağlayacak okunabilir renkler seçmeye dikkat edin. Daha fazla bilgi için bölümüne bakın.

&JSON; dosyasında, ilgili `text-styles` anahtarının değeri bir object'e sahiptir; burada her anahtar, sözdizim vurgulama tanımlarında kullanılanlara eşdeğer olan bir öntanımlı metin biçeminin adına karşılık gelir. Burada, zorunlu olan `kullanılabilir tüm metin biçemi anahtarları` aşağıda listelenmiştir.

    "text-styles": {
        "Normal" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : false,
            "italic" : false,
            "underline" : false,
            "strike-through" : false
        },
        "Keyword" : {
            "text-color" : "#1f1c1b",
            "selected-text-color" : "#ffffff",
            "bold" : true
        },
        "Function" : {
            "text-color" : "#644a9b",
            "selected-text-color" : "#452886"
        },
        Diğer metin biçemi anahtarları...
    }

Öntanımlı metin biçeminin her bir anahtarının bir &JSON; nesnesi olan değerleri vardır; buralarda; örneğin, color, bold, italic, vb. değerler belirtilirler. Bu anahtarlar aşağıda listelenmiştir:

  `text-color`: Metin renginin onaltılık bir renk kodunda olduğu bir dizidir. Bu anahtar/değer zorunludur.

  `selected-text-color`: Seçili olan metin renginin değeri genelde text-color ile aynıdır. Metin seçiliyken, arka plan, Düzenleyici Renkleri'nin TextSelection değeriyle belirlenir, bundan dolayı, metnin iyi bir karşıtlığa sahip olduğundan ve bu arka planla okunabilir olduğundan emin olun. Değer, onaltılık renk koduna sahip bir dizidir ve zorunludur.

  `bold`: Metnin kalın olup olmadığını belirten bir Boole değeridir. Bu anahtar isteğe bağlıdır, öntanımlı değer `false`'tur.

  `italic`: Metnin yatık olup olmadığını belirten bir Boole değeridir. Bu anahtar isteğe bağlıdır, öntanımlı değer `false`'tur.

  `underline`: Metnin altı çizili olup olmadığını belirten bir Boole değeridir. Bu anahtar isteğe bağlıdır, öntanımlı değer `false`'tur.

  `strike-through`: Metnin üzeri çizili olup olmadığını belirten bir Boole değeridir. Bu anahtar isteğe bağlıdır, öntanımlı değer `false`'tur.

  `background-color`: Metnin arka planının belirler; örneğin, yorumlardaki uyarılar için kullanılır. Değer, onaltılık renk koduna sahip bir dizidir. Bu anahtar isteğe bağlıdır ve öntanımlı olarak bir arka plan yoktur.

  `selected-background-color`: Metnin seçiliyken arka planının belirler. Değer, onaltılık renk koduna sahip bir dizidir. Bu anahtar isteğe bağlıdır ve öntanımlı olarak bir arka plan yoktur.

KTextEditor renk temalarını yönetmek için kullanılan arayüzde, bu öznitelikler `Öntanımlı Metin Biçemleri` sekmesinde değiştirilebilir. Biçem listesindeki ad, öge için yapılandırılan biçemi kullanır ve bir biçemi yapılandırırken size anında bir önizleme sağlar. Her biçem, ortak özelliklerin yanı sıra ön plan ve arka plan renklerini de seçmenize olanak tanır. Bir arka plan rengini kaldırmak için bağlam menüsünü kullanmak üzere sağ tıklayın.

Kullanılabilir metin biçemi anahtarları aşağıda listelenmiştir; &JSON; dosyasında kullanılan anahtarlar kalın ile, grafik arayüzde kullanılan adlar ise farklılarsa parantez içinde gösterilirler.

Normal Metin ve Kaynak Kodu

  `Normal`: Özel vurgulama olmadan normal metin ve kaynak kodu için öntanımlı metin biçemi.

  `Keyword`: Yerleşik dil anahtar sözcükleri için metin biçemi.

  `Function`: İşlev tanımları ve çağrıları için metin biçemi.

  `Variable`: Kullanılabiliyorsa değişkenler için metin biçemi. Örneğin, PHP/Perl değişkenleri genellikle bir `$` ile başlar, bundan dolayı `$foo` dizgisine uyan tüm tanımlayıcılar değişken olarak vurgulanırlar.

  `ControlFlow` (Denetim Akışı): if, then, else, return, switch, break, yield, continue, vb. gibi denetim akışı anahtar sözcükleri için metin biçemi.

  `Operator`: `+`, `-`, `*`, `/`, `%`, vb. gibi işleçler için metin biçemi.

  `BuiltIn` (Yerleşik): Yerleşik dil sınıfları, işlevleri ve nesneleri için metin biçemi.

  `Extension`: İyi bilinen uzantılar; örneğin, &Qt; sınıfları, C++ işlevleri/makroları vb. için metin biçemi.

  `Preprocessor`: Önişlemci ifadeleri veya makro tanımları için metin biçemi.

  `Attribute`: Bilgi notları veya işlevlerin veya nesnelerin öznitelikleri için metin biçemi; örneğin, Java’daki `@override` veya C++’daki `__declspec(...)` ve `__attribute__((...))`.

Sayılar, Türler ve Sabitler

  `DataType` (Veri Türü): int, char, float, void, u64, vb. gibi yerleşik veri türleri için metin biçemi.

  `DecVal` (Ondalık/Değer): Ondalık değerler için metin biçemi.

  `BaseN` (N Tabanlı Tamsayı): 10’dan başka bir tabanlı sayılar için metin biçemi.

  `Float` (Kayan Noktalı): Kayan noktalı sayılar için metin biçemi.

  `Constant`: Dil sabitleri ve kullanıcı tanımlı sabitler için metin biçemi; örneğin, Python’daki True, False, None veya C/C++’daki nullptr veya PI gibi matematik sabitleri.

Diziler ve Karakterler

  `Char` (Karakter): `'x'` gibi tekli karakterler için metin biçemi.

  `SpecialChar` (Özel Karakter): Dizilerde kaçırılan karakterler; örneğin, `esenlikler\n` ve değiştirmeler veya düzenli ifade işleçleri gibi özel anlamlı diğer karakterler için metin biçemi.

  `String`: `merhaba dünya` gibi diziler için metin biçemi.

  `VerbatimString` (Gerçek Dizi): Gerçek veya ham diziler için metin biçemi; örneğin, Perl, CoffeeScript belgelerindeki gibi `'ham \ters eğik çizgi'` veya Python veya HERE belgelerindeki `r'\ham'` gibi diziler.

  `SpecialString` (Özel Dizi): Özel diziler için metin biçemi; örneğin, ECMAScript düzenli ifadeleri, &latex; matematik kipi, SQL, vb.

  `Import` (Import’lar, Modüller, Include’lar): Include’lar, import’lar, modüller veya &latex; paketleri için metin biçemi.

Yorumlar ve Belgelendirme

  `Comment`: Normal yorumlar için metin biçemi.

  `Documentation`: API belgelendirmesini yansıtan yorumlar için metin biçemi; örneğin, `/** doxygen yorumları */` veya `"""docstrings"""`.

  `Annotation`: Yorumlardaki bilgi notları veya belgelendirme komutları için metin biçemi; örneğin, Doxygen veya JavaDoc için `@param`.

  `CommentVar` (Yorum Değişkeni): Yukarıdaki komutlarda bir yorumda kullanılan değişken adlarına başvuran metin biçemi; örneğin, Doxygen veya JavaDoc’ta `@param foobar` içindeki `foobar` gibi.

  `RegionMarker` (Bölge İmleyicisi): Genellikle yorumlarda `//BEGIN` ve `//END` ile tanımlanan bölge imleyicilerine yönelik metin biçemi.

  `Information`: Bilgi, notlar ve ipuçları için metin biçemi; örneğin, Doxygen `@note` anahtar sözcüğü gibi.

  `Warning`: Uyarılar için metin biçemi; örneğin, Doxygen’deki `@warning` anahtar sözcüğü gibi.

  `Alert`: Yorumlardaki özel sözcükler için metin biçemi; örneğin, `TODO`, `FIXME`, `XXXX` ve `WARNING`.

Çeşitli

  `Error`: Hata vurgulaması ve yanlış sözdizimi belirten metin biçemi.

  `Others`: Diğer öntanımlı biçemlerden hiçbiriyle eşleşmeyen öznitelikler için metin biçemi.

#### Özel Vurgulama Metin Biçemleri

Burada, önceki bölümde açıklanan `öntanımlı metin biçemini` geçersiz kılarak, belirli bir sözdizim vurgulama tanımı için metin biçemleri oluşturabilirsiniz.

&JSON; tema dosyasında bu, değeri her alt şema anahtarının `bir sözdizimi vurgulama tanımının adına` karşılık geldiği bir nesne olan `custom-styles` anahtarına karşılık gelir. Onun değeri, her bir anahtarın sözdizim tanımlama &XML; dosyasının `itemData` ögesinde tanımlı `biçem öznitelikleri adına` başvuran bir nesnedir. İlgili değer, text-color, selected-text-color, bold, italic, underline, strike-through, background-color ve selected-background-color anahtarlarıyla bir alt nesnedir. Bu alt nesne, bir önceki bölümde tanımlanmıştır. Bu değerlerin her biri isteğe bağlıdır; eğer yoklarsa `text-styles` içinde tanımlı biçem kümesi değerlendirilir.

Örneğin bu kod parçasında, ISO C++ sözdizim vurgulama tanımında Type Modifiers ve Standard Classes öznitelikleri için özel bir metin biçemi vardır. Karşılık gelen isocpp.xml &XML; dosyasında tanımlı Standard Classes özniteliği `BuiltIn` (veya dsBuiltIn) öntanımlı biçemini kullanır. Bu öznitelikte, yalnızca `text-color` değerinin yeni #6431b3 değeriyle üzerine yazılır.

    "custom-styles": {
        "ISO C++": {
            "Standard Classes": {
                "text-color": "#6431b3"
            },
            "Type Modifiers": {
                "bold": true,
                "selected-text-color": "#009183",
                "text-color": "#00b5cf"
            }
        }
    }

- Bu metin biçemlerinin, &XML; dosyalarını vurgulayan sözdizimde tanımlanan öznitelik adlarıyla ilişkili olduğunu dikkate almalısınız. Bir XML dosyası güncellenirse ve bazı nitelikler yeniden adlandırılırsa veya kaldırılırsa temada tanımlanan özel biçem artık geçerli olmayacaktır.

- Sözdizim vurgulama tanımları genellikle başka tanımları da içerir. Örneğin, QML vurgulayıcısı, JavaScript vurgulayıcısını da içerir; çünkü bunlar, vurgulamadaki işlevleri paylaşırlar.

KTextEditor tema yönetim arayüzünde, bu öznitelikler `Vurgulama Metin Biçemleri` sekmesinde yapılandırılabilir. Öntanımlı olarak düzenleyici, geçerli belgenin vurgulamasını önceden seçer. Pek çok vurgunun, biçem listesindeki gruplar tarafından temsil edilen diğer vurguları içerdiğini fark edeceksiniz. Örneğin, öne çıkanların çoğu Alert vurgusunu içe aktarır ve birçok kaynak kodu biçimi de Doxygen vurgusunu içe aktarır.

### Renk Temaları Grafik Arayüzü

Renk temaları oluşturmanın ve düzenlemenin en basit yolu, KTextEditor tarafından sağlanan Yapılandırma iletişim kutusunu kullanmaktır. Ona erişmek için düzenleyicinizdeki menü çubuğundan Ayarlar Uygulama Uygulamasını Yapılandır... yolunu izleyin. Bu, Yapılandır iletişim kutusunu getirir; burada kenar çubuğundaki Renk Temaları girdisini seçin.

&kate;'in renk teması yönetimini gösteren ayarlar iletişim kutusu.

&kate;'in renk teması yönetimini gösteren ayarlar iletişim kutusu.

Bu iletişim kutusunda, sahip olduğunuz tüm temalardaki tüm renkleri düzenleyebilir, yeni temalar oluşuturabilir/kopyalayabilir, onları silebilir, onları &JSON; biçimindeki bir `.theme` dosyasına dışa aktarabilir veya başka `.theme` dosyalarından içe aktarabilirsiniz. Her bir temanın metin renkleri ve biçemleri için ayarları vardır.

Öntanımlı olarak yerleşik temalar değiştirilemez. Bunu yapmak için bunları kopyalamanız ve onlara yeni bir ad vermeniz gerekir.

Bir temayı metin düzenleyicinizde kalıcı olarak kullanmak için öncelikle onu iletişim kutusunun altındaki Uygulama için öntanımlı tema bölümünde seçmeli ve Uygula veya Tamam düğmelerine basmalısınız. Öntanımlı olarak, `Kendiliğinden seçim` seçeneği etkindir; bu, metin düzenleme uygulamasında kullanılan &kde; &plasma; renk şemasına daha uygun bir temayı seçer. Şema açık veya koyuysa, genellikle sırasıyla Esinti Açık ve Esinti Koyu temaları arasında geçiş yapılır.

&kde; global renk şemasını &systemsettings; içindeki Renkler modülünde ayarlayabilirsiniz. Bunu, &kate; veya &kdevelop; gibi bazı uygulamalarda Ayarlar Renk Teması menüsünden bireysel olarak değiştirebilirsiniz.

#### Yeni bir tema oluştur

Yeni bir tema oluşturmak için öncelikle var olan bir tanesini kopyalamanız gerekir. Esinti Açık veya Esinti Koyu gibi temel olarak kullanmak istediğiniz var olan bir temayı seçin ve Kopyala'ya tıklayın. Daha sonra yeni tema için bir ad yazın.

Yerleşik veya saltokunur bir temayı değiştirmek istiyorsanız önce onu farklı bir adla kopyalamanız gerekir.

#### &JSON; tema dosyalarını içe/dışa aktar

Seçili bir temayı (yerleşik olanları da) bir &JSON; dosyasına `.theme` uzantısıyla Dışa Aktar düğmesini kullanarak dışa aktarabilirsiniz. Bu, dosyayı kaydetmek için bir iletişim kutusu açacaktır. Başka dış bir &JSON; dosyasından bir renk teması eklemek için İçe Aktar düğmesine basın ve iletişim kutusundan `.theme` dosyasını seçin.

- Yukarıda belirtildiği üzere, kullanıcı tanımlı tema dosyaları `org.kde.syntax-highlighting/themes/` dizininde depolanırlar. Bir tema oluşturduğunuzda veya kopyaladığınızda orada kendiliğinden oluşur. Ek olarak, bir tema içe aktarmak veya eklemek, bir `.theme` dosyasını bu dizine koymakla eşdeğerdir. KSyntaxHighlighting, bu dizinden renk teması dosyalarını kendiliğinden alır.

- Sizin tarafınızdan oluşturulan bir temayı yayımlamak istiyorsanız &JSON; dosyasının metadata nesnesine ilgili lisansı eklemeniz ve revizyon numarasını denetlemeniz önemlidir.

#### Renk temalarını düzenlemek

##### Renkler

Burada, metin düzenleme alanının renkleri düzenlenirken görebilirsiniz. Bunlar, bölümünde ayrıntılı olarak açıklanmıştır.

##### Öntanımlı Metin Biçemleri

Öntanımlı metin biçemleri, vurgulanan metin biçemleri tarafından devralınır ve bu, düzenleyicinin metni çok tutarlı bir biçimde sunmasına olanak tanır; örneğin, yorum metni, KSyntaxHighlighting’in vurgulayabildiği hemen hemen tüm metin biçimlerinde aynı biçemi kullanır.

Biçem listesindeki ad, öge için yapılandırılan biçemi kullanır ve bir biçemi yapılandırırken size anında bir önizleme sağlar.

Her biçem, ortak özelliklerin yanı sıra ön plan ve arka plan renklerini de seçmenize olanak tanır. Bir arka plan rengini kaldırmak için bağlam menüsünü kullanmak üzere sağ tıklayın.

Bu bölümün öznitelikleri bölümünde ayrıntılı olarak açıklanmıştır.

##### Metin Vurgulama Biçemleri

Burada, belirli bir vurgu tanımı tarafından kullanılan metin biçemlerini düzenleyebilirsiniz. Düzenleyici, geçerli belgenizin kullandığı vurguyu önceden seçer. Farklı bir vurgu üzerinde çalışmak için biçem listesinin üzerindeki Vurgula çoklu kutusundan birini seçin.

Biçem listesindeki ad, öge için yapılandırılan biçemi kullanır ve bir biçemi yapılandırırken size anında bir önizleme sağlar.

Her biçem, ortak özelliklerin yanı sıra ön plan ve arka plan renklerini de seçmenize olanak tanır. Bir arka plan rengini kaldırmak için bağlam menüsünü kullanmak üzere sağ tıklayın. Ayrıca bir biçemin, öge için kullanılan öntanımlı biçeme eşit olup olmadığını görebilir ve değilse bunu buna ayarlayabilirsiniz.

Pek çok vurgunun, biçem listesindeki gruplar tarafından temsil edilen diğer vurguları içerdiğini fark edeceksiniz. Örneğin, çoğu vurgu, Uyarı vurgusunu içe aktarır ve birçok kaynak kodu biçimi, Doxygen vurgusunu içe aktarır. Bu gruplardaki renkleri düzenlemek, yalnızca düzenlenen vurgu biçiminde kullanıldığında biçemleri etkiler.

### İpuçları ve Kolaylıklar

#### Metin Renklerinin Karşıtlığı

Renk temalarıyla çalışırken önemli bir konu, özellikle arka planla birlikte okumayı kolaylaştıracak bir metin karşıtlığı seçmektir.

`Kontrast` uygulaması bir renk karşıtlığı denetleyicisidir. Size metin rengi ve arka plan rengi kombinasyonlarının okunabilir ve erişilebilir olduğunu söyler; dolayısıyla bu, renk temaları oluşturmanıza yardımcı olacak mükemmel bir araçtır.

`Kontrast` uygulamasını from &kde; uygulamaları web sitesinden veya Flathub’daki Flatpak paketiyle indirebilirsiniz (yalnızca GNU/Linux).

GNOME `Contrast` uygulaması da benzer bir uygulamadır. Flathub’daki Flatpak paketiyle indirebilirsiniz (yalnızca GNU/Linux).

#### Sözdizim Vurgulamada Tutarlılık Önerileri

KSyntaxHighlighting, 300’den fazla sözdizimi vurgulama tanımı içerir, bu nedenle yeni temanızın tüm sözdizim vurgulama tanımlarında iyi göründüğünden emin olmanız idealdir. Yerleşik renk temaları, tüm sözdizim vurgulama tanımlarının doğru bir şekilde görüntülenmesini sağlamak için takip edilmesi önerilen (ancak zorunlu olmayan) aşağıdaki benzerliklere sahiptir:

- Keyword ve ControlFlow metin biçemleri için kalın metin kullanın.

- Alert ve RegionMarker dışındaki herhangi bir metin biçeminde arka plan rengi kullanmayın.

Çoğu sözdizim vurgulayıcı, öntanımlı Esinti Açık ve Esinti Koyu temalarında güzel görünmesi için tasarlanmıştır; dolayısıyla, tutarlılığı korumanın bir başka yolu da metin biçemlerinde benzer renkler kullanmaktır; örneğin, Preprocessor ve Others için yeşil; DataType ve Attribute için mavi veya Function için mor.

Bir tema oluştururken ve yayımlarken bu önerilerin zorunlu olmadığını unutmayın.

## &javascript; ile betik yazımı

&kappname; düzenleyici bileşeni, betik yazımı ile kolaylıkla genişletilebilir. Bunun içn kullanılan dil ECMAScript’tir (genellikle &javascript; olarak bilinir). &kappname; iki tür betiği destekler: Girintileme ve komut satırı betikleri.

### Girintileme Betikleri

Girintileme betikleri (aynı zamanda girintileyiciler olarak da bilinir) metin yazarken kaynak kodu kendiliğinden girintiler. Örnek olarak, Dönüş düğmesine bastıktan sonra girinti düzeyi genelde artar.

Aşağıdaki bölümlerde basit bir girintileyici için temel çerçevenin nasıl oluşturulacağı adım adım açıklanmaktadır. İlk adım olarak, yerel ana klasör olan `$`XDG_DATA_HOME`/katepart5/script/indentation` klasöründe yeni bir `*.js` dosyası oluşturun; &eg;, `javascript.js`. Burada, `XDG_DATA_HOME` çevre değişkeni genellikle `~/.local` veya `~/.local/share` olarak genişletilir.

&Windows;'ta bu dosyalar genelde `C:\\Users\\user` olarak genişleyen `%USERPROFILE%\AppData\Local\katepart5\script\indentation`. %USERPROFILE% konumundadır.

#### Girintileme Betiği Üstbilgisi

`javascript.js` dosyasının üstbilgisi, aşağıdaki gibi belgenin başına &JSON; olarak gömülür:

    var katescript = {
        "name": "JavaScript",
        "author": "Örnek Ad <örnek.ad@bir.adres.org>",
        "license": "BSD License",
        "revision": 1,
        "kate-version": "5.1",
        "required-syntax-style": "javascript",
        "indent-languages": ["javascript"],
        "priority": 0,
    }; // kate-script-header, dosyanın başında yorumsuz olmalıdır

Burada her giriş ayrıntılı olarak açıklanır:

- `name` [zorunlu]: Bu, Araçlar Girintileme menüsünde ve yapılandırma iletişim kutusunda görünen girintileyici adıdır.

- `author` [isteğe bağlı]: Yazarın adı ve iletişim bilgisi.

- `license` [isteğe bağlı]: Lisansın kısa adı; örneğin, BSD License veya LGPLv3.

- `revision` [zorunlu]: Betiğin revizyonu. Komut dosyasında her değişiklik yapıldığında bu sayının artırılması gerekir.

- `kate-version` [zorunlu]: Zorunlu en düşük &kappname; sürümü.

- `required-syntax-style` [isteğe bağlı]: Sözdizim vurgulama dosyalarında belirtilen `biçem` ile eşleşen gerekli sözdizim biçemi. Bu, belgedeki belirli vurgulama bilgilerine dayanan girintileyiciler için önemlidir. Gerekli bir sözdizim biçemi belirtilirse girintileyici yalnızca uygun vurgulayıcı etkin olduğunda kullanılabilir. Bu, girintileyicinin beklenen vurgulama şeması olmadan kullanılmasından kaynaklanan tanımsız davranışı önler. Örneğin, Ruby girintileyicisi bunu, `ruby.js` ve `ruby.xml` dosyalarında kullanır.

- `indent-languages` [isteğe bağlı]: Girintileyicinin düzgünce girintileyebildiği sözdizim biçemlerinin &JSON; dizilişi; &eg;: `["c++", "java"]`.

- `priority` [isteğe bağlı]: Vurgulanan belirli bir dosya için birden fazla girintileyici uygunsa öncelik, öntanımlı girintileyici olarak hangi girintileyicinin seçileceğine karar verir.

#### Girintileyici Kaynak Kodu

Üstbilgiyi belirledikten sonra bu bölüm girintileme betiği oluşturma işleminin nasıl çalıştığını açıklamaktadır. Gövdenin temel iskeleti şöyle görünür:

    // zorunlu katepart js kitaplıkları; &eg;, Range require ("range.js"); kullanıyorsanız range.js

    triggerCharacters = "{}/:;";
    function indent(line, indentWidth, ch)
    {
        // triggerCharacters global değişkeninde belirtilen her bir yenisatır (ch == ’\n’) ve tüm karakterler için çağrılır. AraçlarGirintilemeyi Biçimlendir, ch değişkeni boştur; demeli, ch == ’’.
        //
        // Ayrıca bakınız: Betik Yazımı API’si
        return -2;
    }

`indent()` işlevinin üç parametresi vardır:

- `line`: Girintilenmesi gereken satır

- `indentWidth`: Boşluk türünden girintileme genişliği

- `ch`: Ya bir yenisatır karakteri (`ch == ’\n’`) ya `triggerCharacters` içinde belirtilen tetikleyici karakter ya da kullanıcı Araçlar Girintilemeyi Biçimlendir eylemini çağırdıysa boş.

`indent()` işlevinin döndürdüğü değer, satırın nasıl girintileneceğini belirtir. Dönüş değeri basit bir tamsayıysa aşağıdaki gibi değerlendirilir:

- return value `-2`: Bir şey yapma

- return value `-1`: Girintilemeyi tut (önceki boş olmayan satırları arar)

- return value `0`: >=0 sayıları, boşluk türünden girintileme derinliğini belirtir

Alternatif olarak, iki ögeli bir diziliş döndürülebilir:

- `return [ indent, align ];`

Bu durumda ilk öge, yukarıdaki gibi özel değerlerle aynı anlama gelen girintileme derinliğidir. Ancak ikinci öge, hizalama sütununu temsil eden mutlak bir değerdir. Bu değer girinti değerinden yüksekse, fark, ilk parametrenin girintisinden sonra eklenecek boşluk sayısını temsil eder. Aksi halde ikinci sayı dikkate alınmaz. Girintileme için sekmelerin ve boşlukların kullanılmasına genellikle karma kip adı verilir.

Aşağıdaki örneğe ele alın: Girintileme için sekmelerin kullanıldığını ve sekme genişliğinin 4 olduğunu varsayalım. Burada, <tab> bir sekmeyi ve '.' bir boşluğu temsil eder:

    1: <tab><tab>foobar("merhaba",
    2: <tab><tab>......."dünya");

2. satırı girintilerken, `indent()` işlevi [8, 15] değerini döndürür. Sonuç olarak, 8. sütuna girinti yapmak için iki sekme eklenir ve ikinci parametreyi birincinin altına hizalamak için 7 boşluk eklenir, böylece dosya farklı bir sekme genişliğinde görüntülenirse hizalı kalır.

Öntanımlı bir &kde; kurulumu, &kappname; uygulamasını birkaç girintileyici ile kurar. Karşılık gelen &javascript; kaynak kodu `$`XDG_DATA_DIRS`/katepart5/script/indentation` konumunda bulunabilir.

&Windows;'ta bu dosyalar genelde `C:\\Users\\user` olarak genişleyen `%USERPROFILE%\AppData\Local\katepart5\script\indentation`. %USERPROFILE% konumundadır.

Bir girintileyici geliştirmek, değişikliklerin uygun şekilde davranıp davranmadığını görmek için betiklerin yeniden yüklenmesini gerektirir. Uygulamayı yeniden başlatmak yerine komut satırına geçin ve `reload-scripts` komutunu çağırın.

Yararlı betikler geliştiriyorsanız &kappname; uygulamasına katkıda bulunmayı düşünün. Geliştirmelerinizi posta listesine gönderin.

### Komut Satırı Betikleri

Herkesin gereksinimlerini karşılamak güç olsa da, &kappname;, yerleşik komut satırı ile tez metin manipülasyonunu sağlamak için küçük yardımcı araçlar sağlar. Örneğin, `sort` komutu bir betik olarak uygulanmıştır. Bu bölüm, &kappname; uygulamasını olabildiğince genişletmek için nasıl `*.js` dosyaları oluşturulacağını açıklar.

Komut satırı betikleri, girintileme betikleriyle aynı klasörde bulunurlar. İlk adım olarak, yerel ana klasör olan `$`XDG_DATA_HOME`/katepart5/script/commands` klasöründe yeni bir `*.js` dosyası oluşturun; &eg;, `izlencelerim.js`. Burada, `XDG_DATA_HOME` çevre değişkeni genellikle `~/.local` veya `~/.local/share` olarak genişletilir.

&Windows;'ta bu dosyalar genelde `C:\\Users\\user` olarak genişleyen `%USERPROFILE%\AppData\Local\katepart5\script\commands`. %USERPROFILE% konumundadır.

#### Komut Satırı Betik Üstbilgisi

`javascript.js` dosyasının üstbilgisi, aşağıdaki gibi belgenin başına &JSON; olarak gömülür:

    var katescript = {
        "author": "Örnek Ad <örnek.ad@bir.adres.org>",
        "license": "LGPLv2+",
        "revision": 1,
        "kate-version": "5.1",
        "functions": ["sort", "moveLinesDown"],
        "actions": [
            {   "function": "sort",
                "name": "Seçili Metni Sırala",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Satırları Aşağı Taşı",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    }; // kate-script-header, dosyanın başında yorumsuz olmalıdır

Burada her giriş ayrıntılı olarak açıklanır:

- `author` [isteğe bağlı]: Yazarın adı ve iletişim bilgisi.

- `license` [isteğe bağlı]: Lisansın kısa adı; örneğin, BSD License veya LGPLv3.

- `revision` [zorunlu]: Betiğin revizyonu. Komut dosyasında her değişiklik yapıldığında bu sayının artırılması gerekir.

- `kate-version` [zorunlu]: Zorunlu en düşük &kappname; sürümü.

- `functions` [zorunlu]: Betikteki komutların &JSON; dizilişi.

- `actions` [isteğe bağlı]: Uygulama menüsünde görünen eylemleri tanımlayan &JSON; nesnelerinin &JSON; dizilişi. Ayrıntılı bilgi, Kısayolları Bağıntılamak bölümünde sağlanmıştır.

`functions` değeri bir &JSON; dizilişi olduğundan, tek bir betik istediğiniz kadar komut satırı komutu içerebilir. Her bir işlev, &kappname; uygulamasının yerleşik komut satırından kullanılabilir.

#### Betik Kaynak Kodu

Üstbilgide belirtilen tüm işlevlerin betikte uygulanması gerekir. Örneğin, yukarıdaki örnekteki komut dosyasının `sort` ve `moveLinesDown` işlevlerini uygulaması gerekir. Tüm işlevler aşağıdaki sözdizime sahiptir:

    // zorunlu katepart js kitaplıkları; &eg;, Range require ("range.js"); kullanıyorsanız range.js

    function <name>(arg1, arg2, ...)
    {
        // ... uygulama, ayrıca bakınız: Betik Yazımı API’si
    }

Komut satırındaki argümanlar işleve `arg1`, `arg2`, vb. olarak geçirilirler. Her bir komut için belgelendirmek sağlamak istiyorsanız yalnızca '`help`' işlevini aşağıdaki gibi uygulayın:

    function help(cmd)
    {
        if (cmd == "sort") {
            return i18n("Seçili metni sıralayın.");
        } else if (cmd == "...") {
            // ...
        }
    }

Komut satırında `help sort` işlevini yürütmek, sonrasında bu yardım işlevini verilen komuta ayarlı `cmd` ile çağırır; &ie;, `cmd == "sort"`. &kappname; sonrasında döndürülen metni kullanıcıya belgelendirme olarak sunar. Dizileri başka dillere çevrilebilir yaptığınızdan emin olun.

Bir komut satırı betiği geliştirmek, değişikliklerin uygun şekilde davranıp davranmadığını görmek için betiklerin yeniden yüklenmesini gerektirir. Uygulamayı yeniden başlatmak yerine komut satırına geçin ve `reload-scripts` komutunu çağırın.

##### Kısayolları Bağıntılamak

Betiklerin uygulama menüsünden erişilebilir olmasını sağlamak ve kısayollar atamak için betiğin uygun bir betik başlığı sağlaması gerekir. Yukarıdaki örnekte, betik üstbilgisindeki aşağıdaki bölüm nedeniyle menüde hem `sort` hem de `moveLinesDown` işlevleri görünüyor:

    var katescript = {
        ...
        "actions": [
            {   "function": "sort",
                "name": "Seçili Metni Sırala",
                "icon": "",
                "category": "Editing",
                "interactive": "false"
            },
            {   "function": "moveLinesDown",
                "name": "Satırları Aşağı Taşı",
                "icon": "",
                "category": "Editing",
                "shortcut": "Ctrl+Shift+Down",
                "interactive": "false"
            }
        ]
    };

Tek bir eylem için olan alanlar aşağıdaki gibidir:

- `function` [zorunlu]: Araçlar Betikler menüsünde görünmesi gereken işlev.

- `name` [zorunlu]: Betikler menüsünde görünen metin.

- `icon` [isteğe bağlı]: Menüde metnin yanında görünen simge. Burada tüm &kde; simgeleri adları kullanılabilir.

- `category` [isteğe bağlı]: Bir kategori belirtilirse betik bir alt menüde görünür.

- `shortcut` [isteğe bağlı]: Burada verilen kısayol, öntanımlı kısayoldur. Örnek: `Kontrol+Seçenek+T`. Daha fazla ayrıntı için &Qt; belgelendirmesine bakın.

- `interactive` [isteğe bağlı]: Betiğin komut satırında kullanıcı girdisi bekleyip beklemediği. Bunu, `true` olarak ayarlayın.

Yararlı betikler geliştiriyorsanız &kappname; uygulamasına katkıda bulunmayı düşünün. Geliştirmelerinizi posta listesine gönderin.

### Betik Yazımı API’si

Burada sunulan betik yazımı API’si, tüm betikler için kullanılabilirdir; &ie;, girintileme betikleri ve komut satırı betikleri. `Cursor` ve `Range` sınıfları, `$`XDG_DATA_DIRS`/katepart5/libraries` içindeki kitaplık dosyaları tarafından sağlanırlar. `Document` veya `View` işlevlerinden bazılarını kullanması gereken bu API’yi betiğinizde kullanmak istiyorsanız şunu kullanarak gerekli kitaplığı içerin:

    // zorunlu katepart js kitaplıkları; &eg;, Range require ("range.js"); kullanıyorsanız range.js
    require ("range.js");

Standart betik yazımı API’sini kendi işlevleriniz ve prototiplerinizle genişletmek istiyorsanız yalnızca &kde;’nin yerel yapılandırma klasörü olan `$`XDG_DATA_HOME`/katepart5/libraries` içinde yeni bir dosya oluşturun ve onu betiğinizde şunu kullanarak içerin:

    require ("benimbetiğiminadıburaya.js");

&Windows;'ta bu dosyalar genelde `C:\\Users\\user` olarak genişleyen `%USERPROFILE%\AppData\Local\katepart5\libraries`. %USERPROFILE% konumundadır.

`Cursor` veya `Range` gibi var olan prototipleri genişletmek istiyorsanız tavsiye edilen yol global `*.js` dosyalarını değiştirmek değildir. Bunun yerine, &javascript; içindeki `Cursor` prototipini `cursor.js` betiğinizde `require` ile içerildikten sonra değiştirin.

#### İmleçler ve Erimler

&kappname; bir metin düzenleyici olduğundan, tüm betik oluşturma API’si olabildiğince imleçlere ve erimlere dayanır. İmleç, belgedeki bir metin konumunu temsil eden basit bir `(satır, sütun)` demettir. Erim, metni başlangıç imleç konumundan bitiş imleç konumuna kadar yayar. API sonraki bölümlerde ayrıntılı olarak açıklanmaktadır.

##### İmleç Prototipi

    Cursor();

  Yapıcı. `(0, 0)` konumunda bir imleç döndürür.

  Örnek: `var cursor = new Cursor();`

    Cursor(int satır, int sütun);

  Yapıcı. Belirli bir konumda (satır, sütun) bir imleç döndürür.

  Örnek: `var cursor = new Cursor(3, 42);`

    Cursor(Cursor diğer);

  Yapıcıyı kopyala. diğer imlecinin bir kopyasını döndürür.

  Örnek: `var copy = new Cursor(other);`

    Cursor Cursor.clone();

  İmlecin bir klonunu döndürür.

  Örnek: `var clone = cursor.clone();`

    Cursor.setPosition(int satır, int sütun);

  İmleç konumunu satır ve sütun olarak ayarlar.

  Eklendiği sürüm: &kde; 4.11

    bool Cursor.isValid();

  İmlecin geçerli olup olmadığını denetler. Satır ve/veya sütun `-1` olarak ayarlanırsa imleç geçersizdir.

  Örnek: `var valid = cursor.isValid();`

    Cursor Cursor.invalid();

  `(-1, -1)` konumunda yeni geçersiz bir imleç döndürür.

  Örnek: `var invalidCursor = cursor.invalid();`

    int Cursor.compareTo(Cursor diğer);

  Bu imleci diğer imleç ile karşılaştırır. İmleç,

  - diğer imlecinden önce konumlandırılmışsa `-1`,

  - her iki imleç de eşitse `0` ve

  - bu imleç other imlecinden önce geliyorsa `+1` döndürür.

    bool Cursor.equals(Cursor diğer);

  Bu imleç ve diğer imleç eşitse `true`, aksi takdirde `false` döndürür.

    String Cursor.toString();

  İmleci, `Cursor(satır, sütun)` biçiminde bir dizi olarak döndürür.

##### Erim Prototipi

    Range();

  Yapıcı. `new Range()` çağırmak, (0, 0) - (0, 0) konumunda bir erim döndürür.

    Range(Cursor başlangıç, Cursor bitiş);

  Yapıcı. `new Range(başlangıç, bitiş)` çağırmak, (başlangıç, bitiş) erimini döndürür.

    Range(int başlangıçSatırı, int başlangıçSütunu, int bitişSatırı, int bitişSütunu);

  Yapıcı. `new Range(başlangıçSatırı, başlangıçSütunu, bitişSatırı, bitişSütunu)` çağırmak, (başlangıçSatırı, başlangıçSütunu) değerlerini (bitişSatırı, bitişSütunu) olarak döndürür.

    Range(Range diğer);

  Yapıcıyı kopyala. diğer eriminin bir kopyasını döndürür.

    Range Range.clone();

  Erimin bir klonunu döndürür.

  Örnek: `var clone = range.clone();`

    bool Range.isEmpty();

  Başlangıç ve bitiş imleçleri eşitse `true` döndürür.

  Örnek: `var empty = range.isEmpty();`

  Eklendiği sürüm: &kde; 4.11

    bool Range.isValid();

  Hem başlangıç hem bitiş imleçleri eşitse `true`, aksi takdirde `false` döndürür.

  Örnek: `var valid = range.isValid();`

    Range Range.invalid();

  (-1, -1) ile (-1, -1) arasındaki erimi döndürür.

    bool Range.contains(Cursor imleç);

  Eğer bu erim imleç konumunu içeriyorsa `true`, aksi takdirde `false` döndürür.

    bool Range.contains(Range diğer);

  Eğer bu erim diğer erimini içeriyorsa `true`, aksi takdirde `false` döndürür.

    bool Range.containsColumn(int sütun);

  sütun, yarı açık `[başlangıç.sütun, bitiş.sütun)` aralığındaysa `true`, aksi takdirde `false` döndürür.

    bool Range.containsLine(int satır);

  satır, yarı açık `[başlangıç.satır, bitiş.satır)` aralığındaysa `true`, aksi takdirde `false` döndürür.

    bool Range.overlaps(Range diğer);

  Bu erim ve diğer erimi ortak bir bölge paylaşıyorlarsa `true`, aksi takdirde `false` döndürür.

    bool Range.overlapsLine(int satır);

  satır, `[başlangıç.satır, bitiş.satır)` aralığındaysa `true`, aksi takdirde `false` döndürür.

    bool Range.overlapsColumn(int sütun);

  sütun, `[başlangıç.sütun, bitiş.sütun)` aralığındaysa `true`, aksi takdirde `false` döndürür.

    bool Range.onSingleLine();

  Erim aynı satırda başlıyor ve bitiyorsa `true` döndürür; &ie;, Range.start.line == Range.end.line ise.

  Eklendiği sürüm: &kde; 4.9

    bool Range.equals(Range diğer);

  Eğer bu erim ve diğer erimi eşitse `true`, aksi takdirde `false` döndürür.

    String Range.toString();

  Erimi, `Cursor(satır, sütun)` biçiminde bir dizi olarak döndürür.

#### Global İşlevler

Bu bölüm, tüm global işlevleri listeler.

##### Dosyaları Okumak ve İçermek

    String read(String dosya);

  Verilen dosya'yı `katepart5/script/files` dizinine göreceli olarak arar ve içeriğini bir dizi olarak döndürür.

    void require(String dosya);

  Verilen dosya'yı `katepart5/script/libraries` dizinine göreceli olarak arar ve onu değerlendirir. `require`, aynı dosya'nın birden çok içerilmesine karşı korumalıdır.

  Eklendiği sürüm: &kde; 4.10

##### Hata Ayıklama

    void debug(String metin);

  metin'i, uygulamayı başlatan konsolda `stdout`'a yazdırır.

##### Çeviri

Tam yerelleştirmeyi desteklemek için betiklerdeki dizileri çevirmek üzere birkaç işlev bulunur; bunlar, `i18n`, `i18nc`, `i18np` ve `i18ncp` olarak geçer. Bunlar kesin olarak &kde;'nin çeviri işlevleri gibi davranırlar.

Çeviri işlevleri, sarılmış dizileri &kde;'nin çeviri sistemi aracılığıyla uygulamada kullanılan dile çevirir. Resmi &kappname; kaynaklarında geliştirilen komut dosyalarındaki dizeler otomatik olarak çıkarılır ve çevrilebilir. Başka bir deyişle, bir &kappname; geliştiricisi olarak ileti çıkarma ve çeviri ile uğraşmanıza gerek yoktur. Bununla birlikte, çevirinin yalnızca &kde; altyapısı içinde çalıştığını, yani &kde; dışında geliştirilen 3. taraf betiklerdeki yeni dizilerin çevrilmediğini de belirtmek gerekir. Bu nedenle, doğru çevirinin olabilmesi için lütfen betiklerinizle &kate;'e katkıda bulunmayı düşünün.

    void i18n(String metin, arg1, ...);

  metin'i, uygulama tarafından kullanılan dile çevirir. arg1, ..., argümanları isteğe bağlıdır ve `%1`, `%2`, gibi yer tutucuları değiştirmede kullanılırlar.

    void i18nc(String bağlam, String metin, arg1, ...);

  metin'i, uygulama tarafından kullanılan dile çevirir. Ek olarak, bağlam metni çevirmenlere görünür, böylece daha iyi bir çeviri sağlayabilirler. arg1, ..., argümanları isteğe bağlıdır ve `%1`, `%2`, gibi yer tutucuları değiştirmede kullanılırlar.

    void i18np(String tekil, String çoğul, int sayı, arg1, ...);

  tekil veya çoğul varyantları, verilen sayı'ya bağlı olarak uygulama tarafından kullanılan dile çevirir. arg1, ..., argümanları isteğe bağlıdır ve `%1`, `%2`, gibi yer tutucuları değiştirmede kullanılırlar.

    void i18ncp(String bağlam, String tekil, String çoğul, int sayı, arg1, ...);

  tekil veya çoğul varyantları, verilen sayı'ya bağlı olarak uygulama tarafından kullanılan dile çevirir. Ek olarak, bağlam metni çevirmenlere görünür, böylece daha iyi bir çeviri sağlayabilirler. arg1, ..., argümanları isteğe bağlıdır ve `%1`, `%2`, gibi yer tutucuları değiştirmede kullanılırlar.

#### Görünüm API’si

Ne zaman bir betik yürütülürse geçerli etkin düzenleyici görünümünü temsil eden bir `view` global değişkeni vardır. Tüm kullanılabilir View işlevleri aşağıda listelenmiştir.

    void view.copy()

  `[ ] Metin seçilmeden çağrılırsa geçerli satırı kes/kopyala` ayarlıysa bir seçim varken seçimi kopyala, aksi takdirde geçerli satırı kopyala.

  Eklendiği sürüm: &kde-frameworks; 5.79

    void view.cut()

  `[ ] Metin seçilmeden çağrılırsa geçerli satırı kes/kopyala` ayarlıysa bir seçim varken seçimi kes, aksi takdirde geçerli satırı kes.

  Eklendiği sürüm: &kde-frameworks; 5.79

    void view.paste()

  Pano içeriğini yapıştır.

  Eklendiği sürüm: &kde-frameworks; 5.79

    Cursor view.cursorPosition()

  Görünümdeki geçerli imleç konumunu döndürür.

    void view.setCursorPosition(int satır, int sütun);
    void view.setCursorPosition(Cursor imleç);

  Geçerli imleç konumunu ya (satır, sütun) ya da verilen imlece ayarla.

    Cursor view.virtualCursorPosition();

  Geçerli sekme genişliğine bağlı olarak her sekmenin karşılık gelen boşluk miktarını saydığı sanal imleç konumunu döndürür.

    void view.setVirtualCursorPosition(int satır, int sütun);
    void view.setVirtualCursorPosition(Cursor imleç);

  Geçerli sanal imleç konumunu (satır, sütun) veya verilen imleç olarak ayarlayın.

    String view.selectedText();

  Seçilen metni döndürür. Hiçbir metin seçilmezse döndürülen dizi boştur.

    bool view.hasSelection();

  Görünümde seçili metin varsa `true` değerini, aksi takdirde `false` değerini döndürür.

    Range view.selection();

  Seçili metin erimini döndürür. Seçili metin yoksa döndürülen erim geçersizdir.

    void view.setSelection(Range erim);

  Seçili metni verilen erime ayarla.

    void view.removeSelectedText();

  Seçili metni kaldır. Görünümde seçili metin yoksa bu hiçbir şey yapmaz.

    void view.selectAll();

  Belgedeki tüm metni seçer.

    void view.clearSelection();

  Metni kaldırmadan metin seçimini temizler.

    void view.setBlockSelection(bool on);

  Blok seçim kipini açar/kapatır.

    bool view.blockSelection();

  Blok seçim kipi açıksa `true`, aksi takdirde `false` döndürür.

    void view.align(Range erim);

  Geçerli girintileme ayarlarına göre erim'i düzgünce yeniden girintile.

    void view.alignOn(Range erim, String dizgi = "");

  Düzenli ifade dizgi verdiği sütundaki erim'deki satırları hizalar. Boş bir dizgi ile öntanımlı olarak ilk boş olmayan karaktere hizalanır. Dizginin bir yakalaması varsa yakalanan eşleşmeye girintili olacaktır.

  Örnekler:

  `view.alignOn(document.documentRange(), '-');`, tümünü aynı sütunda hizalamak için her satırın ilk `-` satırından önce boşluk ekler.

  `view.alignOn(document.documentRange(), ':\\s+(.)');`, tümünü aynı sütunda hizalamak için iki nokta üst üsteden sonra oluşan ilk boş olmayan karakterden önce boşluk ekler.

    object view.executeCommand(String komut,
                               String argümanlar,
                               Range erim);

  komut komut satırı komutunu isteğe bağlı argümanlar ve erim ile yürütür. Döndürülen nesne'nin komut yürütmesinin başarılı olup olmadığını söyleyen bir object.ok Boole değeri vardır. Bir hata durumunda, object.status bir hata iletisi içerir.

  Eklendiği sürüm: &kde-frameworks; 5.50

    Range view.searchText(Range erim,
                          String dizgi,
                          bool backwards = false);

  erim'de dizgi'nin ilk oluşunu ara ve eşleşen erimi döndür. İsteğe bağlı Boole değeri backwards `true` olarak ayarlanırsa arama geriye doğru yapılır.

  dizgi, erim'de bulunamazsa döndürülen erim geçersizdir (bkz. Range.isValid()).

  Eklendiği sürüm: &kde-frameworks; 5.97

#### Belge API’si

Ne zaman bir betik yürütülürse geçerli etkin belgeyi temsil eden bir `document` global değişkeni vardır. Tüm kullanılabilir Document işlevlerinin bir listesini aşağıda bulabilirsiniz.

    String document.fileName();

  Kaydedilmemiş metin arabellekleri için belgenin dosya adını veya boş bir diziyi döndürür.

    String document.url();

  Belgenin tam URL’sini veya kaydedilmemiş metin arabellekleri için boş bir diziyi döndürür.

    String document.mimeType();

  Belgenin &MIME; türünü veya uygun &MIME; türü bulunamazsa `application/octet-stream` &MIME; türünü döndürür.

    String document.encoding();

  Dosyayı kaydetmek için kullanılan geçerli kodlamayı döndürür.

    String document.highlightingMode();

  Tüm belge için kullanılan global vurgulama kipini döndürür.

    String document.highlightingModeAt(Cursor konum);

  Belgedeki belirli konumda kullanılan vurgulama kipini döndürür.

    Array document.embeddedHighlightingModes();

  Bu belgeye gömülü bir dizi vurgulama modunu döndürür.

    bool document.isModified();

  Belgede kaydedilmemiş değişiklikler varsa `true`, aksi takdirde `false` döndürür.

    String document.text();

  Belgenin tüm içeriğini tek bir metin dizisinde döndürür. Yeni satırlar, `\n` yenisatır karakteriyle işaretlenir.

    String document.text(int satırdan, int sütundan, int satıra, int sütuna);
    String document.text(Cursor şuradan, Cursor şuraya);
    String document.text(Range erim);

  Verilen erimdeki metni döndürür. Kaynak kodunun daha iyi okunabilmesi için imleç ve aralık tabanlı sürümün kullanılması önerilir.

    String document.line(int satır);

  Verilen metin satırını dizi olarak döndürür. İstenen satır erim dışıysa dizi boştur.

    String document.wordAt(int satır, int sütun);
    String document.wordAt(Cursor imleç);

  Verilen imleç konumundaki sözcüğü döndürür.

    Range document.wordRangeAt(int satır, int sütun);
    Range document.wordRangeAt(Cursor imleç);

  Verilen imleç konumundaki sözcüğün erimini döndürür. Metin konumu bir satırın sonundan sonraysa döndürülen erim geçersizdir (bkz. Range.isValid()). Verilen imleçte sözcük yoksa boş bir erim döndürülür.

  Eklendiği sürüm: &kde; 4.9

    String document.charAt(int satır, int sütun);
    String document.charAt(Cursor imleç);

  Verilen imleç konumundaki karakteri döndürür.

    String document.firstChar(int satır);

  Verilen satırdaki boşluk olmayan ilk karakteri döndürür. İlk karakter 0 sütunundadır. Satır boşsa veya yalnızca boşluk karakterleri içeriyorsa döndürülen dizi boştur.

    String document.lastChar(int satır);

  Verilen satırdaki boşluk olmayan son karakteri döndürür. Satır boşsa veya yalnızca boşluk karakterleri içeriyorsa döndürülen dizi boştur.

    bool document.isSpace(int satır, int sütun);
    bool document.isSpace(Cursor imleç);

  Verilen imleç konumundaki karakter boşluksa `true`, aksi takdirde `false` döndürür.

    bool document.matchesAt(int satır, int sütun, String metin);
    bool document.matchesAt(Cursor imleç, String metin);

  Verilen metin ilgili imleç konumunda eşleşiyorsa `true`, aksi takdirde `false` döndürür.

    bool document.startsWith(int satır, String metin, bool skipWhiteSpaces);

  Satır metin ile başlıyorsa `true`, aksi takdirde `false` döndürür. skipWhiteSpaces argümanı, baştaki boşlukların yok sayılıp sayılmayacağını denetler.

    bool document.endsWith(int satır, String metin, bool skipWhiteSpaces);

  Satır metin ile bitiyorsa `true`, aksi takdirde `false` döndürür. skipWhiteSpaces argümanı, sondaki boşlukların yok sayılıp sayılmayacağını denetler.

    bool document.setText(String metin);

  Tüm belge metnini ayarlar.

    bool document.clear();

  Belgedeki tüm metni kaldırır.

    bool document.truncate(int satır, int sütun);
    bool document.truncate(Cursor imleç);

  Verilen satırı verilen sütun veya imleç konumunda keser. Başarı durumunda `true`, verilen satır belge aralığının parçası değilse `false` döndürür.

    bool document.insertText(int satır, int sütun, String metin);
    bool document.insertText(Cursor imleç, String metin);

  Verilen imleç konumunda metin metnini ekler. Başarı durumunda `true`, belge saltokunur kipteyse `false` döndürür.

    bool document.removeText(int satırdan, int sütundan, int satıra, int sütuna);
    bool document.removeText(Cursor şuradan, Cursor şuraya);
    bool document.removeText(Range erim);

  Verilen erimdeki metni kaldırır. Başarı durumunda `true`, belge saltokunur kipteyse `false` döndürür.

    bool document.insertLine(int satır, String metin);

  Verilen satırda metin ekler. Başarı durumunda `true`, belge saltokunur kipteyse veya satır belge eriminde değilse `false` döndürür.

    bool document.removeLine(int satır);

  Verilen metin satırını kaldırır. Başarı durumunda `true`, belge saltokunur kipteyse veya satır belge eriminde değilse `false` döndürür.

    bool document.wrapLine(int satır, int sütun);
    bool document.wrapLine(Cursor imleç);

  Verilen imleç konumunda satırı kaydırır. Başarı durumunda `true`, aksi takdirde; örneğin, satır < 0 ise `false` döndürür.

  Eklendiği sürüm: &kde; 4.9

    void document.joinLines(int başlangıçSatırı, int bitişSatırı);

  başlangıçSatırı konumundan bitişSatırı konumuna kadar olan satırları birbirine katar. İki birbirini izleyen metin satırı her zaman bir boşluk ile ayrılır.

    int document.lines();

  Belgedeki satır sayısını döndürür.

    bool document.isLineModified(int satır);

  satır şu anda kaydedilmemiş veri içeriyorsa `true` döndürür.

  Eklendiği sürüm: &kde; 5.0

    bool document.isLineSaved(int satır);

  line değiştirildi ve belge kaydedildiyse `true` döndürür. Böylece, satırda şu anda kaydedilmeyen bir veri kalmamış olur.

  Eklendiği sürüm: &kde; 5.0

    bool document.isLineTouched(int satır);

  line içinde şu anda kaydedilmemiş veri varsa veya daha önce değiştirildiyse `true` döndürür.

  Eklendiği sürüm: &kde; 5.0

    bool document.findTouchedLine(int başlangıçSatırı, bool aşağı);

  line konumundan başlayan sonraki dokunulmuş satırı arar. Arama, down içinde belirtilen yöne göre aşağı veya yukarı doğru yapılır.

  Eklendiği sürüm: &kde; 5.0

    int document.length();

  Belgedeki karakter sayısını döndürür.

    int document.lineLength(int satır);

  satır'ın uzunluğunu döndürür.

    void document.editBegin();

  Geri Al/Yinele gruplaması için bir düzenleme grubu başlatır. Hem `editEnd()` hem de `editBegin()` işlevlerini aynı sayıda çağırdığınızdan emin olun. `editBegin()` işlevini çağırmak içsel olarak bir başvuru sayacı kullanır; demeli, bu çağrı iç içe geçirilebilir.

    void document.editEnd();

  Bir düzenleme grubunu sonlandırır. `editEnd()` işlevinin son çağrısı (&ie; `editBegin()` işlevinin ilk çağrısı için olan) düzenleme adımını bitirir.

    int document.firstColumn(int satır);

  Verilen satır'daki ilk boşluk olmayan sütunu döndürür. Satırda yalnızca boşluklar varsa `-1` döndürülür.

    int document.lastColumn(int satır);

  Verilen satır'daki son boşluk olmayan sütunu döndürür. Satırda yalnızca boşluklar varsa `-1` döndürülür.

    int document.prevNonSpaceColumn(int satır, int sütun);
    int document.prevNonSpaceColumn(Cursor imleç);

  Verilen imleç konumundan başlayıp geriye doğru arama yaparak boşluk olmayan karakter içeren sütunu döndürür.

    int document.nextNonSpaceColumn(int satır, int sütun);
    int document.nextNonSpaceColumn(Cursor imleç);

  Verilen imleç konumundan başlayıp ileriye doğru arama yaparak boşluk olmayan karakter içeren sütunu döndürür.

    int document.prevNonEmptyLine(int satır);

  Verilen imleç konumundan başlayıp geriye doğru arama yaparak sonraki boş olmayan satırı döndürür.

    int document.nextNonEmptyLine(int satır);

  Verilen imleç konumundan başlayıp ileriye doğru arama yaparak sonraki boş olmayan satırı döndürür.

    bool document.isInWord(String karakter, int öznitelik);

  Verilen öznitelik'i içeren karakter bir sözcüğün parçası olabiliyorsa `true`, aksi takdirde `false` döndürür.

    bool document.canBreakAt(String karakter, int öznitelik);

  Verilen öznitelik'i içeren karakter bir satırı kaydırmak için uygunsa `true`, aksi takdirde `false` döndürür.

    bool document.canComment(int başlangıçÖzniteliği, int bitişÖzniteliği);

  Verilen özniteliklerle başlayan ve biten bir erim, yorum olarak imlenebiliyorsa `true`, aksi takdirde `false` döndürür.

    String document.commentMarker(int öznitelik);

  Verilen bir öznitelik için tek satırlık yorumlar için olan yorum imleyicisini döndürür.

    String document.commentStart(int öznitelik);

  Verilen bir öznitelik için çok satırlık yorum başlangıçı için olan yorum imleyicisini döndürür.

    String document.commentEnd(int öznitelik);

  Verilen bir öznitelik için çok satırlık yorum bitişi için olan yorum imleyicisini döndürür.

    Range document.documentRange();

  Tüm belgeyi kapsayan bir erim döndürür.

    Cursor documentEnd();

  Belgedeki son satırın son sütununda konumlanan imleci döndürür.

    bool isValidTextPosition(int satır, int sütun);
    bool isValidTextPosition(Cursor imleç);

  Verilen imleç konumu geçerli bir metin konumundaysa `true` değerini döndürür. Bir metin konumu yalnızca geçerli bir satırın başında, ortasında veya sonunda bulunuyorsa geçerlidir. Ayrıca bir metin konumu, bir Unicode vekilinde bulunuyorsa geçersizdir.

  Eklendiği sürüm: &kde; 5.0

    int document.attribute(int satır, int sütun);
    int document.attribute(Cursor imleç);

  Verilen imleç konumundaki özniteliği döndürür.

    bool document.isAttribute(int satır, int sütun, int öznitelik);
    bool document.isAttribute(Cursor imleç, int öznitelik);

  Verilen imleç konumundaki öznitelik attribute ile eşitse `true`, aksi takdirde `false` döndürür.

    String document.attributeName(int satır, int sütun);
    String document.attributeName(Cursor imleç);

  Öznitelik adını insanlar tarafından okunabilir metin olarak döndürür. Bu, sözdizim vurgulama dosyalarındaki `itemData` adına eşittir.

    bool document.isAttributeName(int satır, int sütun, String ad);
    bool document.isAttributeName(Cursor imleç, String ad);

  Belirli bir imleç konumundaki öznitelik adı verilen ad ile eşleşiyorsa `true`, aksi takdirde `false` döndürür.

    String document.variable(String anahtar);

  İstenen belge değişkeni anahtar'ın değerini döndürür. Belge değişkeni yoksa dönüş değeri boş bir dizidir.

    void document.setVariable(String anahtar, String değer);

  İstenen belge değişkeni anahtar'ın değerini ayarla.

  Ayrıca bakınız: Kate belge değişkenleri

  Eklendiği sürüm: &kde; 4.8

    int document.firstVirtualColumn(int satır);

  Verilen satırdaki boşluk olmayan ilk karakterin sanal sütununu veya satır boşsa veya yalnızca boşluk karakterleri içeriyorsa `-1` döndürür.

    int document.lastVirtualColumn(int satır);

  Verilen satırdaki boşluk olmayan son karakterin sanal sütununu veya satır boşsa veya yalnızca boşluk karakterleri içeriyorsa `-1` döndürür.

    int document.toVirtualColumn(int satır, int sütun);
    int document.toVirtualColumn(Cursor imleç);
    Cursor document.toVirtualCursor(Cursor imleç);

  Verilen gerçek imleç konumunu, bir int veya Cursor nesnesi döndürerek sanal bir imleç konumuna dönüştürür.

    int document.fromVirtualColumn(int satır, int sanalSütun);
    int document.fromVirtualColumn(Cursor sanalİmleç);
    Cursor document.fromVirtualCursor(Cursor sanalİmleç);

  Verilen sanal imleç konumunu, bir int veya Cursor nesnesi döndürerek gerçek imleç konumuna dönüştürür.

    Cursor document.anchor(int satır, int sütun, Char karakter);
    Cursor document.anchor(Cursor imleç, Char karakter);

  Verilen imleçten başlayarak verilen karakteri geriye doğru arar. Örnek olarak, eğer '(' karakter olarak iletilirse bu işlev '(' açılışının konumunu döndürecektir. Bu başvuru sayımı, yani diğer '(...)' yok sayılır.

    Cursor document.rfind(int satır, int sütun, String metin, int öznitelik = -1);
    Cursor document.rfind(Cursor imleç, String metin, int öznitelik = -1);

  Verilen metni uygun öznitelik ile geriye doğru arayarak bulun. Argüman özniteliği, `-1` olarak ayarlanmışsa yok sayılır. Metin bulunamadığında döndürülen imleç geçersizdir.

    int document.defStyleNum(int satır, int sütun);
    int document.defStyleNum(Cursor imleç);

  Verilen imleç konumunda kullanılan öntanımlı biçemi döndürür.

    bool document.isCode(int satır, int sütun);
    bool document.isCode(Cursor imleç);

  Verilen imleç konumundaki öznitelik aşağıdaki biçemlerin tümüne eşit değilse `true` değerini döndürür: `dsComment`, `dsString`, `dsRegionMarker`, `dsChar`, `dsOthers`.

    bool document.isComment(int satır, int sütun);
    bool document.isComment(Cursor imleç);

  İmleç konumundaki karakterin özniteliği `dsComment` ise `true`, aksi takdirde `false` döndürür.

    bool document.isString(int satır, int sütun);
    bool document.isString(Cursor imleç);

  İmleç konumundaki karakterin özniteliği `dsString` ise `true`, aksi takdirde `false` döndürür.

    bool document.isRegionMarker(int satır, int sütun);
    bool document.isRegionMarker(Cursor imleç);

  İmleç konumundaki karakterin özniteliği `dsRegionMarker` ise `true`, aksi takdirde `false` döndürür.

    bool document.isChar(int satır, int sütun);
    bool document.isChar(Cursor imleç);

  İmleç konumundaki karakterin özniteliği `dsChar` ise `true`, aksi takdirde `false` döndürür.

    bool document.isOthers(int satır, int sütun);
    bool document.isOthers(Cursor imleç);

  İmleç konumundaki karakterin özniteliği `dsOthers` ise `true`, aksi takdirde `false` döndürür.

    void document.indent(Range erim, int değişiklik);

  erim'deki tüm satırları değişiklik sekme kadar veya değişiklik kez girintiler. `tabSize` boşlukları kullanıcı tercihlerine bağlıdır. değişiklik parametresi negatif olabilir.

#### Düzenleyici API’si

Belge ve görünüm API’sine ek olarak, genel düzenleyici betiği oluşturma işlevlerine yönelik işlevler sağlayan bir genel düzenleyici API’si vardır.

    String editor.clipboardText();

  Şu anda global panoda bulunan metni döndürür.

  Eklendiği sürüm: &kde-frameworks; 5.50

    String editor.clipboardHistory();

  Düzenleyici, en fazla 10 pano girdisini içeren bir pano geçmişini tutar. Bu işlev, şu anda pano geçmişinde bulunan tüm girdileri döndürür.

  Eklendiği sürüm: &kde-frameworks; 5.50

    void editor.setClipboardText(String metin);

  Panonun içeriğini metin olarak ayarlar. metin, pano geçmişine eklenir.

  Eklendiği sürüm: &kde-frameworks; 5.50