Merge pull request #1 from dracos/main

Add Perl library

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: test
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        perl:
+          [
+            "5.34",
+            "5.30",
+            "5.26",
+            "5.22",
+            "5.18",
+            "5.14",
+            "5.10"
+          ]
+    name: Perl ${{ matrix.perl }}
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup perl
+        uses: shogo82148/actions-setup-perl@v1
+        with:
+          perl-version: ${{ matrix.perl }}
+      - name: Install dependencies
+        run: cpanm -nq --installdeps --with-develop --with-recommends .
+      - name: Run test
+        run: prove -lr t
+

.gitignore

@@ -0,0 +1,31 @@
+/.build/
+/_build/
+/Build
+/Build.bat
+/blib
+/Makefile
+/pm_to_blib
+
+/carton.lock
+/.carton/
+/local/
+
+nytprof.out
+nytprof/
+
+cover_db/
+
+*.bak
+*.old
+*~
+*.swp
+*.o
+*.obj
+
+!LICENSE
+
+/_build_params
+
+MYMETA.*
+
+/Sqids-*

Build.PL

@@ -0,0 +1,12 @@
+# =========================================================================
+# THIS FILE IS AUTOMATICALLY GENERATED BY MINILLA.
+# DO NOT EDIT DIRECTLY.
+# =========================================================================
+
+use 5.008_001;
+use strict;
+
+use Module::Build::Tiny 0.035;
+
+Build_PL();
+

Changes

@@ -0,0 +1,8 @@
+Revision history for Perl extension Sqids
+
+{{$NEXT}}
+
+0.01 2024-04-06T10:42:51Z
+
+    - initial version, working from reference spec
+

META.json

@@ -0,0 +1,75 @@
+{
+   "abstract" : "generate short unique identifiers from numbers",
+   "author" : [
+      "Matthew Somerville <[email protected]>"
+   ],
+   "dynamic_config" : 0,
+   "generated_by" : "Minilla/v3.1.23, CPAN::Meta::Converter version 2.150010",
+   "license" : [
+      "mit"
+   ],
+   "meta-spec" : {
+      "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec",
+      "version" : 2
+   },
+   "name" : "Sqids",
+   "no_index" : {
+      "directory" : [
+         "t",
+         "xt",
+         "inc",
+         "share",
+         "eg",
+         "examples",
+         "author",
+         "builder"
+      ]
+   },
+   "prereqs" : {
+      "configure" : {
+         "requires" : {
+            "Module::Build::Tiny" : "0.035"
+         }
+      },
+      "develop" : {
+         "requires" : {
+            "Test::CPAN::Meta" : "0",
+            "Test::MinimumVersion::Fast" : "0.04",
+            "Test::PAUSE::Permissions" : "0.07",
+            "Test::Pod" : "1.41",
+            "Test::Spellunker" : "v0.2.7"
+         }
+      },
+      "runtime" : {
+         "requires" : {
+            "Carp" : "0",
+            "Class::Tiny" : "0",
+            "perl" : "5.008001"
+         }
+      },
+      "test" : {
+         "requires" : {
+            "Test::Exception" : "0",
+            "Test::More" : "0.98"
+         }
+      }
+   },
+   "release_status" : "unstable",
+   "resources" : {
+      "bugtracker" : {
+         "web" : "https://github.com/dracos/sqids-perl/issues"
+      },
+      "homepage" : "https://github.com/dracos/sqids-perl",
+      "repository" : {
+         "type" : "git",
+         "url" : "https://github.com/dracos/sqids-perl.git",
+         "web" : "https://github.com/dracos/sqids-perl"
+      }
+   },
+   "version" : "0.01",
+   "x_contributors" : [
+      "Ivan Akimov <[email protected]>"
+   ],
+   "x_serialization_backend" : "JSON::PP version 4.16",
+   "x_static_install" : 1
+}

README.md

