🐰 RabbitJSON v2.1.1 - Kapsamlı Dokümantasyon

📖 Genel Bakış

RabbitJSON, Classic ASP uygulamaları için geliştirilmiş güçlü ve esnek bir JSON işleme kütüphanesidir. Modern web uygulamalarının ihtiyaç duyduğu JSON operasyonlarını VBScript ortamında sorunsuz şekilde gerçekleştirmenizi sağlar.

✨ Temel Özellikler

Hızlı JSON Parsing: Gelişmiş parsing algoritması
HTTP URL Loading: Direkt URL'den JSON yükleme
Path-based Access: Nokta notasyonu ile veri erişimi
Error Handling: Kapsamlı hata yönetimi
Memory Efficient: Otomatik bellek temizleme
Classic ASP Uyumlu: VBScript 5.x+ desteği

🆕 v2.1.1 Yenilikleri

YENİ HTTP/HTTPS URL'den direkt JSON yükleme
GÜNCELLENDİ Gelişmiş key parsing algoritması
GÜNCELLENDİ İyileştirilmiş hata yönetimi
YENİ Kapsamlı test suite

⚡ Kurulum

RabbitJSON'u projenize dahil etmek çok basit:

<!-- #include file="RabbitJSON.v2.asp" -->

📋 Gereksinimler

Classic ASP 3.0+
VBScript 5.0+
IIS 5.0+
Windows Server 2003+

🚀 Hızlı Başlangıç

3 dakikada RabbitJSON kullanmaya başlayın:

1. Basit JSON Parse Etme

<%
' JSON string'ini parse et
Dim jsonStr, json, data
jsonStr = "{""name"":""John"",""age"":30,""city"":""New York""}"

Set json = CreateRabbitJSON()
Set data = json.Parse(jsonStr)

' Veriyi kullan
Response.Write "İsim: " & json.GetValue("name", "") & "<br>"
Response.Write "Yaş: " & json.GetValue("age", 0) & "<br>"
Response.Write "Şehir: " & json.GetValue("city", "")
%>

2. HTTP URL'den JSON Yükleme

<%
' API'den direkt veri çek
Set json = CreateRabbitJSON()
Set data = json.Parse("https://api.github.com/users/octocat")

If Not (data Is Nothing) Then
    Response.Write "Kullanıcı: " & json.GetValue("login", "") & "<br>"
    Response.Write "Takipçi: " & json.GetValue("followers", 0) & "<br>"
Else
    Response.Write "Hata: " & json.LastError
End If
%>

3. JSON Oluşturma

<%
' Dictionary oluştur
Set dict = Server.CreateObject("Scripting.Dictionary")
dict("name") = "Ahmet"
dict("age") = 25
dict("active") = True

' JSON'a çevir
Set json = CreateRabbitJSON()
jsonOutput = json.Stringify(dict, 2)

Response.Write "<pre>" & jsonOutput & "</pre>"
%>

🏗️ JSON Parse Etme

RabbitJSON, JSON verilerini 3 farklı yöntemle parse edebilir:

1. JSON String Parse

<%
Dim jsonString, json, result
jsonString = "{""products"":[{""id"":1,""name"":""Laptop"",""price"":999.99}]}"

Set json = CreateRabbitJSON()
Set result = json.Parse(jsonString)

If Not (result Is Nothing) Then
    Response.Write "Parse başarılı!"
    Response.Write "Ürün adı: " & json.GetValue("products.0.name", "")
Else
    Response.Write "Parse hatası: " & json.LastError
End If
%>

2. Dosyadan JSON Yükleme

<%
' Dosyayı manuel yükle
Dim fso, file, content
Set fso = Server.CreateObject("Scripting.FileSystemObject")
Set file = fso.OpenTextFile(Server.MapPath("data.json"), 1)
content = file.ReadAll()
file.Close()

' Parse et
Set json = CreateRabbitJSON()
Set result = json.Parse(content)
%>

3. HTTP URL'den Yükleme YENİ

