표준 라이브러리 확장 가이드

나만의 KingSejong 모듈을 만들어보세요!

작성일: 2025-11-10

---

목차

1. 모듈 시스템 이해하기
2. 첫 번째 모듈 만들기
3. 모듈 설계 원칙
4. 실전 예제
5. 베스트 프랙티스
6. 표준 라이브러리 기여하기

---

1. 모듈 시스템 이해하기

모듈이란?

모듈은 재사용 가능한 코드 모음입니다. 함수, 변수, 상수를 하나의 파일로 구성하여 다른 프로그램에서 사용할 수 있습니다.

모듈 가져오기

가져오기 "stdlib/math"
가져오기 "mymodule"

모듈 경로 해석

KingSejong은 다음 순서로 모듈을 찾습니다 (첫 번째로 존재하는 파일을 씁니다):

1. 가져오기 문이 있는 파일의 디렉토리 (./x, ../x 는 여기와 2번만 봅니다)
2. 실행 파일 위치에서 찾은 저장소 루트 또는 설치 디렉토리 (bin/../.., bin/../share/kingsejong)
3. 현재 작업 디렉토리
4. 환경변수 KINGSEJONG_PATH 의 디렉토리들 (: 로 구분, Windows 는 ;)
5. 빌드 시 정해진 설치 stdlib 디렉토리 (<prefix>/share/kingsejong)

모듈을 찾지 못하면 에러 메시지에 찾아본 경로가 모두 나옵니다. 모듈 안의 가져오기 도 같은 규칙으로 동작하며, 서로를 가져오는 모듈은 "순환 참조" 에러가 납니다.

예시:

프로젝트/
├── main.ksj
├── mymodule.ksj       # 가져오기 "mymodule"
└── stdlib/
    └── math.ksj        # 가져오기 "stdlib/math"

---

2. 첫 번째 모듈 만들기

단계 1: 모듈 파일 생성

utils.ksj 파일을 만듭니다:

# utils.ksj - 유틸리티 함수 모음

# 인사 함수
인사하기 = 함수(이름) {
    반환 "안녕하세요, " + 이름 + "님!"
}

# 이메일 검증 (간단한 버전)
이메일_검증 = 함수(이메일) {
    # 간단한 검증: @ 포함 여부
    길이값 = 길이(이메일)
    i가 0부터 길이값 미만 {
        # 실제 구현은 문자열 인덱싱 필요
    }
    반환 참  # 간단히 true 반환
}

# 상수
버전 = "1.0.0"

단계 2: 모듈 사용하기

main.ksj:

가져오기 "utils"

메시지 = 인사하기("홍길동")
출력(메시지)

출력("버전: " + 버전)

실행:

./kingsejong main.ksj

출력:

안녕하세요, 홍길동님!
버전: 1.0.0

---

3. 모듈 설계 원칙

원칙 1: 단일 책임

하나의 모듈은 하나의 주제에 집중해야 합니다.

좋은 예:

math.ksj      - 수학 함수만
string.ksj    - 문자열 처리만
array.ksj     - 배열 유틸리티만

나쁜 예:

utils.ksj     - 수학, 문자열, 파일, 네트워크 등 모든 것

원칙 2: 명확한 네이밍

함수 이름은 동사 + 목적어 형태로 작성합니다.

# 좋은 예
배열_정렬한다()
문자열_반복한다()
파일_읽다()

# 나쁜 예
처리()      # 무엇을 처리?
실행()      # 무엇을 실행?

원칙 3: 순수 함수 지향

가능한 한 부작용 없는 순수 함수를 작성합니다.

# 좋은 예 (순수 함수)
더하기 = 함수(a, b) {
    반환 a + b
}

# 나쁜 예 (부작용 있음)
전역변수 = 0
더하기 = 함수(a, b) {
    전역변수 = 전역변수 + 1  # 부작용
    반환 a + b
}

원칙 4: 문서화

모든 공개 함수에 주석을 작성합니다.

# 두 수의 최대공약수를 계산합니다.
# 유클리드 호제법 사용
#
# 매개변수:
#   a: 첫 번째 정수
#   b: 두 번째 정수
#
# 반환값:
#   a와 b의 최대공약수
최대공약수 = 함수(a, b) {
    만약 (b == 0) {
        반환 a
    }
    반환 최대공약수(b, a % b)
}

---

4. 실전 예제