@@ -1,15 +1,128 @@
-# [Sqids Perl](https://sqids.org/perl)
+[![Actions Status](https://github.com/dracos/sqids-perl/actions/workflows/test.yml/badge.svg)](https://github.com/dracos/sqids-perl/actions)
+# NAME
 
-Sqids (pronounced "squids") is a small library that lets you generate YouTube-looking IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.
+Sqids - generate short unique identifiers from numbers
+
+# SYNOPSIS
+
+    use Sqids;
+    my $sqids = Sqids->new;
+
+    # encode/decode a single number
+    my $id = $sqids->encode(123);         # 'UKk'
+    my $num = $sqids->decode('UKk');      # 123
+
+    # or a list or arrayref
+    $id = $sqids->encode(1, 2, 3);        # '86Rf07'
+    $id = $sqids->encode([1, 2, 3]);      # '86Rf07'
+    my @nums = $sqids->decode('86Rf07');  # (1, 2, 3)
+
+    # also get results in an arrayref
+    my $nums = $sqids->decode('86Rf07');  # [1, 2, 3]
+
+# DESCRIPTION
+
+[Sqids](https://sqids.org/perl) (\*pronounced "squids"\*) is a small
+library that lets you \*\*generate unique IDs from numbers\*\*. It's good for link
+shortening, fast & URL-safe ID generation and decoding back into numbers for
+quicker database lookups.
+
+Features:
+
+- **Encode multiple numbers** - generate short IDs from one or several non-negative numbers
+- **Quick decoding** - easily decode IDs back into numbers
+- **Unique IDs** - generate unique IDs by shuffling the alphabet once
+- **ID padding** - provide minimum length to make IDs more uniform
+- **URL safe** - auto-generated IDs do not contain common profanity
+- **Randomized output** - Sequential input provides nonconsecutive IDs
+- **Many implementations** - Support for [40+ programming languages](https://sqids.org/)
+
+## Use-cases
+
+Good for:
+
+- Generating IDs for public URLs (eg: link shortening)
+- Generating IDs for internal systems (eg: event tracking)
+- Decoding for quicker database lookups (eg: by primary keys)
+
+Not good for:
+
+- Sensitive data (this is not an encryption library)
+- User IDs (can be decoded revealing user count)
 
 ## Getting started
 
-@todo
+Install Sqids via:
+
+    cpanm Sqids
+
+# METHODS
+
+## new
+
+    my $sqids = Sqids->new();
+
+Make a new Sqids object. This constructor accepts a few options, either
+as a hashref or a list (using [Class::Tiny](https://metacpan.org/pod/Class%3A%3ATiny)):
+
+    my $sqids = Sqids->new(
+        alphabet => 'abcdefg',
+        min_length => 4,
+        blocklist => ['word'],
+    );
+
+- alphabet
+
+    You can randomize IDs by providing a custom alphabet:
+
+        my $sqids = Sqids->new({
+          alphabet: 'FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE',
+        });
+        my $id = $sqids->encode(1, 2, 3); # "B4aajs"
+        my $numbers = $sqids->decode($id); # [1, 2, 3]
+
+- min\_length
+
+    Enforce a _minimum_ length for IDs:
+
+        my $sqids = Sqids->new( min_length => 10 );
+        my $id = $sqids->encode(1, 2, 3); # "86Rf07xd4z"
+        my $numbers = $sqids->decode($id); # [1, 2, 3]
+
+- blocklist
+
+    Prevent specific words from appearing anywhere in the auto-generated IDs:
+
+        my $sqids = Sqids->new( blocklist => ['86Rf07'] );
+        my $id = $sqids->encode([1, 2, 3]); # "se8ojk"
+        my $numbers = $sqids->decode($id); # [1, 2, 3]
+
+## encode
+
+    my $id = $sqids->encode($n1, [$n2, ...]);
+
+Encode a single number (or a list of numbers, or a single arrayref of numbers) into a string.
+
+## decode
+
+    my @numbers = $sqids->decode($id);
+
+Decode an id into its number (or numbers). Returns a list in list context,
+or a scalar (one number) or arrayref (multiple numbers) in scalar context.
+
+**Note**: Because of the algorithm's design, **multiple IDs can decode back
+into the same sequence of numbers**. If it's important to your design that IDs
+are canonical, you have to manually re-encode decoded numbers and check that
+the generated ID matches.
+
+# SEE ALSO
+
+[Sqids](https://sqids.org)
 
-## Examples
+# LICENSE
 
-@todo
+Copyright (C) Matthew Somerville. MIT.
 
-## License
+# AUTHOR
 
-[MIT](LICENSE)
+Matthew Somerville <[email protected]>

cpanfile

@@ -0,0 +1,9 @@
+requires 'perl', '5.008001';
+requires 'Class::Tiny';
+requires 'Carp';
+
+on 'test' => sub {
+    requires 'Test::More', '0.98';
+    requires 'Test::Exception';
+};
+