Standard library · Encoding and data

encoding.slug

A URL slug generator with built-in transliteration tables for Persian, Arabic, Cyrillic, Greek, Latin accents, Hebrew, Hindi, Thai, Japanese kana and Korean.

import encoding.slug

A slug is the readable part of an address, like my-first-post in /blog/my-first-post. This package turns a title in any language into one. It is written in Salam, uses fixed tables only (no models, no network, no files), keeps no state, and is safe to call from many threads at once.

Make is the whole story for most programs: it transliterates to ASCII, lowercases, drops emoji, spells out & and %, and joins the words with a hyphen. MakeWith takes an Options value when you need another separator, a length limit, stop words, your own replacements or native letters.

Titles to slugs in one call

Punctuation and spaces become one separator, apostrophes vanish without leaving a gap (what's is whats), accents are removed, symbols such as &, @, %, + and currency signs are written as words, and emoji are dropped.

encoding-slug-guide-basics.salam
import encoding.slug

func main:
    println slug.Make("Hello, World!")
    println slug.Make("  10 Tips & Tricks for 100% Better Code  ")
    println slug.Make("What's new in v2.0? (Release Notes)")
    println slug.Make("Café crème brûlée")
    println slug.Make("user@example.com")
    println slug.Make("Launch day 🚀🎉")
end
Outputhello-world 10-tips-and-tricks-for-100-percent-better-code whats-new-in-v2-0-release-notes cafe-creme-brulee user-at-example-com launch-day

Many languages, one table per script

The script of the text picks the table. DetectScript names the dominant script of a text: latin, cyrillic, greek, arabic, hebrew, devanagari, thai, japanese, korean or han, and an empty text for digits and symbols only. The tables follow the usual conventions of each language, so the result is the spelling readers expect, not a letter-by-letter code.

ScriptWhat is covered
LatinLatin-1, Extended-A and B, Vietnamese, Polish, Czech, Nordic, Turkish; ß is ss, æ is ae, þ is th, full-width letters and ligatures are unfolded. With the language de, ä ö ü become ae oe ue; with da or no, å ø become aa oe.
CyrillicRussian by default, Ukrainian (г is h, и is y, ї is yi at the start of a word and i inside it), Bulgarian (ъ is a, щ is sht), Serbian and Macedonian without diacritics, Belarusian.
GreekELOT 743 style: ου is ou, μπ is b at the start of a word and mp inside it, accents and polytonic marks are removed.
Arabic scriptPersian and Arabic, see the next section.
HebrewConsonants only (the text has no vowels), points are ignored.
DevanagariHindi: consonants carry an inherent a that is dropped at the end of a word and after a virama.
ThaiA basic table: consonants, vowels, pre-posed vowels moved after their consonant, tone marks ignored.
JapaneseHiragana and katakana to Hepburn: きょ is kyo, っ doubles the next consonant, the long vowel mark is ignored.
KoreanHangul syllables are taken apart into their letters algorithmically and written in Revised Romanization, without sound changes between syllables.
ChineseNo pinyin table: Han characters pass through unchanged (see keep_han).
encoding-slug-guide-languages.salam
import encoding.slug

func show(title: str):
    println slug.DetectScript(title) + ":", slug.Make(title)
end

func main:
    show("Привет, мир! Щука и Ёж")
    show("Київ Їжак Ґанок")
    show("Ελληνικά: Καλημέρα κόσμε")
    show("Ağaç ışık İstanbul şeker")
    show("Zażółć gęślą jaźń Łódź")
    show("Nguyễn Thị Minh Khai Đà Nẵng")
    show("שלום עולם")
    show("हिन्दी भारत नमस्ते")
    show("สวัสดี ครับ")
    show("こんにちは ラーメン")
    show("안녕하세요 한국어")
    show("你好 世界")
end
Outputcyrillic: privet-mir-shchuka-i-yozh cyrillic: kyiv-yizhak-ganok greek: ellinika-kalimera-kosme latin: agac-isik-istanbul-seker latin: zazolc-gesla-jazn-lodz latin: nguyen-thi-minh-khai-da-nang hebrew: shlvm-avlm devanagari: hindi-bharat-namaste thai: swasdi-khrab japanese: konnichiha-ramen korean: annyeonghaseyo-hangukeo han: 你好-世界

Persian and Arabic

Persian and Arabic share a script, so the language is told apart by the letters: any of پ چ ژ گ ک ی or the digits ۰ to ۹ mean Persian; ة ى ي ك أ إ without them mean Arabic; text with neither is read as Persian. Pass lang = "fa" or "ar" to decide yourself.

  • Persian digits and Arabic-Indic digits become 0 to 9 everywhere.
  • Tashkeel (harakat), shadda, tatweel and the Quranic marks are removed; presentation forms (ﻻ, ﺳ) are first turned into the plain letters.
  • The zero-width non-joiner is a word boundary: می‌خواهم becomes mi-khvahm.
  • Arabic ي and ك are the same letters as Persian ی and ک.
  • Letters follow the common conventions: خ is kh, ش is sh, چ is ch, ژ is zh, گ is g, ع is a; Persian ق is gh and ث ذ ض are s z z, Arabic ق is q and ث ذ ض are th dh d.
  • و and ی are guessed from their neighbours. In Persian, و is v at the start of a word or before a vowel letter, u otherwise, and va when it stands alone as the word "and"; ی is y at the start, next to a vowel letter, and i otherwise; ای at the start of a word is i (ایران is iran). In Arabic, و is w.
  • Short vowels are not written in Persian or Arabic text and are not guessed, so سلام is slam and محمد is mhmd. When the pretty English spelling matters (a person or a place), set it with AddReplacement.
encoding-slug-guide-persian.salam
import encoding.slug

func main:
    println slug.Make("سلام دنیا")
    println slug.Make("می‌خواهم ایران را ببینم")
    println slug.Make("ژاله و گلی، چای شیرین")
    println slug.Make("قیمت: ۱۲۳٫۵۰ ریال")
    println slug.Make("كتاب علي")
    println slug.Make("مَدرَسه ـــ کِتاب")

    println slug.Transliterate("خوب است، دوستان!", "")
    println slug.Transliterate("قطر ثلاثة", "ar")
    println slug.Transliterate("قطر ثلاثة", "fa")
end
Outputslam-dnya mi-khvahm-iran-ra-bbinm zhalh-va-gli-chay-shirin ghimt-123-50-ryal ktab-ali mdrsh-ktab khub ast, dustan! qtr thlatht ghtr slast

Options

Start from DefaultOptions (or a preset) and change what you need. Stop words are compared with the finished words, so write them in any script and case: they go through the same transliteration as the text. If every word of a title is a stop word, the words are kept so the slug is not empty. Replacements are plain text, applied left to right before anything else, so C++ can become cpp before the plus signs turn into words. fallback is returned when nothing is left.

encoding-slug-guide-options.salam
import encoding.slug

func main:
    title := "The Quick Brown Fox & the Lazy Dog"
    println slug.Make(title)

    mut opts := slug.Options {}
    opts.separator = "_"
    println slug.MakeWith(title, opts)

    opts = slug.DefaultOptions()
    opts.lowercase = false
    println slug.MakeWith(title, opts)

    opts = slug.DefaultOptions()
    slug.AddStopWords(opts, "the a an and of")
    println slug.MakeWith(title, opts)

    opts = slug.DefaultOptions()
    opts.symbols = false
    println slug.MakeWith(title, opts)
    opts.lang = "de"
    opts.symbols = true
    println slug.MakeWith(title, opts)

    opts = slug.DefaultOptions()
    slug.AddReplacement(opts, "C++", "cpp")
    slug.AddReplacement(opts, "C#", "csharp")
    println slug.MakeWith("C++ versus C#", opts)

    opts = slug.DefaultOptions()
    opts.allow = "."
    println slug.MakeWith("Report v1.2.final", opts)

    opts = slug.DefaultOptions()
    opts.fallback = "untitled"
    println slug.MakeWith("???", opts)
    slug.FreeOptions(opts)
end
Outputthe-quick-brown-fox-and-the-lazy-dog the_quick_brown_fox_and_the_lazy_dog The-Quick-Brown-Fox-and-the-Lazy-Dog quick-brown-fox-lazy-dog the-quick-brown-fox-the-lazy-dog the-quick-brown-fox-und-the-lazy-dog cpp-versus-csharp report-v1.2.final untitled

Limiting the length

max_length counts characters, not bytes. The slug is cut between words, never in the middle of one: whole words are kept while they fit, with their separators. Only when the very first word is longer than the limit is it cut, so the result is never empty for a non-empty title. The URL preset limits slugs to 100 characters.

encoding-slug-guide-length.salam
import encoding.slug

func main:
    title := "How to build a fast and friendly web server in Salam"
    mut opts := slug.Options {}
    opts = slug.DefaultOptions()
    println slug.Make(title)
    opts.max_length = 30
    println slug.MakeWith(title, opts)
    opts.max_length = 12
    println slug.MakeWith(title, opts)
    opts.max_length = 5
    println slug.MakeWith("extraordinary", opts)
    println slug.MakeWith(title, slug.URL())
end
Outputhow-to-build-a-fast-and-friendly-web-server-in-salam how-to-build-a-fast-and how-to-build extra how-to-build-a-fast-and-friendly-web-server-in-salam

Keeping the native letters

With keep_unicode the letters of every script stay as they are: only the case is folded (Latin, Greek and Cyrillic), Persian forms are unified (ي to ی, ك to ک), digits become ASCII, marks that do not belong in a word are removed and separators work as usual. Modern browsers and search engines handle such addresses, and they read better for Persian, Russian or Greek sites. Input should be in normal form NFC. Without keep_unicode, Han characters are still kept because no table exists; set keep_han to false to drop them.

encoding-slug-guide-unicode.salam
import encoding.slug

func main:
    mut opts := slug.Options {}
    opts = slug.Unicode()
    println slug.MakeWith("سلام دنیا، ۱۲۳ ك ي", opts)
    println slug.MakeWith("Привет, Мир!", opts)
    println slug.MakeWith("Crème Brûlée Ñandú", opts)
    println slug.MakeWith("你好 世界", opts)
    opts.lowercase = false
    println slug.MakeWith("Привет, Мир!", opts)

    opts = slug.DefaultOptions()
    println slug.MakeWith("abc 你好 def", opts)
    opts.keep_han = false
    println slug.MakeWith("abc 你好 def", opts)
end
Outputسلام-دنیا-123-ک-ی привет-мир crème-brûlée-ñandú 你好-世界 Привет-Мир abc-你好-def abc-def

Unique slugs

Unique takes a function that says whether a slug is already used (a database lookup, a set, a directory listing) and returns the slug itself or the first free one of slug-2, slug-3 and so on. UniqueWith picks the separator and Numbered builds one numbered name. After ten thousand tries the number reached so far is returned, so a function that always answers yes cannot hang the program.

encoding-slug-guide-unique.salam
import encoding.slug

func taken(s: str): bool:
    ret s == "post" or s == "post-2" or s == "post-3"
end

func main:
    println slug.Unique("fresh", (s: str): ret taken(s) end)
    println slug.Unique("post", (s: str): ret taken(s) end)
    println slug.UniqueWith("post", "_", (s: str): ret taken(s) end)
    println slug.Numbered("post", 7, "-")
end
Outputfresh post-4 post_2 post-7

Checking a slug

IsSlug accepts only what Make can produce with the default options: lowercase letters and digits joined by single hyphens, none at either end. IsSlugWith checks against the options you used, including the separator, the length limit and native letters.

encoding-slug-guide-validate.salam
import encoding.slug

func main:
    println slug.IsSlug("hello-world")
    println slug.IsSlug("Hello World")
    println slug.IsSlug("-hello-")
    println slug.IsSlug("a--b")
    println slug.IsSlug(slug.Make("Any title, any language: Привет"))

    println slug.IsSlugWith("hello_world", slug.Snake())
    println slug.IsSlugWith("سلام-دنیا", slug.Unicode())
    println slug.IsSlugWith("9lives", slug.Identifier())
end
Outputtrue false false false true true true false

Presets

URL is the default with a 100 character limit. Filename keeps case, uses _, allows dots and hyphens, limits to 200 characters, never starts or ends with a dot and falls back to file, so ../etc/passwd cannot escape a directory. Snake uses _. Identifier uses _, never starts with a digit and falls back to _, which is what you want for a variable or a column name. Unicode keeps native letters.

encoding-slug-guide-presets.salam
import encoding.slug

func main:
    title := "My Report: Q3 2026 (final).PDF"
    println "default   ", slug.Make(title)
    println "url       ", slug.MakeWith(title, slug.URL())
    println "filename  ", slug.MakeWith(title, slug.Filename())
    println "snake     ", slug.MakeWith(title, slug.Snake())
    println "identifier", slug.MakeWith("9 lives of a cat", slug.Identifier())
    println "unicode   ", slug.MakeWith("Привет мир", slug.Unicode())
end
Outputdefault my-report-q3-2026-final-pdf url my-report-q3-2026-final-pdf filename My_Report_Q3_2026_final.PDF snake my_report_q3_2026_final_pdf identifier _9_lives_of_a_cat unicode привет-мир

What people get wrong:

  • Expecting slam to be written salam. Persian and Arabic text has no short vowels, and the package does not invent them; use AddReplacement for names.
  • Using the slug as a key without Unique. Two different titles can give the same slug, and an empty title gives an empty one unless fallback is set.
  • Counting bytes. max_length counts characters; with keep_unicode a Persian slug of 50 characters is about 100 bytes.
  • Splitting camelCase: fooBar is foobar. Put a space in the title if you want two words.
  • Freeing an Options that holds stop words or replacements twice. Copies of an Options share those two lists, so call FreeOptions once for the family.

Every string returned is new and belongs to the caller. For percent-encoding see encoding.url; to escape text for pages see encoding.html.

Types

Options

struct Options
Everything that decides how a slug is made. Start from DefaultOptions or a preset and change single fields.
NameTypeDescription
separatorstr = "-"Text put between words, a hyphen by default. May be longer than one character or empty.
lowercasebool = trueFold letters to lowercase. On by default.
max_lengthint = 0Largest length in characters, cut between words. 0 means no limit.
langstr = ""Language code that picks between conventions (de, da, no, uk, bg, sr, fa, ar, ru and so on). Empty means detect it from the script. Region suffixes such as pt-BR are ignored.
keep_unicodebool = falseKeep the letters of every script instead of transliterating them.
keep_hanbool = trueKeep Han characters, which have no table. On by default; when off they are dropped.
stop_wordsVectorWords left out of the slug. Use AddStopWords to fill it.
replacementsVectorPairs of pattern and value applied to the title first. Use AddReplacement to fill it.
trimbool = trueRemove separators, and allowed punctuation, from both ends. On by default.
collapsebool = trueMerge a run of separators into one. On by default; when off every character that is not kept gives its own separator.
allowstr = ""ASCII punctuation that stays in the slug, such as ._~ . A separator is not put next to an allowed character.
symbolsbool = trueSpell & @ % + $ and currency signs as words. On by default; when off they are only separators.
identifierbool = falseMake the result usable as a name in code: when it starts with a digit an underscore is put in front.
fallbackstr = ""Returned when the slug would be empty.
encoding-slug-Options.salam
import encoding.slug

func main:
    mut opts := slug.Options {}
    opts = slug.DefaultOptions()
    opts.separator = "_"
    opts.max_length = 20
    opts.lang = "de"
    slug.AddStopWords(opts, "the of")
    slug.AddReplacement(opts, "&", " und ")
    println slug.MakeWith("The Best of Müller & Söhne in Köln", opts)
    slug.FreeOptions(opts)

    println slug.MakeWith("Report (final).pdf", slug.Filename())
    println slug.MakeWith("9 lives", slug.Identifier())
    println slug.MakeWith("Привет мир", slug.Unicode())
    println slug.MakeWith("a b c", slug.URL())
end
Outputbest_mueller_und Report_final.pdf _9_lives привет-мир a-b-c

Functions

DetectScript

func DetectScript(text: str): str
Names the script most letters of a text belong to: latin, cyrillic, greek, arabic, hebrew, devanagari, thai, japanese, korean or han. Returns an empty text when there are no letters. Free the returned text.
encoding-slug-Make.salam
import encoding.slug

func main:
    println slug.Make("Hello, World! Ünïcödé & Co.")
    println slug.MakeWith("Hello, World!", slug.Snake())
    println slug.Transliterate("Привет, мир! Zürich", "")
    println slug.Transliterate("Müller Größe", "de")
    println slug.DetectScript("こんにちは")
    println slug.DetectScript("Καλημέρα")
end
Outputhello-world-unicode-and-co hello_world Privet, mir! Zurich Mueller Groesse japanese greek

DefaultOptions

func DefaultOptions(): Options
The usual choice: hyphen separator, lowercase, no length limit, language detected, symbols spelled as words, separators trimmed and merged.

The example for this item is shown with the ones above: encoding-slug-Options.salam

URL

func URL(): Options
DefaultOptions with the length limited to 100 characters.

The example for this item is shown with the ones above: encoding-slug-Options.salam

Filename

func Filename(): Options
For file names: underscore separator, case kept, dots and hyphens allowed, 200 characters at most, never starts or ends with a dot, falls back to file.

The example for this item is shown with the ones above: encoding-slug-Options.salam

Snake

func Snake(): Options
DefaultOptions with an underscore separator.

The example for this item is shown with the ones above: encoding-slug-Options.salam

Identifier

func Identifier(): Options
For names in code: underscore separator, lowercase, never starts with a digit (an underscore is put in front), falls back to an underscore.

The example for this item is shown with the ones above: encoding-slug-Options.salam

Unicode

func Unicode(): Options
DefaultOptions that keeps the native letters of every script instead of transliterating.

The example for this item is shown with the ones above: encoding-slug-Options.salam

AddStopWords

func AddStopWords(o &: Options, words: str)
Adds words, separated by spaces or commas, that are left out of slugs. They are compared after transliteration and ignoring case.

The example for this item is shown with the ones above: encoding-slug-Options.salam

AddReplacement

func AddReplacement(o &: Options, pattern: str, value: str)
Adds a replacement: every occurrence of the pattern in the title is replaced by the value before anything else happens. Patterns are tried in the order they were added.

The example for this item is shown with the ones above: encoding-slug-Options.salam

FreeOptions

func FreeOptions(o &: Options)
Releases the stop word and replacement lists of an Options. Copies share them, so free once.

The example for this item is shown with the ones above: encoding-slug-Options.salam

MakeWith

func MakeWith(text: str, o: Options): str
Turns a title into a slug with the options you give. Free the returned text.

The example for this item is shown with the ones above: encoding-slug-Make.salam

Make

func Make(text: str): str
Turns a title into a slug with DefaultOptions: transliterated to ASCII, lowercase, words joined by a hyphen, symbols spelled as words, emoji dropped. Free the returned text.

The example for this item is shown with the ones above: encoding-slug-Make.salam

Transliterate

func Transliterate(text: str, lang: str): str
Writes a text in ASCII letters and leaves everything else as it is: case, spaces and punctuation stay, digits of other scripts become 0 to 9, emoji and symbols without a spelling become spaces. The language is a code such as fa, ar, ru, uk, bg, sr, de, da or tr; an empty one is detected from the script. Free the returned text.

The example for this item is shown with the ones above: encoding-slug-Make.salam

Numbered

func Numbered(slug: str, n: int, separator: str): str
Returns the slug followed by the separator and a number, or the slug alone when the number is 1 or less.
encoding-slug-Unique.salam
import encoding.slug

func used(s: str): bool:
    ret s == "post" or s == "post-2"
end

func main:
    println slug.Unique("post", (s: str): ret used(s) end)
    println slug.UniqueWith("post", "_", (s: str): ret used(s) end)
    println slug.Numbered("post", 5, "-")
    println slug.IsSlug("post-3")
    println slug.IsSlugWith("Post_3", slug.Snake())
end
Outputpost-3 post_2 post-5 true false

UniqueWith

func UniqueWith(slug: str, separator: str, exists: func(str): bool): str
Like Unique with the separator you choose. After ten thousand tries it returns the number reached.

The example for this item is shown with the ones above: encoding-slug-Unique.salam

Unique

func Unique(slug: str, exists: func(str): bool): str
Returns the slug when the function says it is free, else the first of slug-2, slug-3 and so on that is free. Free the returned text.

The example for this item is shown with the ones above: encoding-slug-Unique.salam

IsSlugWith

func IsSlugWith(s: str, o: Options): bool
Tells whether a text is a slug for the given options: separator, case, allowed characters, native letters, length limit and identifier rule.

The example for this item is shown with the ones above: encoding-slug-Unique.salam

IsSlug

func IsSlug(s: str): bool
Tells whether a text is a slug the default options could produce: lowercase ASCII letters and digits, single hyphens, none at the ends, not empty.

The example for this item is shown with the ones above: encoding-slug-Unique.salam