srgn - 코드 외과의사
소스 코드 구문(syntax)을 이해하는 grep-유사 도구로, 검색 기능 외에도 조작(manipulation)이 가능합니다.
grep처럼 정규 표현식(regular expressions)은 핵심적인 기본 원시 요소입니다. 하지만 grep과 달리, 추가적인 기능들은 더 높은 정밀도를 제공하며, 조작을 위한 옵션까지 갖추고 있습니다. 이를 통해 srgn은 정규 표현식이나 IDE 툴링(모두 이름 변경(Rename all), 모든 참조 찾기(Find all references) 등)만으로는 처리할 수 없는 차원에서 작동하여 이들을 보완합니다.
srgn은 취해야 할 *액션(actions)*을 중심으로 구성되어 있으며 (필요한 경우), 오직 정밀하고 선택적으로 언어 문법에 민감한(language grammar-aware) 범위(scopes) 내에서만 작동합니다. 기존 도구의 관점에서 본다면, 이는 다음 조합과 같습니다:
tr,
sed,
ripgrep 그리고
tree-sitter
이 결합된 형태이며, 설계 목표는 *단순성(simplicity)*입니다. 만약 정규 표현식과 작업하는 언어의 기본 개념을 알고 있다면 충분히 사용할 수 있습니다.
"만약 grep, tr, sed 그리고 tree-sitter가 어느 날 밤 술에 취해서 아기를 낳는다면?"
-- Real Python Podcast
간단한 사용법(Quick walkthrough)
[!TIP]
모든 여기에 표시된 코드 스니펫은 실제 srgn 바이너리를 사용하여 유닛 테스트의 일부로 검증되었습니다. 여기서 보여주는 것은 작동이 보장되는 내용입니다.
가장 간단한 srgn 사용법은 tr과 유사하게 작동합니다:
$ echo 'Hello World!' | srgn '[wW]orld' -- 'there'
Hello there!
정규 표현식 패턴 '[wW]orld'에 대한 일치 항목(범위)은 두 번째 위치 인자(second positional argument)로 대체됩니다(액션). 0개 이상의 액션을 지정할 수 있습니다:
$ echo 'Hello World!' | srgn '[wW]orld'
Hello World!
$ echo 'Hello World!' | srgn --upper '[wW]orld' -- 'you'
...
대체(Replacement)는 항상 먼저 수행되며 위치 기반으로 지정됩니다. 인수는 마지막에 오며, 안전을 위해 --로 구분됩니다. 다른 액션은 그 후에 적용되며 명령줄 플래그로 제공됩니다.
다중 스코프 (Multiple scopes)
유사하게, 하나 이상의 스코프를 지정할 수 있습니다: 정규 표현식 패턴 외에도 **소스 코드의 구문 요소(syntactical elements of source code)**에 스코프를 부여하는 언어 문법 인식 (language grammar-aware) 스코프가 주어질 수 있습니다 (예를 들어, "Python의 class 정의 본체 전체"와 같은 것을 생각해보세요). 둘 다 주어진 경우, 정규 표현식 패턴은 오직 그 첫 번째 언어 스코프 내부에서만 적용됩니다. 이는 일반적인 정규 표현식을 사용하는 것만으로는 불가능했던 정밀도로 검색 및 조작을 가능하게 하며, IDE의 *모두 이름 바꾸기(Rename all)*와 같은 도구와는 다른 차원의 기능을 제공합니다.
예를 들어, 이 (의미 없는) Python 소스 파일을 고려해 보세요:
"""Module for watching birds and their age."""
from dataclasses import dataclass
...
다음 명령을 사용하여 검색할 수 있습니다:
$ cat birds.py | srgn --python 'class' 'age'
11: age: int
15: self.age += 1
문자열 age는 Python class 정의 내부에서만 찾았으며(예를 들어, register_bird와 같은 함수 본체에서도 age가 발생하지만, 일반적인 grep에서는 이를 고려 대상에서 제외하는 것이 거의 불가능합니다), 그 외의 곳에서는 발견되지 않았습니다. 기본적으로 이 '검색 모드(search mode)'는 줄 번호도 출력합니다. 액션이 지정되지 않으면 검색 모드로 진입하며, --python과 같은 언어가 주어지면[^3]—이는 'ripgrep이지만 구문적 언어 요소가 추가된 것'처럼 생각할 수 있습니다.
또한 검색은 줄을 가로질러(across lines) 수행될 수 있습니다. 예를 들어, 문서 문자열(docstring)이 누락된 메서드(즉, class 내부의 def)를 찾는 경우입니다:
Note how this does not surface either from_egg (has a docstring) or register_bird
(not a method, def outside class).
여러 언어 범위 지정 (Multiple language scopes)
언어 범위 자체도 여러 번 지정할 수 있습니다. 예를 들어, Rust 스니펫의 경우
pub enum Genre {
Rock(Subgenre),
Jazz,
...
여러 항목을 정밀하게 추출할 수 있습니다.
$ cat music.rs | srgn --rust 'pub-enum' --rust 'type-identifier' 'Subgenre'
2: Rock(Subgenre),
여기서 모든 기준을 충족하는 라인만 반환되며, 모든 조건 사이에 논리적 AND 역할을 합니다. 조건은 왼쪽에서 오른쪽으로 평가되므로, 일부 조합은 의미가 없을 수 있습니다. 예를 들어, Python doc-strings 안에 있는 Python class 본문을 검색하면 보통 아무것도 반환되지 않습니다. 하지만 역방향(inverse)의 경우는 예상대로 작동합니다:
$ cat birds.py | srgn --py 'class' --py 'doc-strings'
8: """A bird!"""
19: """Create a bird from an egg."""
class 본문 밖에 있는 독스트링은 표시되지 않습니다!
-j 플래그는 이 동작을 변경합니다. 왼쪽에서 오른쪽으로 교차하는 방식 대신, 모든 쿼리를 독립적으로 실행하고 그 결과를 결합하여 한 번에 여러 방식으로 검색할 수 있게 합니다:
$ cat birds.py | srgn -j --python 'comments' --python 'doc-strings' 'bird[^s]'
8: """A bird!"""
19: """Create a bird from an egg."""
...
패턴 bird[^s]는 독스트링 안에 있는 것이 아니라, 주석이나 독스트링 내부에서도 동일하게 발견되었습니다.
재귀적 작업 (Working recursively)
표준 입력(standard input)이 제공되지 않으면, srgn은 관련 소스 파일을 자동으로 찾아냅니다. 예를 들어 이 저장소의 경우:
$ srgn --python 'class' 'age'
docs/samples/birds
11: age: int
...
이는 현재 디렉터리를 재귀적으로 탐색하며, 파일 확장자와 shebang 라인을 기반으로 파일을 찾고 매우 빠른 속도로 처리합니다. 예를 들어, srgn --go strings '\d+'를 실행하면 12코어 M3에서 약 300만 줄의 Go 코드베이스에 포함된 Kubernetes 코드베이스 내의 리터럴 Go 문자열에서 발견되는 약 14만 개의 모든 숫자(digits)를 찾아 3초 만에 출력합니다. 여러 파일을 다루는 방법에 대해서는 아래를 참조하십시오.
액션과 스코프 결합하기
스코프와 액션은 거의 임의로 조합할 수 있습니다 (다만, 많은 조합이 사용되거나 심지어 의미가 없을 수도 있습니다). 예를 들어, 다음 Python 코드 조각을 고려해 보십시오 (다른 지원 언어를 사용한 예시는 아래를 참조하십시오):
"""GNU 모듈."""
def GNU_says_moo():
...
여기에 다음 명령을 실행하는 경우:
cat gnu.py | srgn --titlecase --python 'doc-strings' '(?<!The )GNU ([a-z]+)' -- '$1: GNU 🐂 is not Unix'
이 호출 구조는 다음과 같습니다:
--titlecase: 스코프 내에서 발견된 모든 것을 제목 케이스(Titlecase)로 변환하는 액션입니다.
--python 'doc-strings': 파이썬 언어 문법에 따라 독스트링(docstring)으로 범위를 한정하는 스코프입니다.
'(?<!The )GNU ([a-z]+)': 이미 이전 옵션으로 범위가 한정된 내용만 보고, 이를 더 좁힙니다. 이전 범위를 확장할 수는 없습니다. 정규 표현식 스코프는 모든 언어 스코프 적용 이후에 적용됩니다.
<!-- markdownlint-disable MD038 -->
(?<!...)는 부정 후방 탐색(negative lookbehind) 구문으로, 이 고급 기능이 어떻게 사용 가능한지 보여줍니다. The 로 접두사화된 GNU 문자열은 고려되지 않습니다.
<!-- markdownlint-enable MD038 -->
이 명령은 여러 범위(언어 및 정규식 패턴)와 여러 액션(대체 및 대문자 처리)을 사용합니다. 그 결과는 다음과 같습니다.
"""Module: GNU 🐂 Is Not Unix."""
def GNU_says_moo():
...
여기서 변경 사항은 다음으로 제한됩니다:
- """GNU module."""
+ """Module: GNU 🐂 Is Not Unix."""
...
[!WARNING]
While srgn is in beta (major version 0), make sure to only
(recursively) process files you can safely
restore.
검색 모드는 파일을 덮어쓰지 않으므로 항상 안전합니다.
도구의 전체 도움말 출력은 여기를 참조하십시오.
[!NOTE]
지원되는 언어는 다음과 같습니다:
- C
- C#
- Go
- HCL (Terraform)
- Python
- Rust
- TypeScript
설치
미리 빌드된 바이너리
릴리스(releases)에서 미리 빌드된 바이너리를 다운로드하십시오.
cargo-binstall
이 크레이트는 cargo-binstall와 호환되는 형식으로 바이너리를 제공합니다:
- Rust 툴체인을 설치합니다.
cargo install cargo-binstall를 실행합니다 (시간이 다소 걸릴 수 있습니다).
cargo binstall srgn를 실행합니다 (GitHub에서 사전 빌드된 바이너리를 다운로드하므로 몇 초가 소요됩니다).
이 단계들은 CI에서 테스트되었기 때문에 작동하는 것이 보장됩니다™(CI). 또한, 사용자의 플랫폼에 대해 사전 빌드된 바이너리가 제공되지 않는 경우에도 도구가 소스 코드로부터 컴파일로 폴백(fallback)하기 때문에 작동합니다.
Homebrew
다음 경로를 통해 포뮬러를 사용할 수 있습니다:
Nix
nixpkgs에서 사용 가능합니다:
Flake
또한 이 저장소는 플레이크를 포함하고 있으며, 이를 오버레이(overlaying)하거나 직접 실행하는 데 사용할 수 있습니다:
nix run github:alexpovel/srgn
Arch Linux
AUR을 통해 사용할 수 있습니다.
MacPorts
포트(port)가 사용 가능합니다:
CI (GitHub Actions)
모든 GitHub Actions 러너 이미지에는 cargo가 사전 설치되어 있으며, cargo-binstall은 편리한 GitHub Action을 제공합니다:
jobs:
srgn:
name: Install srgn in CI
...
위의 과정들은 컴파일이 필요하지 않기 때문에 단지 총 5초 만에 완료됩니다. 더 자세한 내용은 cargo-binstall의 CI 관련 조언을 참조하십시오.
Cargo (소스 코드로부터 컴파일)
- Rust 툴체인 설치
- C 컴파일러가 필요합니다:
-
리눅스에서는 gcc를 사용합니다.
-
macOS에서는 clang을 사용합니다.
-
윈도우에서는 MSVC를 사용합니다.
설치 시 "C++용 데스크톱 개발(Desktop development with C++)"을 선택하세요.
cargo install srgn을 실행합니다.
Cargo (Rust 라이브러리로 사용 시)
더 많은 정보는 여기를 참조하세요.
셸 완성(Shell completions)
셸 완성 스크립트는 다양한 셸에서 지원됩니다. 예를 들어, ZSH에서 완성을 사용하려면 ~/.zshrc에 eval "$(srgn --completions zsh)"를 추가하세요. 그런 다음 대화형 세션은 다음과 같을 수 있습니다:
srgn shell completion
사용 방법 안내 (Walkthrough)
이 도구는 **스코프(scopes)**와 **액션(actions)**을 중심으로 설계되었습니다. 스코프는 처리할 입력 부분을 좁혀줍니다. 액션은 실제로 처리를 수행합니다. 일반적으로 스코프와 액션 모두 조합 가능하므로, 각각 여러 개를 전달할 수 있습니다. 둘 다 선택 사항이지만 (하지만 아무런 동작도 지정하지 않는 것은 무의미함), 스코프를 지정하지 않으면 전체 입력이 스코프에 포함됨을 의미합니다.