slug

README

slug

Package slug generate slug from Unicode string, URL-friendly slugify with multiple languages support.

Example

package main

import (
	"fmt"
	"github.com/gosimple/slug"
)

func main() {
	text := slug.Make("Hellö Wörld хелло ворлд")
	fmt.Println(text) // Will print: "hello-world-khello-vorld"

	someText := slug.Make("影師")
	fmt.Println(someText) // Will print: "ying-shi"

	enText := slug.MakeLang("This & that", "en")
	fmt.Println(enText) // Will print: "this-and-that"

	deText := slug.MakeLang("Diese & Dass", "de")
	fmt.Println(deText) // Will print: "diese-und-dass"

	slug.Lowercase = false // Keep uppercase characters
	deUppercaseText := slug.MakeLang("Diese & Dass", "de")
	fmt.Println(deUppercaseText) // Will print: "Diese-und-Dass"

	slug.CustomSub = map[string]string{
		"water": "sand",
	}
	textSub := slug.Make("water is hot")
	fmt.Println(textSub) // Will print: "sand-is-hot"
}

Design

This library will always returns clean output from any Unicode string containing only the following ASCII characters:

• numbers: 0-9
• small letters: a-z
• big letters: A-Z (only if you set Lowercase to false)
• minus sign: -
• underscore: _

Minus sign and underscore characters will never appear at the beginning or the end of the returned string.

Thanks to context-insensitive transliteration of Unicode characters to ASCII output returned string is safe for URL slugs and filenames.

Requests or bugs?

https://github.com/gosimple/slug/issues

If your language is missing you could add it in languages_substitution.go file.

In case of missing proper Unicode characters transliteration to ASCII you could add them to underlying library: https://github.com/gosimple/unidecode.

Installation

go get -u github.com/gosimple/slug

Benchmarking

go test -run=NONE -bench=. -benchmem -count=6 ./... > old.txt
# make changes
go test -run=NONE -bench=. -benchmem -count=6 ./... > new.txt

go install golang.org/x/perf/cmd/benchstat@latest

benchstat old.txt new.txt

License

The source files are distributed under the Mozilla Public License, version 2.0, unless otherwise noted. Please read the FAQ if you have further questions regarding the license.

Documentation

Overview

Package slug generate slug from unicode string, URL-friendly slugify with multiple languages support.

Example:

package main

import(
	"github.com/gosimple/slug"
	"fmt"
)

func main () {
	text := slug.Make("Hellö Wörld хелло ворлд")
	fmt.Println(text) // Will print: "hello-world-khello-vorld"

	someText := slug.Make("影師")
	fmt.Println(someText) // Will print: "ying-shi"

	enText := slug.MakeLang("This & that", "en")
	fmt.Println(enText) // Will print: "this-and-that"

	deText := slug.MakeLang("Diese & Dass", "de")
	fmt.Println(deText) // Will print: "diese-und-dass"

	slug.Lowercase = false // Keep uppercase characters
	deUppercaseText := slug.MakeLang("Diese & Dass", "de")
	fmt.Println(deUppercaseText) // Will print: "Diese-und-Dass"

	slug.CustomSub = map[string]string{
		"water": "sand",
	}
	textSub := slug.Make("water is hot")
	fmt.Println(textSub) // Will print: "sand-is-hot"
}

Requests or bugs?

https://github.com/gosimple/slug/issues

Index

• Variables
• func IsSlug(text string) bool
• func Make(s string) (slug string)
• func MakeLang(s string, lang string) (slug string)
• func Substitute(s string, sub map[string]string) (buf string)
• func SubstituteRune(s string, sub map[rune]string) string

Variables

var (
	// CustomSub stores custom substitution map
	CustomSub map[string]string
	// CustomRuneSub stores custom rune substitution map
	CustomRuneSub map[rune]string

	// MaxLength stores maximum slug length.
	// By default slugs aren't shortened.
	// If MaxLength is smaller than length of the first word, then returned
	// slug will contain only substring from the first word truncated
	// after MaxLength.
	MaxLength int

	// EnableSmartTruncate defines if cutting with MaxLength is smart.
	// Smart algorithm will cat slug after full word.
	// Default is true.
	EnableSmartTruncate = true

	// Lowercase defines if the resulting slug is transformed to lowercase.
	// Default is true.
	Lowercase = true

	// Append timestamp to the end in order to make slug unique
	// Default is false
	AppendTimestamp = false
)

Functions

func IsSlug

func IsSlug(text string) bool

IsSlug returns True if provided text does not contain white characters, punctuation, all letters are lower case and only from ASCII range. It could contain `-` and `_` but not at the beginning or end of the text. It should be in range of the MaxLength var if specified. All output from slug.Make(text) should pass this test.

func Make

func Make(s string) (slug string)

Make returns slug generated from provided string. Will use "en" as language substitution.

func MakeLang

func MakeLang(s string, lang string) (slug string)

MakeLang returns slug generated from provided string and will use provided language for chars substitution.

func Substitute

func Substitute(s string, sub map[string]string) (buf string)

Substitute returns string with superseded all substrings from provided substitution map. Substitution map will be applied in alphabetic order. Many passes, on one substitution another one could apply.

func SubstituteRune

func SubstituteRune(s string, sub map[rune]string) string

SubstituteRune substitutes string chars with provided rune substitution map. One pass.