전처리기

"#INCLUDE, #INSERT, IncludeFile로 프로그램을 여러 파일에 나누고, #IF와 타깃 프로파일로 필요한 타깃에서만 줄을 컴파일하는 법을 다룹니다."

한 줄 요약#

전처리기는 컴파일러보다 먼저, 프로그램을 텍스트 줄로 읽습니다. 하는 일은 두 가지입니다. 다른 파일의 줄을 가져오는 것, 그리고 프로그램이 컴파일되는 곳에 따라 줄을 남기거나 버리는 것입니다. 이 페이지의 모든 것은 문장 하나가 컴파일되기 전에 결정됩니다.

프로젝트 모듈: 파일은 어디서 오는가#

포함되는 파일은 프로젝트의 BASIC 모듈이며 그 밖의 것은 없습니다. 컴파일러는 디스크 경로나 URL을 읽지 않습니다.

  • 만들기: 스크립트 에디터에서 File › New Script · BASIC Module을 선택합니다. 이름은 modules/module_1.bas(그다음 module_2.bas…)이고 OPTION EXPLICIT로 시작합니다.
  • 가져오기: .bas 또는 .agc 파일을 **File › Import…**로 가져오면 파일 이름을 딴 모듈로 추가됩니다. (에디터가 엔티티의 스크립트에서 열려 있으면 Import는 그 스크립트를 대체합니다.)
  • 이름 바꾸기(우클릭, Rename)로 폴더에 배치합니다. 이름이 곧 경로입니다. lib/math.bas로 이름을 바꾼 모듈은 #INCLUDE "lib/math.bas"로 포함합니다.
  • 모듈은 혼자 실행되지 않습니다. 프로젝트와 함께 저장되고, 프로젝트와 함께 HTML과 Bevy로 내보내집니다.
  • #INCLUDE ", #INSERT ", IncludeFile(" 뒤에서 에디터가 모듈 이름을 자동 완성합니다.

#INCLUDE, #INSERT, IncludeFile#

#INCLUDE "<path>"
#INSERT "<path>"
IncludeFile("<path>")

셋 모두 디렉티브 자리에 모듈의 줄을 넣습니다. 한 가지가 다릅니다.

