Research · narration

Mastering URL Manipulation with stzUrl: A Complete Guide

Creating URL objects is straightforward:

by Mansour Ayouni · in the repository since 2025-07-16 · tutorial · area Web & app server

The stzUrl class is part of the web-wings module in the MAX layer of the Softanza library for Haro. Alongside other web-focused classes like stzJson and stzHtml, it provides sophisticated URL manipulation capabilities built on top of the Softanza Engine's native capabilities. stzUrl delivers an intuitive, object-oriented approach to parsing, building, and manipulating URLs with precision and ease.

Core Concepts

Object Creation and Validation

Haro

# From URL string
o1 = new stzUrl("https://www.google.com")
? o1.IsValid()     #--> TRUE
? o1.Content()     #--> https://www.google.com

# Empty URL object
o1 = new stzUrl("")
? o1.IsEmpty()     #--> TRUE
? o1.IsValid()     #--> FALSE

o1.SetUrl("www.site.com")
? o1.IsValid()	   #--> TRUE

illustration

The class intelligently validates URLs and provides clear feedback about their structure and validity.

Component Extraction

stzUrl excels at decomposing complex URLs into their constituent parts:

Haro

o1 = new stzUrl("https://user:pass@api.example.com:8080/v1/users?format=json#profile")

? o1.Scheme()      #--> https
? o1.Host()        #--> api.example.com
? o1.Port()        #--> 8080
? o1.Path()        #--> /v1/users
? o1.Query()       #--> format=json
? o1.Fragment()    #--> profile
? o1.UserName()    #--> user
? o1.Password()    #--> pass

illustration

Intuitive Method Names

The class provides intuitive method names that make code self-documenting:

Haro

o1 = new stzUrl("ftp://files.example.com/documents/report.pdf")

? o1.Protocol()    #--> ftp
? o1.Domain()      #--> files.example.com
? o1.Server()      #--> files.example.com
? o1.Location()    #--> /documents/report.pdf
? o1.FileName()    #--> report.pdf

illustration

URL Types and Validation

The library recognizes various URL types and provides specialized validation:

Haro

aUrls = [
	"https://www.google.com",
	"http://localhost:3000",
	"ftp://files.example.com",
	"file:///C:/docs/file.txt",
	"../relative/path",
	"invalid url with spaces"
]

for cUrl in aUrls
	o1 = new stzUrl(cUrl)
	? "URL: " + cUrl
	? "  Valid: " + o1.IsValid()
	? "  Relative: " + o1.IsRelative()
	? "  Local File: " + o1.IsLocalFile()
	? ""
next

illustration

Output:

URL: https://www.google.com
  Valid: 1
  Relative: 0
  Local File: 0

URL: http://localhost:3000
  Valid: 1
  Relative: 0
  Local File: 0

URL: ftp://files.example.com
  Valid: 1
  Relative: 0
  Local File: 0

URL: file:///C:/docs/file.txt
  Valid: 1
  Relative: 0
  Local File: 1

URL: ../relative/path
  Valid: 1
  Relative: 1
  Local File: 0

URL: invalid url with spaces
  Valid: 1
  Relative: 1
  Local File: 0

Protocol-Specific Checks

Built-in methods for common protocols:

Haro

? StzUrlQ("https://secure.com").IsHttps()        #--> TRUE
? StzUrlQ("http://regular.com").IsHttp()         #--> TRUE
? StzUrlQ("ftp://files.com").IsFtp()             #--> TRUE
? StzUrlQ("file:///local.txt").IsFileScheme()    #--> TRUE

illustration

NOTE: The StzUrlQ() function creates a stzUrl object and return it so we can directly call any method on it.

Building URLs Programmatically

Step-by-Step Construction

The fluent interface allows elegant URL building:

Haro

oURL = new stzUrl("")
oURL {
    SetScheme("https")
    SetHost("api.mysite.com")
    SetPort(443)
    SetPath("/v2/products")
    SetQuery("category=electronics")
    SetFragment("results")
    
    ? Content()
}
#--> https://api.mysite.com:443/v2/products?category=electronics#results

illustration

Modification and Rebuilding

Existing URLs can be easily modified:

Haro

o1 = new stzUrl("http://www.example.com/products")

# Upgrade to HTTPS
o1.SetScheme("https")

# Add authentication
o1.SetUserName("apiuser")
o1.SetPassword("secret")

# Add query parameters
o1.SetQuery("page=1&size=20")

? o1.Content()
#--> https://apiuser:secret@www.example.com/products?page=1&size=20

illustration

Advanced Features

URL Relationships

The library understands hierarchical relationships between URLs:

Haro

oParent = new stzUrl("https://www.example.com/docs/")
oChild = new stzUrl("https://www.example.com/docs/tutorial/")