예제 1: datetime 모듈

날짜/시간 처리 모듈 (간단한 버전):

datetime.ksj:

# datetime.ksj - 날짜/시간 유틸리티

# 윤년 판별
윤년인가 = 함수(년도) {
    만약 (년도 % 400 == 0) {
        반환 참
    }
    만약 (년도 % 100 == 0) {
        반환 거짓
    }
    만약 (년도 % 4 == 0) {
        반환 참
    }
    반환 거짓
}

# 월별 일수
월별_일수 = 함수(년도, 월) {
    일수들 = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]

    만약 (월 == 2 && 윤년인가(년도)) {
        반환 29
    }

    반환 일수들[월 - 1]
}

# 두 날짜 사이의 일수 계산 (간단한 버전)
일수_차이 = 함수(년1, 월1, 일1, 년2, 월2, 일2) {
    # 간단한 근사값
    일수1 = (년1 * 365) + (월1 * 30) + 일1
    일수2 = (년2 * 365) + (월2 * 30) + 일2
    반환 일수2 - 일수1
}

# 요일 계산 (Zeller의 공식 - 간략화 버전)
요일_구하기 = 함수(년도, 월, 일) {
    요일들 = ["일요일", "월요일", "화요일", "수요일", "목요일", "금요일", "토요일"]
    # 실제 구현은 복잡한 수식 필요
    # 여기서는 간단히 인덱스 반환
    인덱스 = (년도 + 월 + 일) % 7
    반환 요일들[인덱스]
}

사용 예제:

가져오기 "datetime"

# 윤년 판별
출력(윤년인가(2024))  # 참
출력(윤년인가(2023))  # 거짓

# 월별 일수
출력(월별_일수(2024, 2))  # 29 (윤년)
출력(월별_일수(2023, 2))  # 28

# 날짜 차이
차이 = 일수_차이(2024, 1, 1, 2024, 12, 31)
출력("2024년의 일수: " + 문자열(차이))

예제 2: validator 모듈

데이터 검증 모듈:

validator.ksj:

# validator.ksj - 데이터 검증 유틸리티

가져오기 "stdlib/string"

# 양수인가
양수인가 = 함수(값) {
    반환 값 > 0
}

# 범위 내인가
범위_내인가 = 함수(값, 최소, 최대) {
    반환 값 >= 최소 && 값 <= 최대
}

# 길이 검증
길이_검증 = 함수(문자열, 최소길이, 최대길이) {
    길이값 = 길이(문자열)
    반환 길이값 >= 최소길이 && 길이값 <= 최대길이
}

# 빈 값인가
빈값인가 = 함수(값) {
    만약 (타입(값) == "문자열") {
        반환 비어있는가(값)
    }
    만약 (타입(값) == "배열") {
        반환 길이(값) == 0
    }
    만약 (값 == 없음) {
        반환 참
    }
    반환 거짓
}

# 모든 조건 만족 (all)
모두_만족 = 함수(값, 검증함수들) {
    i가 0부터 길이(검증함수들) 미만 {
        검증함수 = 검증함수들[i]
        만약 (!검증함수(값)) {
            반환 거짓
        }
    }
    반환 참
}

# 하나라도 만족 (any)
하나라도_만족 = 함수(값, 검증함수들) {
    i가 0부터 길이(검증함수들) 미만 {
        검증함수 = 검증함수들[i]
        만약 (검증함수(값)) {
            반환 참
        }
    }
    반환 거짓
}

사용 예제:

가져오기 "validator"

# 양수 검증
출력(양수인가(10))   # 참
출력(양수인가(-5))   # 거짓

# 범위 검증
나이 = 25
출력(범위_내인가(나이, 1, 100))  # 참

# 길이 검증
비밀번호 = "password123"
출력(길이_검증(비밀번호, 8, 20))  # 참

# 빈 값 검증
출력(빈값인가(""))      # 참
출력(빈값인가([]))      # 참
출력(빈값인가(없음))    # 참

예제 3: formatter 모듈

데이터 포맷팅 모듈:

formatter.ksj:

# formatter.ksj - 데이터 포맷팅 유틸리티

가져오기 "stdlib/string"

# 숫자를 천 단위로 구분
천단위_구분 = 함수(숫자) {
    # 간단한 구현
    문자열 = 타입(숫자) + ""
    # 실제로는 3자리마다 쉼표 추가 로직 필요
    반환 문자열
}

