rouge-lexer-dotenv 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cc8cf0f6c5267751bc39290acfc5892601a8013d3247b2b576c4791018e9a1c9
+  data.tar.gz: 20f371518f1fb9a6d43fe3a87a312c641baf5570851fe1d3eeaa5f11c5510ce3
+SHA512:
+  metadata.gz: 91955e35d33d18058127f4ad14fce015993ca9e17c1d5cae17d75c496662b3e92c3eca1c99d80dd5248577dd131cb82b29ffd0840bc4ca9c1f5bace159fff4fc
+  data.tar.gz: 254dcad8a3ad1cba9069e13a35edfa60297bc8da6780c205153c8ac5d8d9ce39838cce243ae1795b0c4b68c52c70022005c5f6d4bc11a505cd9585cd8e77b17d

data/README.md

@@ -0,0 +1,129 @@
+# rouge-lexer-dotenv
+
+[![Test](https://github.com/seanthegeek/rouge-lexer-dotenv/actions/workflows/test.yml/badge.svg)](https://github.com/seanthegeek/rouge-lexer-dotenv/actions/workflows/test.yml)
+[![Gem Version](https://badge.fury.io/rb/rouge-lexer-dotenv.svg)](https://rubygems.org/gems/rouge-lexer-dotenv)
+
+A Rouge lexer plugin for dotenv (.env) environment variable files. Rouge is the
+default syntax highlighter for Jekyll (and therefore GitHub Pages). This gem adds
+.env support to Rouge.
+
+## Installation
+
+The gem requires Ruby 3.0 or newer and Rouge 3.4 or newer.
+
+Install the gem directly:
+
+```sh
+gem install rouge-lexer-dotenv
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem 'rouge-lexer-dotenv'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+## Usage
+
+Once installed, Rouge will automatically discover the lexer. You can use
+`dotenv` as the language tag in fenced code blocks (see the
+lexer definition for additional aliases):
+
+````markdown
+```dotenv
+# your code here
+```
+````
+
+### Jekyll / GitHub Pages
+
+Add the gem to your site's `Gemfile` inside the `:jekyll_plugins` group:
+
+```ruby
+group :jekyll_plugins do
+  gem "rouge-lexer-dotenv"
+end
+```
+
+Run `bundle install`, then use the language tag in fenced code blocks. Jekyll
+will pick up the lexer automatically via Rouge's plugin discovery.
+
+````markdown
+```dotenv
+# Database
+DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
+DATABASE_POOL_SIZE=10
+
+BASE_URL=https://api.example.com
+FULL_URL=${BASE_URL}/v1/users
+```
+````
+
+The aliases `env`, `.env` and `environment` work too:
+
+````markdown
+```env
+ENABLE_CACHE=true
+```
+````
+
+### Colors
+
+The lexer tells Rouge how to identify tokens. Rouge wraps each token in a `span` tag
+with a `class` related to that token type. If you want to change how the tokens are
+highlighted, change themes or add custom CSS.
+
+## Development
+
+Install dependencies:
+
+```sh
+bundle install
+```
+
+Run the test suite:
+
+```sh
+bundle exec rake
+```
+
+Start the visual preview server (available at http://localhost:9292):
+
+```sh
+bundle exec rake server
+```
+
+Run the terminal preview script:
+
+```sh
+ruby preview.rb
+```
+
+Enable debug mode to print each token and its value:
+
+```sh
+DEBUG=1 ruby preview.rb
+```
+
+### Iterative testing workflow
+
+1. Run `bundle exec rake` to check for test failures and error tokens.
+2. Start the server with `bundle exec rake server`.
+3. In another terminal, check for error tokens in the rendered output:
+
+   ```sh
+   curl -s http://localhost:9292 | grep 'class="err"'
+   ```
+
+4. Fix any error tokens in `lib/rouge/lexers/dotenv.rb`.
+5. Repeat until no error tokens remain.
+
+## License
+
+MIT

data/lib/rouge/lexer/dotenv.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'rouge'
+require File.expand_path('../lexers/dotenv', __dir__)

data/lib/rouge/lexers/dotenv.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+# Rouge lexer for dotenv (.env) environment variable files.
+#
+# Every construct recognised here is taken from the env.dev dotenv guide
+# (https://env.dev/guides/dotenv): KEY=value assignments, `#` comments,
+# double-quoted values (spaces, special characters, multiline and `${VAR}`
+# expansion), single-quoted literal values, empty values and `${VAR}`
+# expansion in unquoted values. See AGENTS.md for the design notes.
+module Rouge
+  module Lexers
+    class Dotenv < RegexLexer
+      title 'dotenv'
+      desc 'dotenv (.env) environment variable files (env.dev/guides/dotenv)'
+      tag 'dotenv'
+      aliases 'env', '.env', 'environment'
+      # `.env.test` also matches the PHP lexer's `*.test` (Drupal) pattern and
+      # cannot be disambiguated by filename alone; see the project notes in
+      # AGENTS.md. Passing the source to Rouge::Lexer.guess resolves it.
+      filenames '.env', '.env.*', '*.env'
+      mimetypes 'text/x-dotenv'
+
+      # Boolean values, as used by feature flags in the documentation
+      # (ENABLE_CACHE=true). Only recognised when they are the whole value.
+      def self.constants
+        @constants ||= Set.new %w(true false)
+      end
+
+      # A .env file is a sequence of KEY=value lines (uppercase keys by
+      # convention, no whitespace around the `=`), blank lines and `#`
+      # comments. Require the first few meaningful lines to look like that.
+      def self.detect?(text)
+        lines = text.lines.map(&:strip).reject { |l| l.empty? || l.start_with?('#') }.first(5)
+        return false if lines.empty?
+
+        lines.all? { |l| l.match?(/\A[A-Z][A-Z0-9_]*=/) }
+      end
+
+      # Lookahead: nothing but optional blanks and an optional inline comment
+      # remain on the line, so the token just matched is the whole value.
+      END_OF_VALUE = /(?=[ \t]*(?:#.*)?$)/.freeze
+
+      state :whitespace do
+        rule %r/\s+/, Text::Whitespace
+      end
+
+      state :comment do
+        rule %r/#.*/, Comment::Single
+      end
+
+      state :root do
+        mixin :whitespace
+        mixin :comment
+
+        # KEY=value. Whitespace around `=` is a documented pitfall that breaks
+        # most parsers; it is still tokenised so a stray space does not turn
+        # the whole line into an error.
+        rule %r/([A-Za-z_][A-Za-z0-9_]*)([ \t]*)(=)/ do
+          groups Name::Variable, Text::Whitespace, Operator
+          push :value
+        end
+      end
+
+      # Everything after `=` up to the end of the line.
+      state :value do
+        rule %r/\n/, Text::Whitespace, :pop!
+        rule %r/[ \t]+/, Text::Whitespace
+
+        # Inline comment. Only reachable at a token boundary, i.e. right after
+        # `=` or after whitespace; a `#` glued to an unquoted value (the
+        # documented URL=https://x.com#anchor pitfall) stays part of the value.
+        mixin :comment
+
+        rule %r/"/, Str::Double, :double_string
+        rule %r/'/, Str::Single, :single_string
+
+        mixin :interpolation
+
+        rule %r/\d+#{END_OF_VALUE}/, Num::Integer
+
+        rule %r/[A-Za-z]+#{END_OF_VALUE}/ do |m|
+          if self.class.constants.include?(m[0])
+            token Keyword::Constant
+          else
+            token Str
+          end
+        end
+
+        # Unquoted value text, stopping at whitespace and at `${` expansions
+        rule %r/[^\s$]+/, Str
+        rule %r/\$/, Str
+      end
+
+      # Double quotes allow spaces, special characters, multiline values and
+      # `${VAR}` expansion.
+      state :double_string do
+        rule %r/"/, Str::Double, :pop!
+        rule %r/\\./m, Str::Escape
+        mixin :interpolation
+        rule %r/[^"\\$]+/m, Str::Double
+        rule %r/\$/, Str::Double
+      end
+
+      # Single quotes are literal: no escapes, no interpolation.
+      state :single_string do
+        rule %r/'/, Str::Single, :pop!
+        rule %r/[^']+/m, Str::Single
+      end
+
+      state :interpolation do
+        rule %r/\$\{/, Str::Interpol, :curly
+      end
+
+      state :curly do
+        rule %r/\}/, Str::Interpol, :pop!
+        rule %r/[A-Za-z_][A-Za-z0-9_]*/, Name::Variable
+        # An unterminated `${` ends at the line break; leave the newline to the
+        # enclosing state so it can close the value as well.
+        rule(/(?=\n)/) { pop! }
+        rule %r/[ \t]+/, Text::Whitespace
+      end
+    end
+  end
+end

data/spec/demos/dotenv

@@ -0,0 +1,15 @@
+# App
+NODE_ENV=development
+PORT=3000
+
+# Database
+DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
+DATABASE_POOL_SIZE=10
+
+# External APIs
+STRIPE_SECRET_KEY=sk_test_abc123
+SENDGRID_API_KEY="SG.xxxx"
+# Feature flags
+ENABLE_CACHE=true
+BASE_URL=https://api.example.com
+FULL_URL=${BASE_URL}/v1/users

data/spec/visual/samples/dotenv

@@ -0,0 +1,111 @@
+# Visual sample for the dotenv lexer. Every construct below comes from the
+# env.dev dotenv guide: https://env.dev/guides/dotenv
+
+# ---------------------------------------------------------------------------
+# Basic assignment: KEY=value, uppercase keys, no spaces around the `=`
+# ---------------------------------------------------------------------------
+DATABASE_HOST=localhost
+PORT=3000
+NODE_ENV=development
+LOG_LEVEL=debug
+STRIPE_SECRET_KEY=sk_test_abc123
+BASE_URL=https://api.example.com
+
+# Integer values
+DATABASE_POOL_SIZE=10
+MAX_RETRIES=5
+TIMEOUT_MS=30000
+
+# Feature flags (boolean values)
+ENABLE_CACHE=true
+ENABLE_TRACING=false
+
+# Lowercase and mixed-case keys are accepted even though uppercase is the
+# convention
+db_host=localhost
+apiKey=abc123
+_PRIVATE=1
+
+# ---------------------------------------------------------------------------
+# Quoted values
+# ---------------------------------------------------------------------------
+
+# Double quotes allow spaces and special characters
+GREETING="Hello, World!"
+DATABASE_URL="postgres://user:pass@localhost:5432/mydb"
+SENDGRID_API_KEY="SG.xxxx"
+MESSAGE="It's a \"quoted\" word with a tab\tand a backslash \\"
+DOUBLE_TRUE="true"
+DOUBLE_NUMBER="3000"
+
+# Single quotes treat the value as a literal string with no interpolation
+REGEX='\d+\.\d+'
+LITERAL='${NOT_EXPANDED} stays as written'
+QUOTE='He said "hi"'
+SINGLE_HASH='# not a comment'
+
+# ---------------------------------------------------------------------------
+# Comments and empty values
+# ---------------------------------------------------------------------------
+
+# Database config
+DB_PASSWORD=
+DB_NAME=""
+DB_USER=''
+
+# Inline comments are supported by some parsers but not all
+REDIS_HOST=localhost # local development only
+REDIS_PORT=6379 # default port
+DEBUG=true # feature flag
+CACHE_TTL="60" # quoted number
+
+# An unquoted `#` with no space in front of it is part of the value; many
+# parsers truncate here, so the guide recommends quoting the value instead
+DOCS_URL=https://x.com#anchor
+DOCS_URL_QUOTED="https://x.com#anchor"
+
+# ---------------------------------------------------------------------------
+# Multiline and variable expansion
+# ---------------------------------------------------------------------------
+
+# Some parsers support multiline values in double quotes
+PRIVATE_KEY="-----BEGIN RSA KEY-----
+MIIBogIBAAJBALRi...
+-----END RSA KEY-----"
+
+CERTIFICATE="-----BEGIN CERTIFICATE-----
+MIIC+zCCAeOgAwIBAgIJAL
+-----END CERTIFICATE-----"
+
+# Variable expansion with the ${} syntax
+BASE_URL=https://api.example.com
+FULL_URL=${BASE_URL}/v1/users
+API_ROOT=${BASE_URL}
+HEALTH_URL=${BASE_URL}/health # inline comment after expansion
+PREFIX_AND_SUFFIX=prefix-${NODE_ENV}-suffix
+TWO_VARIABLES=${DATABASE_HOST}:${PORT}
+
+# Expansion inside double quotes
+DATABASE_URL="postgres://user:${DB_PASSWORD}@${DATABASE_HOST}:5432/${DB_NAME}"
+GREETING_FULL="${GREETING} from ${NODE_ENV}"
+
+# A lone dollar sign that is not an expansion is plain text
+PRICE=$5
+PRICE_QUOTED="costs $5"
+
+# ---------------------------------------------------------------------------
+# Whitespace and per-environment values
+# ---------------------------------------------------------------------------
+
+# Whitespace around `=` breaks most parsers; it is tokenised but not endorsed
+SPACED_KEY = value
+	TAB_INDENTED=value
+  SPACE_INDENTED=value
+
+# Values typical of a committed .env.example template
+SECRET_KEY=replace-me
+SENTRY_DSN=
+AWS_REGION=us-east-1
+S3_BUCKET=my-bucket.example.com
+ALLOWED_HOSTS=localhost,127.0.0.1,example.com
+CORS_ORIGINS="http://localhost:3000, https://app.example.com"

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: rouge-lexer-dotenv
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sean Whalen
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rouge
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: A Rouge plugin providing syntax highlighting for dotenv (.env) environment
+  variable files
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/rouge/lexer/dotenv.rb
+- lib/rouge/lexers/dotenv.rb
+- spec/demos/dotenv
+- spec/visual/samples/dotenv
+homepage: https://github.com/seanthegeek/rouge-lexer-dotenv
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/seanthegeek/rouge-lexer-dotenv
+  bug_tracker_uri: https://github.com/seanthegeek/rouge-lexer-dotenv/issues
+  changelog_uri: https://github.com/seanthegeek/rouge-lexer-dotenv/blob/main/CHANGELOG.md
+  documentation_uri: https://github.com/seanthegeek/rouge-lexer-dotenv/blob/main/README.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rouge lexer for .env
+test_files: []