<%
' Direkt URL'den parse et
Set json = CreateRabbitJSON()
Set result = json.Parse("https://jsonplaceholder.typicode.com/posts/1")

If Not (result Is Nothing) Then
    Response.Write "Başlık: " & json.GetValue("title", "")
    Response.Write "İçerik: " & Left(json.GetValue("body", ""), 100) & "..."
End If
%>

📄 JSON Serileştirme

Dictionary ve Array objelerini JSON formatına çevirin:

Pretty Print (Girintili)

<%
Set dict = Server.CreateObject("Scripting.Dictionary")
dict("company") = "RabbitCMS"
dict("year") = 2025
dict("active") = True

Set json = CreateRabbitJSON()
Response.Write "<pre>" & json.Stringify(dict, 2) & "</pre>"

' Çıktı:
' {
'   "company": "RabbitCMS",
'   "year": 2025,
'   "active": true
' }
%>

Kompakt Format

<%
compactJson = json.StringifyCompact(dict)
Response.Write compactJson

' Çıktı: {"company":"RabbitCMS","year":2025,"active":true}
%>

🎯 Veri Erişimi

Nokta notasyonu ile nested verilere kolayca erişin:

<%
' Kompleks JSON yapısı
jsonStr = "{""user"":{""profile"":{""name"":""John"",""settings"":{""theme"":""dark""}}}}"

Set json = CreateRabbitJSON()
json.Parse(jsonStr)

' Nested değerlere erişim
userName = json.GetValue("user.profile.name", "")
userTheme = json.GetValue("user.profile.settings.theme", "light")

Response.Write "Kullanıcı: " & userName & "<br>"
Response.Write "Tema: " & userTheme
%>

Array Erişimi

<%
' Array içeren JSON
jsonStr = "{""products"":[{""name"":""Laptop""},{""name"":""Mouse""}]}"

Set json = CreateRabbitJSON()
json.Parse(jsonStr)

' Array elemanlarına erişim (0-based index)
firstProduct = json.GetValue("products.0.name", "")
secondProduct = json.GetValue("products.1.name", "")

Response.Write "İlk ürün: " & firstProduct & "<br>"
Response.Write "İkinci ürün: " & secondProduct
%>

🔧 Parse() Method

JSON string'ini parse eder veya HTTP URL'den JSON yükler.

Parametre	Tip	Açıklama
jsonString	String	JSON string veya HTTP URL
Dönüş	Tip	Açıklama
result	Dictionary/Nothing	Parse edilen data veya Nothing

<%
Set json = CreateRabbitJSON()

' JSON string parse
Set result1 = json.Parse("{""key"":""value""}")

' HTTP URL parse
Set result2 = json.Parse("https://api.example.com/data")

' Hata kontrolü
If result1 Is Nothing Then
    Response.Write "Parse hatası: " & json.LastError
End If
%>

📊 GetValue() Method

Nokta notasyonu ile belirtilen path'den değer alır.

Parametre	Tip	Açıklama
path	String	Nokta notasyonu path (ör: "user.name")
defaultValue	Mixed	Değer bulunamazsa dönen default değer
Dönüş	Tip	Açıklama
value	Mixed	Bulunan değer veya default değer

<%
Set json = CreateRabbitJSON()
json.Parse("{""user"":{""name"":""John"",""age"":30,""active"":true}}")

' Farklı tip değerler
userName = json.GetValue("user.name", "")          ' String
userAge = json.GetValue("user.age", 0)             ' Number  
isActive = json.GetValue("user.active", False)     ' Boolean
salary = json.GetValue("user.salary", 0)           ' Olmayan key - default döner

Response.Write "İsim: " & userName & "<br>"
Response.Write "Yaş: " & userAge & "<br>"
Response.Write "Aktif: " & isActive & "<br>"
Response.Write "Maaş: " & salary ' 0 döner
%>

✏️ SetValue() Method

Nokta notasyonu ile belirtilen path'e değer atar. Gerekirse intermediate objeler oluşturur.