? oParent.IsParentOf(oChild)    #--> TRUE

illustration

URL Resolution

Relative URLs can be resolved against base URLs:

Haro

oBase = new stzUrl("https://www.example.com/docs/guide/")
oRelative = new stzUrl("../images/diagram.png")
oResolved = oBase.ResolvedWith(oRelative)

? oResolved.Content()
#--> https://www.example.com/docs/images/diagram.png

illustration

File URL Handling

Seamless conversion between file paths and URLs:

Haro

cFilePath = "C:/Users/Documents/report.pdf"
o1 = new stzUrl("")
oFileUrl = o1.FromLocalFile(cFilePath)

? oFileUrl.Content()        #--> file:///C:/Users/Documents/report.pdf
? oFileUrl.ToLocalFile()    #--> C:/Users/Documents/report.pdf

illustration

Practical Applications

API Endpoint Builder

Haro

oApi = new stzUrl("")
oApi {
    SetScheme("https")
    SetHost("api.github.com")
    SetPath("/repos/microsoft/vscode/issues")
    SetQuery("state=open&labels=bug")
}
#--> https://api.github.com/repos/microsoft/vscode/issues?state=open&labels=bug

illustration

Database Connection URLs

Haro

oDb = new stzUrl("")
oDb {
    SetScheme("postgresql")
    SetUserName("dbuser")
    SetPassword("dbpass")
    SetHost("localhost")
    SetPort(5432)
    SetPath("/myapp_db")
}
#--> postgresql://dbuser:dbpass@localhost:5432/myapp_db

illustration

WebSocket URL Conversion

Haro

oHttp = new stzUrl("https://chat.example.com/room/123")
oWs = oHttp.Copy()
oWs {
    SetScheme("wss")
    SetPath("/ws/room/123")
}
#--> wss://chat.example.com/ws/room/123

illustration

Error Handling and Robustness

The library provides comprehensive error reporting for invalid URLs:

Haro

o1 = new stzUrl("ht tp://invalid space.com")

? o1.IsValid()
#--> FALSE
? o1.Error()

#--> Relative URL's path component contains ':' before any '/';
# source was "ht tp://invalid space.com";
# path = "ht tp://invalid space.com"

illustration

Common error scenarios are handled gracefully, with descriptive messages that help developers identify and fix issues quickly.

Performance and Efficiency

For applications requiring multiple URL manipulations, objects can be reused efficiently:

Haro

o1 = new stzUrl("")
aEndpoints = [
    ["https", "api1.service.com", "/v1/users"],
    ["https", "api2.service.com", "/v1/products"],
    ["https", "api3.service.com", "/v1/orders"]
]

for aEndpoint in aEndpoints
    o1.SetScheme(aEndpoint[1])
    o1.SetHost(aEndpoint[2])
    o1.SetPath(aEndpoint[3])
    ? o1.Content()
next

illustration

Output:

Building multiple URLs:
  https://api1.service.com/v1/users
  https://api2.service.com/v1/products
  https://api3.service.com/v1/orders

Best Practices

Always validate URLs before processing with IsValid()
Use expressive methods like Domain() and Protocol() for clarity
Leverage the Copy() method when creating URL variants
Handle errors gracefully using the Error() method
Reuse objects for performance in batch operations

Conclusion

The stzUrl class exemplifies the power and elegance of Softanza's web-wings module. By transforming complex URL operations into simple, readable code, it demonstrates how the Softanza library makes professional web development accessible in Haro. Whether building web scrapers, API clients, or file management tools, stzUrl provides the precision and flexibility needed for modern applications.

Cite

Mansour Ayouni. "Mastering URL Manipulation with stzUrl: A Complete Guide". Softanza narrations, 2025. https://mayouni.github.io/stzsite/en/narrations/stzmax-stzurl-narration.html

Run in Haro's name on 2026-10-08 20:43 inside the library at commit 4a184e6f0, block after block in one process: 0 of 15 blocks kept their promise; the others are illustrations. The code of the articles is Haro code. Where an article was written before the language took its present name, the name was changed and nothing else. Genre, area and series read from the file's name, the year from its first commit: derived, until the article carries its own header. The file on GitHub(opens in a new tab)

Mastering URL Manipulation with stzUrl: A Complete Guide

Core Concepts

Object Creation and Validation

Component Extraction

Intuitive Method Names

URL Types and Validation

Protocol-Specific Checks

Building URLs Programmatically

Step-by-Step Construction

Modification and Rebuilding

Advanced Features

URL Relationships

URL Resolution

File URL Handling

Practical Applications

API Endpoint Builder

Database Connection URLs

WebSocket URL Conversion

Error Handling and Robustness

Performance and Efficiency

Best Practices

Conclusion

Related reading

Cite