# 퍼센트 포맷
퍼센트_포맷 = 함수(값, 전체) {
    비율 = (값 * 100) / 전체
    반환 타입(비율) + "%"
}

# 전화번호 포맷 (간단한 버전)
전화번호_포맷 = 함수(번호) {
    # 010-1234-5678 형식
    # 실제 구현은 문자열 슬라이싱 필요
    반환 번호
}

# 테이블 행 생성
테이블_행 = 함수(데이터배열, 너비배열) {
    결과 = ""
    i가 0부터 길이(데이터배열) 미만 {
        값 = 타입(데이터배열[i]) + ""
        너비 = 너비배열[i]
        셀 = 왼쪽_채우기(값, 너비)
        결과 = 결과 + " " + 셀 + " │"
    }
    반환 "│" + 결과
}

# JSON 형식으로 변환 (간단한 버전)
JSON_변환 = 함수(객체) {
    # 매우 간단한 구현
    반환 "{...}"  # 실제로는 복잡한 변환 로직 필요
}

사용 예제:

가져오기 "formatter"
가져오기 "stdlib/string"

# 퍼센트 포맷
합격자 = 45
전체학생 = 50
출력(퍼센트_포맷(합격자, 전체학생))  # "90%"

# 테이블 생성
출력(줄_만들기(50, "-"))
출력(테이블_행(["이름", "나이", "점수"], [15, 10, 10]))
출력(줄_만들기(50, "-"))
출력(테이블_행(["홍길동", 25, 95], [15, 10, 10]))
출력(테이블_행(["김철수", 30, 88], [15, 10, 10]))
출력(줄_만들기(50, "-"))

---

5. 베스트 프랙티스

1. 에러 처리

유효하지 않은 입력을 확인하고 적절히 처리합니다:

나누기 = 함수(a, b) {
    만약 (b == 0) {
        출력("오류: 0으로 나눌 수 없습니다")
        반환 없음
    }
    반환 a / b
}

2. 기본값 제공

선택적 매개변수에 기본값을 제공합니다:

인사 = 함수(이름, 형식) {
    만약 (형식 == 없음) {
        형식 = "안녕하세요"
    }
    반환 형식 + ", " + 이름 + "님!"
}

3. 테스트 함수 포함

모듈에 간단한 테스트를 포함합니다:

# math_utils.ksj

더하기 = 함수(a, b) {
    반환 a + b
}

# 테스트
테스트_더하기 = 함수() {
    결과 = 더하기(2, 3)
    만약 (결과 == 5) {
        출력("✓ 더하기 테스트 통과")
        반환 참
    } 아니면 {
        출력("✗ 더하기 테스트 실패")
        반환 거짓
    }
}

# 모든 테스트 실행
모든_테스트_실행 = 함수() {
    테스트_더하기()
    # 다른 테스트들...
}

4. 버전 관리

모듈에 버전 정보를 포함합니다:

# mymodule.ksj

모듈_이름 = "MyModule"
모듈_버전 = "1.0.0"
모듈_설명 = "유틸리티 함수 모음"

# ... 함수들 ...

---

6. 표준 라이브러리 기여하기

기여 가이드

1. 아이디어 제안

   • GitHub Issues에 새 모듈 아이디어 제안

2. 구현

   • stdlib/ 디렉토리에 .ksj 파일 생성
   • 명확한 함수 문서 작성
   • 예제 코드 작성

3. 테스트

   • 모든 함수가 올바르게 동작하는지 확인
   • 엣지 케이스 테스트

4. 문서화

   • stdlib/README.md 업데이트
   • 예제 프로그램 추가

5. Pull Request

   • 변경 사항을 PR로 제출
   • 코드 리뷰 반영

표준 라이브러리 후보

다음 모듈들은 향후 표준 라이브러리에 추가될 수 있습니다:

• random.ksj - 랜덤 숫자 생성
• datetime.ksj - 날짜/시간 처리
• file.ksj - 파일 입출력
• json.ksj - JSON 파싱/생성
• http.ksj - HTTP 요청
• regex.ksj - 정규표현식
• crypto.ksj - 암호화/해시

---

참고 자료

• 언어 레퍼런스
• 초보자 튜토리얼
• 표준 라이브러리 문서
• 예제 프로그램

---

즐거운 모듈 개발 되세요! 🚀

© 2025 KingSejong Team