<%
Set json = CreateRabbitJSON()
json.Parse("{}")

' Nested path oluşturma
json.SetValue "user.profile.name", "John"
json.SetValue "user.profile.age", 30
json.SetValue "user.settings.theme", "dark"
json.SetValue "user.settings.notifications", True

' Array oluşturma
json.SetValue "user.hobbies.0", "Programming"
json.SetValue "user.hobbies.1", "Reading"

' JSON çıktısı
Response.Write "<pre>" & json.Stringify(json.Data, 2) & "</pre>"
%>

🔍 HasValue() Method

Belirtilen path'in var olup olmadığını kontrol eder.

<%
Set json = CreateRabbitJSON()
json.Parse("{""user"":{""name"":""John"",""email"":null}}")

' Path kontrolü
If json.HasValue("user.name") Then
    Response.Write "İsim mevcut: " & json.GetValue("user.name", "")
End If

If json.HasValue("user.email") Then
    Response.Write "Email mevcut ama null olabilir"
End If

If Not json.HasValue("user.phone") Then
    Response.Write "Telefon bilgisi yok"
End If
%>

🗑️ RemoveValue() Method

Belirtilen path'deki değeri siler.

<%
Set json = CreateRabbitJSON()
json.Parse("{""user"":{""name"":""John"",""temp"":""delete-me""}}")

' Değer silme
If json.RemoveValue("user.temp") Then
    Response.Write "Geçici değer silindi"
Else
    Response.Write "Silme hatası: " & json.LastError
End If

' Son durum
Response.Write "<pre>" & json.Stringify(json.Data, 2) & "</pre>"
%>

🎯 Helper Functions

Hızlı işlemler için global helper fonksiyonlar:

CreateRabbitJSON()

<%
' Yeni RabbitJSON instance oluştur
Set json = CreateRabbitJSON()
%>

ParseJSON(jsonString)

<%
' Hızlı parse - direkt Dictionary döner
Set data = ParseJSON("{""key"":""value""}")
Response.Write data("key")
%>

ToJSON(obj, indent)

<%
Set dict = Server.CreateObject("Scripting.Dictionary")
dict("name") = "John"

' Hızlı stringify
jsonStr = ToJSON(dict, 2)
Response.Write "<pre>" & jsonStr & "</pre>"
%>

ToJSONCompact(obj)

<%
' Kompakt JSON
compactStr = ToJSONCompact(dict)
Response.Write compactStr
%>

📍 Path Notation (Nokta Notasyonu)

RabbitJSON, nested verilere erişim için güçlü nokta notasyonu destekler:

📋 Path Syntax Kuralları

Object erişimi: object.property
Nested object: user.profile.name
Array erişimi: products.0.name (0-based index)
Deep nesting: data.users.0.profile.settings.theme