디렉티브횟수
#INCLUDE프로그램당 한 번. 어떤 파일이 요청하든 같은 파일에 대한 이후의 요청은 건너뜁니다.
#INSERT나타날 때마다
IncludeFile나타날 때마다 (#INSERT의 PureBasic 이름)

모듈 lib/math.bas는 FUNCTION Clamp(value, low, high)를 선언합니다.

FUNCTION Clamp(value, low, high)
  IF value < low THEN EXITFUNCTION low
  IF value > high THEN EXITFUNCTION high
ENDFUNCTION value

메인 프로그램이 그것을 두 번 요청해도, #INCLUDE는 한 번만 가져옵니다.

#INCLUDE "lib/math.bas"
#INCLUDE "lib/math.bas"
Console(Str(Clamp(15, 0, 10)))   ' 10

#INSERT를 쓰면 함수가 두 번 선언되어 거부됩니다.

#INSERT "lib/math.bas"
#INSERT "lib/math.bas"

오류는 "Ambiguous BASIC overload: Clamp"이며 lib/math.bas에서 보고됩니다.

선언을 담은 파일(함수, TYPE, GLOBAL)에는 #INCLUDE를 쓰세요. 반복하고 싶은 코드 조각에는 #INSERT를 쓰세요.

모듈 snippets/banner.bas는 코드 한 줄입니다.

Console("==========")
#INSERT "snippets/banner.bas"
Console("  LEVEL 1")
#INSERT "snippets/banner.bas"

배너 줄이 LEVEL 1의 위와 아래에 두 번 출력됩니다.

  • 디렉티브는 줄당 하나, 그 줄에 단독으로. 끝의 ' 주석은 괜찮습니다.
  • ⚠️ : 뒤에는 안 됩니다. x = 1 : #INCLUDE "lib/math.bas"는 거부되지 않지만, 디렉티브가 텍스트로 프로그램에 남아 프로그램이 시작될 수 없습니다.
  • 경로는 큰따옴표로 감쌉니다. 세 가지 모두 괄호는 선택 사항입니다. IncludeFile "lib/math.bas"도 동작합니다.
  • 키워드와 경로는 대소문자를 무시합니다. #include "LIB/Math.bas"는 같은 줄입니다.
  • 단순한 텍스트 삽입입니다. FUNCTION 안의 디렉티브는 거기에 줄을 넣습니다. 런타임 IF 안의 디렉티브는 조건과 상관없이 삽입됩니다. IF는 그 줄들을 실행할지만 정합니다. 파일을 빼려면 아래의 #IF를 쓰세요.
  • #INSERT는 #INCLUDE에 포함되지 않습니다. 앞서 삽입된 파일도 이후의 #INCLUDE가 한 번 가져옵니다.

경로#

경로는 두 곳에서 이 순서로 찾습니다.

  1. 디렉티브가 있는 파일 옆(그 폴더);
  2. 프로젝트의 루트부터.

/와 \는 모두 폴더를 구분하고, ..는 한 폴더 위로 갑니다. 어떤 모듈과도 맞지 않는 경로는 디렉티브의 줄에서 컴파일 오류가 됩니다. "BASIC include file not found: <path>".

모듈 game/player.bas는 FUNCTION ClampHealth(hp)를 선언하며, 한 폴더 위의 lib/math.bas가 필요합니다.

#INCLUDE "../lib/math.bas"

FUNCTION ClampHealth(hp)
ENDFUNCTION Clamp(hp, 0, 100)
#INCLUDE "game/player.bas"
#INCLUDE "lib/math.bas"
Console(Str(ClampHealth(140)))   ' 100

lib/math.bas는 game/player.bas와 메인 프로그램에 의해 두 번 요청되지만 한 번만 포함됩니다.

순환#

서로를 포함하는 두 파일은 순환을 이룹니다.

  • #INCLUDE에서는 이미 포함된 파일을 건너뛰므로 순환이 그냥 멈춥니다. 오류는 없습니다.
  • #INSERT나 IncludeFile에서는 순환이 컴파일 오류이며, 연쇄를 알려 줍니다. "Cyclic BASIC include: loop/a.bas -> loop/b.bas -> loop/a.bas".

모듈 loop/a.bas와 loop/b.bas는 서로를 삽입합니다.

#INSERT "b.bas"
#INSERT "a.bas"
#INSERT "loop/a.bas"

모듈 안의 오류#

포함된 줄의 오류는 메인 프로그램의 줄이 아니라 모듈의 이름과 그 모듈의 줄 번호와 함께 보고됩니다. 콘솔에서 더블클릭하면 그 모듈이 열립니다. 콘솔 형식은 오류를 참고하세요.

조건부 컴파일#

#IF <condition>
  <lines>
[#ELSEIF <condition>]
  <lines>
[#ELSE]
  <lines>
#ENDIF

#IFDEF <symbol>
#IFNDEF <symbol>
#DEFINE <symbol>
#UNDEF <symbol>

CompilerIf <condition>
CompilerElseIf <condition>
CompilerElse
CompilerEndIf

#IF는 조건이 참인 첫 번째 분기의 줄을 남기고 나머지를 버립니다. 조건은 심볼을 검사합니다. 심볼은 값 없이 정의되어 있거나 아니거나 하는 이름입니다.

#IF ENGINE AND DEBUG
Console("editor build")
#ELSEIF HTML
Console("web export")
#ELSE
Console("other target")
#ENDIF

에디터에서는 editor build가 출력됩니다. 같은 프로그램의 HTML 내보내기에는 web export 줄만 들어갑니다.

철자의미
#IF, #ELSEIF (또는 #ELIF), #ELSE, #ENDIF분기
#IFDEF X#IF X와 같으며, 심볼 하나에만
#IFNDEF X#IF NOT X와 같으며, 심볼 하나에만
CompilerIf, CompilerElseIf, CompilerElse, CompilerEndIf#IF, #ELSEIF, #ELSE, #ENDIF의 PureBasic 이름

조건에 들어갈 수 있는 것#

쓰는 것참이 되는 때
WEB심볼 WEB이 정의되어 있을 때
DEFINED(WEB), DEFINED WEB같음
NOT WEB, !WEBWEB이 정의되어 있지 않을 때
WEB AND DEBUG, WEB && DEBUG둘 다 정의되어 있을 때
WEB OR BEVY, WEB || BEVY적어도 하나가 정의되어 있을 때
DEBUG && (WEB OR BEVY)괄호로 묶음: DEBUG, 그리고 WEB 또는 BEVY 중 하나
TRUE, FALSE항상, 절대 아님
  • NOT은 AND보다, AND는 OR보다 강하게 묶입니다. 의심스러우면 괄호를 추가하세요.
  • 알 수 없는 심볼은 그냥 거짓입니다. 심볼 이름의 오타는 오류가 아닙니다. 철자를 확인하세요.
  • 그 밖의 것은 허용되지 않습니다. 숫자, 문자열, 비교, 상수 모두 안 됩니다. #IF 1, #IF LEVEL = 3, PureBasic의 CompilerIf #PB_Compiler_OS = #PB_OS_Windows는 모두 "Invalid BASIC compiler condition"으로 거부됩니다. PureBasic의 인자 두 개짜리 Defined도 거부됩니다. DEFINED(X)라고 쓰세요.
  • 디렉티브와 심볼은 대소문자를 무시합니다. #if web도 동작합니다.

블록 규칙#

  • 디렉티브는 줄당 하나. 끝의 ' 주석은 괜찮습니다.
  • 블록은 깊이에 제한 없이 중첩됩니다.
  • 블록은 같은 파일에서 열고 닫아야 합니다. 메인 프로그램의 #IF가 모듈에서 끝날 수는 없습니다.
  • 버려진 분기의 줄은 비워지며 컴파일되지 않습니다. BASIC이 아닌 텍스트를 포함해 무엇이든 들어 있어도 되고, 나머지 줄의 줄 번호는 그대로 유지됩니다.
  • REMSTART … REMEND 또는 /* … */ 주석 안에 쓴 디렉티브는 무시됩니다.
메시지원인
#IF requires #ENDIF파일 끝에서 블록이 열려 있음
#ENDIF without #IF, #ELSE without #IF, #ELSEIF without #IF열린 블록이 없음
#ELSEIF after #ELSE, Duplicate #ELSE순서가 틀림
Invalid BASIC compiler condition: …숫자나 비교가 있는 조건, 또는 심볼이 둘 이상인 #IFDEF
#DEFINE requires one symbol값이 있는 #DEFINE

#DEFINE과 #UNDEF#

#DEFINE은 심볼을 추가하고, #UNDEF는 제거합니다. 자신만의 스위치에 쓰세요.

#DEFINE CHEATS
#IF DEFINED(CHEATS) AND NOT RELEASE
Console("cheat keys on")
#ENDIF

에디터에서는 cheat keys on이 출력됩니다. 내보내기에서는 RELEASE가 정의되어 있어 그 줄이 버려집니다.

  • 심볼에는 값이 없습니다. #DEFINE LEVEL 3은 거부되며, 매크로는 없습니다.
  • 그 줄부터 프로그램의 나머지에 적용되고, 그 뒤에 포함되는 파일에도 적용됩니다. 처음에 포함한 #DEFINE 모음 모듈은 설정 파일처럼 동작합니다.
  • 버려진 분기 안의 #DEFINE은 아무 일도 하지 않습니다.
  • #UNDEF는 프로파일 심볼도 제거합니다. #UNDEF DEBUG 뒤에는 에디터에서도 #IFDEF DEBUG가 거짓입니다.

타깃 프로파일#

프로그램을 컴파일하는 곳은 각각 심볼 집합, 곧 프로파일로 시작합니다.

프로그램이 컴파일되는 곳정의되는 심볼
에디터: Play, 미리보기ENGINE, WEB, DEBUG
HTML 내보내기HTML, WEB, RELEASE
Bevy 내보내기BEVY, RELEASE
#IF DEBUG
GLOBAL lives AS integer = 99
#ELSE
GLOBAL lives AS integer = 3
#ENDIF
Console(Str(lives))   ' 에디터에서는 99, 내보내기에서는 3
  • DEBUG는 에디터에만 있고, RELEASE는 모든 내보내기에 있습니다. 그래서 테스트용 단축 기능의 스위치로 자연스럽습니다.
  • 에디터에서만 동작하는 코드를 내보내기에서 빼려면 #IF ENGINE을 쓰세요.
  • 컴파일러는 더 좁은 두 가지 Bevy 프로파일 BEVY NATIVE RELEASE와 BEVY WASM WEB RELEASE도 압니다. 이 글을 쓰는 시점에 Bevy 내보내기는 일반 프로파일로 컴파일하므로, NATIVE나 WASM이 아니라 BEVY를 검사하세요.

다른 모든 것보다 먼저 실행됩니다#

전처리기는 위에서 아래로 한 번에 처리합니다.

  1. #IF 블록과 #DEFINE / #UNDEF가 줄 단위로 결정됩니다;
  2. 남은 #INCLUDE, #INSERT, IncludeFile 줄이 해당 파일로 대체되고, 그 파일도 같은 두 단계를 거칩니다;
  3. 그다음에야 컴파일러가 결과를 읽습니다. @expose, OPTION EXPLICIT, 명령어와 나머지 모두 그때입니다.

세 가지 결과가 따릅니다.

  • 버려진 분기 안의 파일은 읽히지 않습니다. 없어도 됩니다. "not found" 오류가 나지 않습니다.
  • 조건은 변수나 상수를 검사할 수 없습니다. 아직 존재하지 않기 때문입니다. 심볼만 가능합니다.
  • @expose 줄은 이 단계 뒤에 처리됩니다. 변수와 타입을 참고하세요.
#IF BEVY
#INCLUDE "bevy/only.bas"
#ENDIF
Console("compiled")   ' compiled

에디터에서는 bevy/only.bas가 존재하지 않아도 됩니다.

클래식 방언과의 비교#

방언가진 것aukimi에서는
AGK#include (한 번)와 #insert (매번)같은 단어, 같은 의미. 파일은 프로젝트 모듈입니다.
PureBasicIncludeFile (매번), XIncludeFile (한 번)IncludeFile은 같습니다. XIncludeFile은 거부됩니다. #INCLUDE라고 쓰세요.
PureBasic상수와 비교를 쓰는 CompilerIfCompilerIf는 심볼만 받습니다
C, FreeBASIC#define NAME value, 매크로#DEFINE은 값 없는 심볼을 정의합니다. 매크로는 없습니다.