<%
' Kompleks JSON yapısı
jsonStr = "{"
jsonStr = jsonStr & """company"": {"
jsonStr = jsonStr & "  ""name"": ""RabbitCMS"","
jsonStr = jsonStr & "  ""employees"": ["
jsonStr = jsonStr & "    {""name"": ""John"", ""role"": ""Developer""},"
jsonStr = jsonStr & "    {""name"": ""Jane"", ""role"": ""Designer""}"
jsonStr = jsonStr & "  ],"
jsonStr = jsonStr & "  ""settings"": {"
jsonStr = jsonStr & "    ""theme"": {""primary"": ""blue"", ""secondary"": ""gray""}"
jsonStr = jsonStr & "  }"
jsonStr = jsonStr & "}"

Set json = CreateRabbitJSON()
json.Parse(jsonStr)

' Path örnekleri
companyName = json.GetValue("company.name", "")                    ' "RabbitCMS"
firstEmployee = json.GetValue("company.employees.0.name", "")      ' "John"
primaryColor = json.GetValue("company.settings.theme.primary", "") ' "blue"

Response.Write "Şirket: " & companyName & "<br>"
Response.Write "İlk çalışan: " & firstEmployee & "<br>"
Response.Write "Ana renk: " & primaryColor
%>

⚠️ Hata Yönetimi

RabbitJSON kapsamlı hata yönetimi sağlar:

<%
Set json = CreateRabbitJSON()

' Geçersiz JSON test
Set result = json.Parse("{invalid json}")

If result Is Nothing Then
    Response.Write "<div class='error'>"
    Response.Write "Parse Hatası: " & json.LastError
    Response.Write "</div>"
Else
    Response.Write "Parse başarılı!"
End If

' HTTP hata test
Set result = json.Parse("https://invalid-url-test.com/api")
If result Is Nothing Then
    Response.Write "<div class='error'>"
    Response.Write "HTTP Hatası: " & json.LastError
    Response.Write "</div>"
End If

' Güvenli veri erişimi
safeValue = json.GetValue("non.existent.path", "default-value")
Response.Write "Güvenli değer: " & safeValue
%>

🚨 Yaygın Hata Durumları

Invalid JSON Syntax: Eksik tırnak, virgül hatası
HTTP Connection Error: URL erişim problemi
Path Not Found: Olmayan path erişimi
Type Mismatch: Yanlış veri tipi beklentisi

⚡ Performance & Best Practices

💡 Performance İpuçları

Object Reuse: Aynı JSON instance'ını tekrar kullanın
Batch Operations: Çoklu veri erişimi için tek seferde alın
Memory Management: Büyük objeler için Clear() kullanın
Path Caching: Sık kullanılan path'leri değişkende saklayın

<%
' ✅ İYİ - Object reuse
Set json = CreateRabbitJSON()
For i = 1 To 10
    Set data = json.Parse("api-call-" & i & ".json")
    ' Process data
Next

' ✅ İYİ - Batch data access
userName = json.GetValue("user.name", "")
userEmail = json.GetValue("user.email", "")
userAge = json.GetValue("user.age", 0)

' ✅ İYİ - Memory cleanup
json.Clear()  ' Büyük veri sonrası

' ❌ KÖTÜ - Her iterasyonda yeni object
For i = 1 To 10
    Set newJson = CreateRabbitJSON()  ' Gereksiz
    ' Process...
Next
%>

📊 Performance Metrikleri

Operasyon	Tipik Süre	Açıklama
Small JSON Parse (<1KB)	<5ms	Basit objeler
Medium JSON Parse (1-10KB)	5-50ms	Orta kompleks yapılar
Large JSON Parse (>10KB)	50-200ms	Büyük veri setleri
HTTP URL Loading	100-2000ms	Ağ gecikme dahil
Path Access	<1ms	Parsed data'dan erişim

📚 Gerçek Dünya Örnekleri

🛒 E-Commerce API Entegrasyonu

<%
' E-commerce API'den ürün bilgisi çek
Set json = CreateRabbitJSON()
Set productData = json.Parse("https://api.store.com/products/123")

If Not (productData Is Nothing) Then
    productName = json.GetValue("name", "")
    productPrice = json.GetValue("price", 0)
    inStock = json.GetValue("inventory.available", False)
    
    Response.Write "<div class='product'>"
    Response.Write "<h3>" & productName & "</h3>"
    Response.Write "<p>Fiyat: $" & FormatNumber(productPrice, 2) & "</p>"
    
    If inStock Then
        Response.Write "<span class='available'>Stokta</span>"
    Else
        Response.Write "<span class='unavailable'>Stok Yok</span>"
    End If
    Response.Write "</div>"
End If
%>

👥 Kullanıcı Profili Yönetimi

<%
' Kullanıcı profili güncelleme
Set json = CreateRabbitJSON()
json.Parse("{}")

' Profil verilerini set et
json.SetValue "user.id", 12345
json.SetValue "user.profile.name", Request.Form("name")
json.SetValue "user.profile.email", Request.Form("email")
json.SetValue "user.settings.notifications", True
json.SetValue "user.settings.theme", "dark"
json.SetValue "user.lastUpdated", Now()

' Veritabanına kaydet
profileJson = json.StringifyCompact(json.Data)
' SQL: UPDATE users SET profile_data = '" & profileJson & "' WHERE id = 12345
%>

📊 Analytics Dashboard

<%
' Analytics API'den veri çek
Set json = CreateRabbitJSON()
Set analyticsData = json.Parse("https://analytics.api.com/dashboard")

If Not (analyticsData Is Nothing) Then
    todayVisitors = json.GetValue("today.visitors", 0)
    totalPageViews = json.GetValue("today.pageViews", 0)
    bounceRate = json.GetValue("today.bounceRate", 0)
    
    ' Top sayfalar
    For i = 0 To 4  ' İlk 5 sayfa
        pagePath = json.GetValue("topPages." & i & ".path", "")
        pageViews = json.GetValue("topPages." & i & ".views", 0)
        
        If pagePath <> "" Then
            Response.Write "<tr>"
            Response.Write "<td>" & pagePath & "</td>"
            Response.Write "<td>" & FormatNumber(pageViews, 0) & "</td>"
            Response.Write "</tr>"
        End If
    Next
End If
%>

📋 Değişiklik Geçmişi

v2.1.1 (2025-01-20) GÜNCEL

✅ HTTP/HTTPS URL'den direkt JSON yükleme desteği
✅ Gelişmiş key parsing algoritması (whitespace temizleme)
✅ İyileştirilmiş hata mesajları
✅ Kapsamlı test suite eklendi
🔧 Performance optimizasyonları

v2.0.0 (2024-12-15)

🎯 Tamamen yeniden yazıldı
✅ Class-based architecture
✅ Nokta notasyonu path desteği
✅ Nested object/array handling
✅ Helper functions eklendi

v1.0.0 (2024-06-01)

🎉 İlk stable release
✅ Temel JSON parse/stringify
✅ Classic ASP uyumluluğu

🔧 Uyumluluk Matrisi

Bileşen	Minimum Versiyon	Önerilen	Test Edildi
Classic ASP	3.0	3.0	✅
VBScript	5.0	5.6+	✅
IIS	5.0	7.0+	✅
Windows Server	2003	2016+	✅
MSXML	3.0	6.0	✅

⚠️ Bilinen Sınırlamalar

Unicode escape sequences (\uXXXX) tam desteklenmez
Çok büyük JSON dosyaları (>10MB) memory limiti yaşayabilir
Recursive referanslar desteklenmez
BigInteger/Decimal precision VBScript limitli

🛠️ Sorun Giderme

❌ Yaygın Problemler ve Çözümleri

Problem: "Parse error: Invalid JSON format"

Çözüm: JSON syntax'ını kontrol edin. Tüm string'ler çift tırnak içinde olmalı.

❌ Yanlış: {'name': 'John'}
✅ Doğru:  {"name": "John"}

Problem: "Path element not found in object"

Çözüm: Path'in doğru olduğunu ve case-sensitive olduğunu kontrol edin.

// Path kontrolü
If json.HasValue("user.name") Then
    userName = json.GetValue("user.name", "")
Else
    Response.Write "Path bulunamadı!"
End If

Problem: HTTP URL loading başarısız

Çözüm: URL'in erişilebilir olduğunu ve HTTPS sertifikasını kontrol edin.

Set result = json.Parse(apiUrl)
If result Is Nothing Then
    Response.Write "HTTP Error: " & json.LastError
    ' Alternatif: Manuel HTTP request
End If

🔍 Debug İpuçları

<%
' JSON parse debug
Set json = CreateRabbitJSON()
Set result = json.Parse(jsonString)

Response.Write "<h4>Debug Bilgileri:</h4>"
Response.Write "Parse Sonucu: " & TypeName(result) & "<br>"
Response.Write "Hata Mesajı: " & json.LastError & "<br>"

If Not (result Is Nothing) Then
    Response.Write "Root Key Sayısı: " & UBound(json.GetKeys()) + 1 & "<br>"
    Response.Write "İlk Key: " & json.GetKeys()(0) & "<br>"
End If
%>