Visualização em página única

Bem-vindo

Bem-vindo à documentação oficial do YueScript!
Aqui você encontra recursos da linguagem, uso, exemplos de referência e materiais úteis.
Selecione um capítulo na navegação para começar a aprender YueScript.

Introdução ao YueScript

YueScript é uma linguagem dinâmica que compila para Lua. É um dialeto do MoonScript. O código escrito em YueScript é expressivo e extremamente conciso. É adequado para escrever lógica de aplicação variável com código mais manutenível e roda em ambientes Lua embutidos, como jogos ou servidores web.

Yue (月) é o nome da lua em chinês e é pronunciado como [jyɛ].

Um gostinho de YueScript

-- sintaxe de importação
import p, to_lua from "yue"

-- literais de objeto
inventory =
  equipment:
    - "sword"
    - "shield"
  items:
    - name: "potion"
      count: 10
    - name: "bread"
      count: 3

-- compreensão de lista
map = (arr, action) ->
  [action item for item in *arr]

filter = (arr, cond) ->
  [item for item in *arr when cond item]

reduce = (arr, init, action): init ->
  init = action init, item for item in *arr

-- operador pipe
[1, 2, 3]
  |> map (x) -> x * 2
  |> filter (x) -> x > 4
  |> reduce 0, (a, b) -> a + b
  |> print

-- manipulação de metatable
apple =
  size: 15
  <index>:
    color: 0x00ffff

with apple
  p .size, .color, .<index> if .<>?

-- sintaxe de exportação estilo js
export 🌛 = "Script da Lua"

Compilar

Sobre o Dora SSR

O YueScript está sendo desenvolvido e mantido em conjunto com o motor de jogo open-source Dora SSR. Tem sido usado para criar ferramentas do motor, demonstrações de jogos e protótipos, validando suas capacidades em cenários do mundo real e aprimorando a experiência de desenvolvimento do Dora SSR.

Instalação

Módulo Lua

Instale o luarocks, um gerenciador de pacotes para módulos Lua. Em seguida, instale-o como módulo Lua e executável com:

luarocks install yuescript

Ou você pode compilar o arquivo yue.so com:

make shared LUAI=/usr/local/include/lua LUAL=/usr/local/lib/lua

Depois, obtenha o arquivo binário no caminho bin/shared/yue.so.

Compilar ferramenta binária

Clone este repositório e compile e instale o executável com:

make install

Compilar a ferramenta YueScript sem o recurso de macro:

make install NO_MACRO=true

Compilar a ferramenta YueScript sem o binário Lua embutido:

make install NO_LUA=true

Baixar binário pré-compilado

Você pode baixar arquivos binários pré-compilados, incluindo executáveis compatíveis com diferentes versões do Lua e arquivos de biblioteca.

Baixe os arquivos binários pré-compilados aqui.

Uso

Módulo Lua

Use o módulo YueScript em Lua:

• Caso 1

  Use require em “your_yuescript_entry.yue” no Lua.

  require("yue")("your_yuescript_entry")

  E esse código continua funcionando quando você compila “your_yuescript_entry.yue” para “your_yuescript_entry.lua” no mesmo caminho. Nos demais arquivos YueScript, use normalmente o require ou import. Os números de linha nas mensagens de erro também serão tratados corretamente.

• Caso 2

  Requerer o módulo YueScript e reescrever a mensagem manualmente.

  local yue = require("yue")
  yue.insert_loader()
  local success, result = xpcall(function()
    return require("yuescript_module_name")
  end, function(err)
    return yue.traceback(err)
  end)

• Caso 3

  Usar a função compiladora do YueScript em Lua.

  local yue = require("yue")
  local codes, err, globals = yue.to_lua([[
    f = ->
      print "hello world"
    f!
  ]],{
    implicit_return_root = true,
    reserve_line_number = true,
    lint_global = true,
    space_over_tab = false,
    options = {
      target = "5.4",
      path = "/script"
    }
  })

Ferramenta YueScript

Use a ferramenta YueScript com:

> yue -h
Usage: yue
       [options] [<file/directory>] ...
       yue -e <code_or_file> [args...]
       yue -w [<directory>] [options]
       yue -

Notas:
   - '-' / '--' deve ser o primeiro e único argumento.
   - '-o/--output' não pode ser usado com múltiplos arquivos de entrada.
   - '-w/--watch' não pode ser usado com entrada de arquivo (apenas diretório).
   - com '-e/--execute', os tokens restantes são tratados como argumentos do script.

Opções:
   -h, --help                 Mostrar esta mensagem de ajuda e sair.
   -e <str>, --execute <str>  Executar um arquivo ou código bruto
   -m, --minify               Gerar código minificado
   -r, --rewrite              Reescrever saída para corresponder aos números de linha originais
   -t <output_to>, --output-to <output_to>
                              Especificar onde colocar os arquivos compilados
   -o <file>, --output <file> Escrever saída em arquivo
   -p, --print                Escrever saída na saída padrão
   -b, --benchmark            Mostrar tempo de compilação (não grava saída)
   -g, --globals              Listar variáveis globais usadas em NOME LINHA COLUNA
   -s, --spaces               Usar espaços no código gerado em vez de tabulações
   -l, --line-numbers         Escrever números de linha do código fonte
   -j, --no-implicit-return   Desabilitar retorno implícito no final do arquivo
   -c, --reserve-comments     Preservar comentários antes de instruções do código fonte
   -w [<dir>], --watch [<dir>]
                              Observar alterações e compilar cada arquivo no diretório
   -v, --version              Imprimir versão
   -                          Ler da entrada padrão, imprimir na saída padrão
                              (Deve ser o primeiro e único argumento)
   --                         Igual a '-' (mantido para compatibilidade retroativa)

   --target <version>         Especificar a versão do Lua para a qual o código será gerado
                              (a versão pode ser apenas 5.1 a 5.5)
   --path <path_str>          Adicionar um caminho de busca Lua extra ao package.path
   --<key>=<value>            Passar opção do compilador no formato key=value (comportamento existente)

   Execute sem opções para entrar no REPL, digite o símbolo '$'
   em uma única linha para iniciar/parar o modo multilinha

Casos de uso:

Compilar recursivamente todos os arquivos YueScript com extensão .yue no caminho atual: yue .

Compilar e salvar resultados em um caminho de destino: yue -t /target/path/ .

Compilar e preservar informações de debug: yue -l .

Compilar e gerar código minificado: yue -m .

Executar código bruto: yue -e ‘print 123’

Executar um arquivo YueScript: yue -e main.yue

Espaço em branco

YueScript é uma linguagem sensível a espaço em branco. Você precisa escrever blocos de código na mesma indentação com espaço ’ ‘ ou tabulação ’\t’, como corpo de função, lista de valores e alguns blocos de controle. E expressões contendo diferentes espaços em branco podem significar coisas diferentes. Tabulação é tratada como 4 espaços, mas é melhor não misturar o uso de espaços e tabulações.

Separador de instrução

Uma instrução normalmente termina em uma quebra de linha. Você também pode usar ponto e vírgula ; para terminar explicitamente uma instrução, o que permite escrever múltiplas instruções na mesma linha:

a = 1; b = 2; print a + b

Compilar

Encadeamento multilinha

Você pode escrever chamadas de função encadeadas em múltiplas linhas com a mesma indentação.

Rx.Observable
  .fromRange 1, 8
  \filter (x) -> x % 2 == 0
  \concat Rx.Observable.of 'who do we appreciate'
  \map (value) -> value .. '!'
  \subscribe print

Compilar

Comentário

-- Eu sou um comentário

str = --[[
Este é um comentário multilinha.
Está OK.
]] strA \ -- comentário 1
  .. strB \ -- comentário 2
  .. strC

func --[[port]] 3000, --[[ip]] "192.168.1.1"

Compilar

Literais

Todos os literais primitivos do Lua podem ser usados. Isso se aplica a números, strings, booleanos e nil.

Diferente do Lua, quebras de linha são permitidas dentro de strings com aspas simples e duplas sem sequência de escape:

some_string = "Aqui está uma string
  que tem uma quebra de linha."

-- Você pode misturar expressões em literais de string usando a sintaxe #{}.
-- Interpolação de string está disponível apenas em strings com aspas duplas.
print "Tenho #{math.random! * 100}% de certeza."

Compilar

Literais numéricos

Você pode usar underscores em um literal numérico para aumentar a legibilidade.

integer = 1_000_000
hex = 0xEF_BB_BF
binary = 0B10011

Compilar

String multilinha estilo YAML

O prefixo | introduz um literal de string multilinha no estilo YAML:

str = |
  key: value
  list:
    - item1
    - #{expr}

Compilar

Isso permite escrever texto estruturado multilinha convenientemente. Todas as quebras de linha e indentação são preservadas em relação à primeira linha não vazia, e expressões dentro de #{...} são interpoladas automaticamente como tostring(expr).

A string multilinha YAML detecta automaticamente o prefixo comum de espaço em branco à esquerda (indentação mínima em todas as linhas não vazias) e remove-o de todas as linhas. Isso facilita a indentação visual do seu código sem afetar o conteúdo da string resultante.

fn = ->
  str = |
    foo:
      bar: baz
  return str

Compilar

A indentação interna é preservada em relação ao prefixo comum removido, permitindo estruturas aninhadas limpas.

Todos os caracteres especiais como aspas (") e barras invertidas (\) no bloco YAML Multiline são escapados automaticamente para que a string Lua gerada seja sintaticamente válida e se comporte como esperado.

str = |
  path: "C:\Program Files\App"
  note: 'Ele disse: "#{Hello}!"'

Compilar

Operador

Todos os operadores binários e unários do Lua estão disponíveis. Além disso, != é um alias para ~=, e \ ou :: podem ser usados para escrever uma chamada de função encadeada como tb\func! ou tb::func!. E o YueScript oferece alguns outros operadores especiais para escrever códigos mais expressivos.

tb\func! if tb ~= nil
tb::func! if tb != nil

Compilar

Comparações encadeadas

Comparações podem ser encadeadas arbitrariamente:

print 1 < 2 <= 2 < 3 == 3 > 2 >= 1 == 1 < 3 != 5
-- saída: true

a = 5
print 1 <= a <= 10
-- saída: true

Compilar

Observe o comportamento de avaliação das comparações encadeadas:

v = (x) ->
  print x
  x

print v(1) < v(2) <= v(3)
--[[
  saída:
  2
  1
  3
  true
]]

print v(1) > v(2) <= v(3)
--[[
  saída:
  2
  1
  false
]]

Compilar

A expressão do meio é avaliada apenas uma vez, em vez de duas vezes como seria se a expressão fosse escrita como v(1) < v(2) and v(2) <= v(3). No entanto, a ordem das avaliações em uma comparação encadeada é indefinida. É fortemente recomendado não usar expressões com efeitos colaterais (como impressão) em comparações encadeadas. Se efeitos colaterais forem necessários, o operador de curto-circuito and deve ser usado explicitamente.

Anexar à tabela

O operador [] = é usado para anexar valores a tabelas.

tab = []
tab[] = "Value"

Compilar

Você também pode usar o operador spread ... para anexar todos os elementos de uma lista a outra:

tbA = [1, 2, 3]
tbB = [4, 5, 6]
tbA[] = ...tbB
-- tbA agora é [1, 2, 3, 4, 5, 6]

Compilar

Spread de tabela

Você pode concatenar tabelas de array ou tabelas hash usando o operador spread ... antes de expressões em literais de tabela.

Ao fazer spread em um literal de tabela com chaves (por exemplo, {...other}), tanto a parte de array quanto a parte hash da tabela Lua são copiadas.

parts =
  * "shoulders"
  * "knees"
lyrics =
  * "head"
  * ...parts
  * "and"
  * "toes"

copy = {...other}

a = {1, 2, 3, x: 1}
b = {4, 5, y: 1}
merge = {...a, ...b}

Compilar

Spread de tabela de lista

Ao fazer spread em um literal de tabela com colchetes (por exemplo, [...other,]), apenas a parte de array é copiada.

source = {1, 2, 3, name: "Yue"}
fullCopy = {...source}
listCopy = [...source,]
-- fullCopy => {1, 2, 3, name: "Yue"}
-- listCopy => [1, 2, 3]

Compilar

Indexação reversa de tabela

Você pode usar o operador # para obter os últimos elementos de uma tabela.

last = data.items[#]
second_last = data.items[#-1]
data.items[#] = 1

Compilar

Metatable

O operador <> pode ser usado como atalho para manipulação de metatable.

Criação de metatable

Crie tabela normal com chaves vazias <> ou chave de metamétodo cercada por <>.

mt = {}
add = (right) => <>: mt, value: @value + right.value
mt.__add = add

a = <>: mt, value: 1
 -- definir campo com variável de mesmo nome
b = :<add>, value: 2
c = <add>: mt.__add, value: 3

d = a + b + c
print d.value

close _ = <close>: -> print "fora do escopo"

Compilar

Acesso à metatable

Acesse a metatable com <> ou nome do metamétodo cercado por <> ou escrevendo alguma expressão em <>.

-- criar com metatable contendo campo "value"
tb = <"value">: 123
tb.<index> = tb.<>
print tb.value

tb.<> = __index: {item: "hello"}
print tb.item

Compilar

Desestruturação de metatable

Desestruture a metatable com chave de metamétodo cercada por <>.

{item, :new, :<close>, <index>: getter} = tb
print item, new, close, getter

Compilar

Existência

O operador ? pode ser usado em diversos contextos para verificar existência.

func?!
print abc?["hello world"]?.xyz

x = tab?.value
len = utf8?.len or string?.len or (o) -> #o

if print and x?
  print x

with? io.open "test.txt", "w"
  \write "hello"
  \close!

Compilar

Pipe

Em vez de uma série de chamadas de função aninhadas, você pode encaminhar valores com o operador |>.

"hello" |> print
1 |> print 2 -- insere o item do pipe como primeiro argumento
2 |> print 1, _, 3 -- pipe com um placeholder

-- expressão pipe em multilinha
readFile "example.txt"
  |> extract language, {}
  |> parse language
  |> emit
  |> render
  |> print

Compilar

Coalescência de nil

O operador de coalescência de nil ?? retorna o valor do operando esquerdo se não for nil; caso contrário, avalia o operando direito e retorna seu resultado. O operador ?? não avalia seu operando direito se o operando esquerdo avaliar para não-nil.

local a, b, c, d
a = b ?? c ?? d
func a ?? {}

a ??= false

Compilar

Objeto implícito

Você pode escrever uma lista de estruturas implícitas que começa com o símbolo * ou - dentro de um bloco de tabela. Se você está criando objeto implícito, os campos do objeto devem estar com a mesma indentação.

-- atribuição com objeto implícito
list =
  * 1
  * 2
  * 3

-- chamada de função com objeto implícito
func
  * 1
  * 2
  * 3

-- retorno com objeto implícito
f = ->
  return
    * 1
    * 2
    * 3

-- tabela com objeto implícito
tb =
  name: "abc"

  values:
    - "a"
    - "b"
    - "c"

  objects:
    - name: "a"
      value: 1
      func: => @value + 1
      tb:
        fieldA: 1

    - name: "b"
      value: 2
      func: => @value + 2
      tb: { }

Compilar

Atributos

Suporte de sintaxe para atributos do Lua 5.4. E você ainda pode usar tanto a declaração const quanto close e obter verificação de constante e callback com escopo funcionando ao direcionar para versões do Lua abaixo da 5.4.

const a = 123
close _ = <close>: -> print "Fora do escopo."

Compilar

Você pode fazer desestruturação com variáveis atribuídas como constante.

const {:a, :b, c, d} = tb
-- a = 1

Compilar

Você também pode declarar uma variável global como const.

global const Constant = 123
-- Constant = 1

Compilar

Módulo

Import

A instrução import é um açúcar sintático para requerer um módulo ou ajudar a extrair itens de um módulo importado. Os itens importados são const por padrão.

-- usado como desestruturação de tabela
do
  import insert, concat from table
  -- reporta erro ao atribuir a insert, concat
  import C, Ct, Cmt from require "lpeg"
  -- atalho para require implícito
  import x, y, z from 'mymodule'
  -- import com estilo Python
  from 'module' import a, b, c

-- atalho para requerer um módulo
do
  import 'module'
  import 'module_x'
  import "d-a-s-h-e-s"
  import "module.part"

-- requerer módulo com aliasing ou desestruturação de tabela
do
  import "player" as PlayerModule
  import "lpeg" as :C, :Ct, :Cmt
  import "export" as {one, two, Something:{umm:{ch}}}

Compilar

Import Global

Você pode importar globais específicos para variáveis locais com import. Ao importar uma cadeia de acessos a variáveis globais, o último campo será atribuído à variável local.

do
  import tostring
  import table.concat
  print concat ["a", tostring 1]

Compilar

Importação automática de variável global

Você pode colocar import global no topo de um bloco para importar automaticamente todos os nomes que não foram explicitamente declarados ou atribuídos no escopo atual como globais. Essas importações implícitas são tratadas como consts locais que referenciam os globais correspondentes na posição da instrução.

Nomes que foram explicitamente declarados como globais no mesmo escopo não serão importados, então você ainda pode atribuir a eles.

do
  import global
  print "hello"
  math.random 3
  -- print = nil -- erro: globais importados são const

do
  -- variável global explícita não será importada
  import global
  global FLAG
  print FLAG
  FLAG = 123

Compilar

Export

A instrução export oferece uma forma concisa de definir módulos.

Export nomeado

Export nomeado definirá uma variável local e também adicionará um campo na tabela exportada.

export a, b, c = 1, 2, 3
export cool = "cat"

export What = if this
  "abc"
else
  "def"

export y = ->
  hallo = 3434

export class Something
  umm: "cool"

Compilar

Fazendo export nomeado com desestruturação.

export :loadstring, to_lua: tolua = yue
export {itemA: {:fieldA = 'default'}} = tb

Compilar

Exportar itens nomeados do módulo sem criar variáveis locais.

export.itemA = tb
export.<index> = items
export["a-b-c"] = 123

Compilar

Export sem nome

Export sem nome adicionará o item alvo na parte array da tabela exportada.

d, e, f = 3, 2, 1
export d, e, f

export if this
  123
else
  456

export with tmp
  j = 2000

Compilar

Export padrão

Usar a palavra-chave default na instrução export para substituir a tabela exportada por qualquer coisa.

export default ->
  print "hello"
  123

Compilar

Atribuição

A variável é tipada dinamicamente e é definida como local por padrão. Mas você pode alterar o escopo da declaração pelas instruções local e global.

hello = "world"
a, b, c = 1, 2, 3
hello = 123 -- usa a variável existente

Compilar

Atualização

Você pode realizar atribuição de atualização com muitos operadores binários.

x = 1
x += 1
x -= 1
x *= 10
x /= 10
x %= 10
s ..= "world" -- adiciona um novo local se a variável local não existir
arg or= "valor padrão"

Compilar

Atribuição encadeada

Você pode fazer atribuição encadeada para atribuir múltiplos itens ao mesmo valor.

a = b = c = d = e = 0
x = y = z = f!

Compilar

Locais explícitos

do
  local a = 1
  local *
  print "declarar antecipadamente todas as variáveis como locais"
  x = -> 1 + y + z
  y, z = 2, 3
  global instance = Item\new!

do
  local X = 1
  local ^
  print "declarar antecipadamente apenas variáveis em maiúsculas"
  a = 1
  B = 2

Compilar

Globais explícitos

do
  global a = 1
  global *
  print "declarar todas as variáveis como globais"
  x = -> 1 + y + z
  y, z = 2, 3

do
  global X = 1
  global ^
  print "declarar apenas variáveis em maiúsculas como globais"
  a = 1
  B = 2
  local Temp = "um valor local"

Compilar

Atribuição por desestruturação

A atribuição por desestruturação é uma forma de extrair rapidamente valores de uma tabela por seu nome ou posição em tabelas baseadas em array.

Tipicamente, quando você vê um literal de tabela, {1,2,3}, ele está no lado direito de uma atribuição porque é um valor. A atribuição por desestruturação troca o papel do literal de tabela e o coloca no lado esquerdo de uma instrução de atribuição.

Isso é melhor explicado com exemplos. Assim você extrairia os dois primeiros valores de uma tabela:

thing = [1, 2]

[a, b] = thing
print a, b

Compilar

No literal de tabela de desestruturação, a chave representa a chave para ler do lado direito, e o valor representa o nome ao qual o valor lido será atribuído.

obj = {
  hello: "world"
  day: "tuesday"
  length: 20
}

{hello: hello, day: the_day} = obj
print hello, the_day

:day = obj -- OK fazer desestruturação simples sem chaves

Compilar

Isso também funciona com estruturas de dados aninhadas:

obj2 = {
  numbers: [1, 2, 3, 4]
  properties: {
    color: "green"
    height: 13.5
  }
}

{numbers: [first, second], properties: {color: color}} = obj2
print first, second, color

Compilar

Se a instrução de desestruturação for complicada, sinta-se à vontade para espalhá-la em várias linhas. Um exemplo um pouco mais complicado:

{
  numbers: [first, second]
  properties: {
    color: color
  }
} = obj2

Compilar

É comum extrair valores de uma tabela e atribuí-los a variáveis locais que têm o mesmo nome da chave. Para evitar repetição, podemos usar o operador de prefixo ::

{:concat, :insert} = table

Compilar

Isso é efetivamente o mesmo que import, mas podemos renomear campos que queremos extrair misturando a sintaxe:

{:mix, :max, random: rand} = math

Compilar

Você pode escrever valores padrão ao fazer desestruturação:

{:name = "sem nome", :job = "sem emprego"} = person

Compilar

Você pode usar _ como placeholder ao fazer desestruturação de lista:

[_, two, _, four] = items

Compilar

Desestruturação por intervalo

Você pode usar o operador spread ... na desestruturação de lista para capturar um intervalo de valores. Isso é útil quando você quer extrair elementos específicos do início e do fim de uma lista enquanto coleta o restante entre eles.

orders = ["first", "second", "third", "fourth", "last"]
[first, ...bulk, last] = orders
print first  -- imprime: first
print bulk   -- imprime: {"second", "third", "fourth"}
print last   -- imprime: last

Compilar

O operador spread pode ser usado em diferentes posições para capturar diferentes intervalos, e você pode usar _ como placeholder para os valores que não quer capturar:

-- Capturar tudo após o primeiro elemento
[first, ...rest] = orders

-- Capturar tudo antes do último elemento
[...start, last] = orders

-- Capturar tudo exceto os elementos do meio
[first, ..._, last] = orders

Compilar

Desestruturação em outros lugares

A desestruturação também pode aparecer em lugares onde uma atribuição ocorre implicitamente. Um exemplo disso é um loop for:

tuples = [
  ["hello", "world"]
  ["egg", "head"]
]

for [left, right] in *tuples
  print left, right

Compilar

Sabemos que cada elemento na tabela array é uma tupla de dois itens, então podemos desempacotá-lo diretamente na cláusula de nomes da instrução for usando desestruturação.

Atribuição em if

Os blocos if e elseif podem receber uma atribuição no lugar de uma expressão condicional. Ao avaliar o condicional, a atribuição será realizada e o valor que foi atribuído será usado como expressão condicional. A variável atribuída está no escopo apenas para o corpo do condicional, ou seja, nunca está disponível se o valor não for truthy. E você precisa usar o “operador walrus” := em vez de = para fazer a atribuição.

if user := database.find_user "moon"
  print user.name

Compilar

if hello := os.getenv "hello"
  print "Você tem hello", hello
elseif world := os.getenv "world"
  print "você tem world", world
else
  print "nada :("

Compilar

Atribuição em if com múltiplos valores de retorno. Apenas o primeiro valor é verificado, os outros valores estão no escopo.

if success, result := pcall -> "obter resultado sem problemas"
  print result -- variável result está no escopo
print "OK"

Compilar

Atribuição em while

Você também pode usar atribuição em if em um loop while para obter o valor como condição do loop.

while byte := stream\read_one!
  -- fazer algo com o byte
  print byte

Compilar

Atribuição de varargs

Você pode atribuir os resultados retornados de uma função a um símbolo varargs .... E então acessar seu conteúdo da forma Lua.

list = [1, 2, 3, 4, 5]
fn = (ok) -> ok, table.unpack list
ok, ... = fn true
count = select '#', ...
first = select 1, ...
print ok, count, first

Compilar

A cláusula Using; controlando atribuição destrutiva

Embora o escopo léxico possa ser uma grande ajuda na redução da complexidade do código que escrevemos, as coisas podem ficar difíceis de gerenciar conforme o tamanho do código aumenta. Considere o seguinte trecho:

i = 100

-- muitas linhas de código...

my_func = ->
  i = 10
  while i > 0
    print i
    i -= 1

my_func!

print i -- vai imprimir 0

Compilar

Em my_func, sobrescrevemos o valor de i por engano. Neste exemplo é bem óbvio, mas considere uma base de código grande ou estrangeira onde não está claro quais nomes já foram declarados.

Seria útil dizer quais variáveis do escopo envolvente pretendemos alterar, para evitar que alteremos outras por acidente.

A palavra-chave using nos permite fazer isso. using nil garante que nenhuma variável fechada seja sobrescrita na atribuição. A cláusula using é colocada após a lista de argumentos em uma função, ou no lugar dela se não houver argumentos.

i = 100

my_func = (using nil) ->
  i = "hello" -- uma nova variável local é criada aqui

my_func!
print i -- imprime 100, i não é afetado

Compilar

Múltiplos nomes podem ser separados por vírgulas. Os valores do closure ainda podem ser acessados, apenas não podem ser modificados:

tmp = 1213
i, k = 100, 50

my_func = (add using k, i) ->
  tmp = tmp + add -- uma nova variável local tmp é criada
  i += tmp
  k += tmp

my_func(22)
print i, k -- estes foram atualizados

Compilar

Literais de função

Todas as funções são criadas usando uma expressão de função. Uma função simples é denotada usando a seta: ->.

my_function = ->
my_function() -- chama a função vazia

Compilar

O corpo da função pode ser uma instrução colocada diretamente após a seta, ou pode ser uma série de instruções indentadas nas linhas seguintes:

func_a = -> print "hello world"

func_b = ->
  value = 100
  print "The value:", value

Compilar

Se uma função não tem argumentos, ela pode ser chamada usando o operador !, em vez de parênteses vazios. A invocação ! é a forma preferida de chamar funções sem argumentos.

func_a!
func_b()

Compilar

Funções com argumentos podem ser criadas precedendo a seta com uma lista de nomes de argumentos entre parênteses:

sum = (x, y) -> print "sum", x + y

Compilar

Funções podem ser chamadas listando os argumentos após o nome de uma expressão que avalia para uma função. Ao encadear chamadas de função, os argumentos são aplicados à função mais próxima à esquerda.

sum 10, 20
print sum 10, 20

a b c "a", "b", "c"

Compilar

Para evitar ambiguidade ao chamar funções, parênteses também podem ser usados para envolver os argumentos. Isso é necessário aqui para garantir que os argumentos certos sejam enviados às funções certas.

print "x:", sum(10, 20), "y:", sum(30, 40)

Compilar

Não deve haver espaço entre o parêntese de abertura e a função.

As funções convertem a última instrução em seu corpo em uma instrução de retorno, isso é chamado de retorno implícito:

sum = (x, y) -> x + y
print "The sum is ", sum 10, 20

Compilar

E se você precisar retornar explicitamente, pode usar a palavra-chave return:

sum = (x, y) -> return x + y

Compilar

Assim como no Lua, as funções podem retornar múltiplos valores. A última instrução deve ser uma lista de valores separados por vírgulas:

mystery = (x, y) -> x + y, x - y
a, b = mystery 10, 20

Compilar

Setas fat

Como é um idioma em Lua enviar um objeto como primeiro argumento ao chamar um método, uma sintaxe especial é fornecida para criar funções que incluem automaticamente um argumento self.

func = (num) => @value + num

Compilar

Valores padrão de argumentos

É possível fornecer valores padrão para os argumentos de uma função. Um argumento é determinado como vazio se seu valor for nil. Qualquer argumento nil que tenha valor padrão será substituído antes da execução do corpo da função.

my_function = (name = "something", height = 100) ->
  print "Hello I am", name
  print "My height is", height

Compilar

Uma expressão de valor padrão de argumento é avaliada no corpo da função na ordem das declarações de argumentos. Por esse motivo, os valores padrão têm acesso aos argumentos declarados anteriormente.

some_args = (x = 100, y = x + 1000) ->
  print x + y

Compilar

Considerações

Devido à forma expressiva de chamar funções sem parênteses, algumas restrições devem ser colocadas para evitar ambiguidade de análise envolvendo espaço em branco.

O sinal de menos desempenha dois papéis: um operador de negação unário e um operador de subtração binário. Considere como os seguintes exemplos compilam:

a = x - 10
b = x-10
c = x -y
d = x- z

Compilar

A precedência do primeiro argumento de uma chamada de função pode ser controlada usando espaço em branco se o argumento for um literal de string. Em Lua, é comum omitir parênteses ao chamar uma função com uma única string ou literal de tabela.

Quando não há espaço entre uma variável e um literal de string, a chamada de função tem precedência sobre quaisquer expressões seguintes. Nenhum outro argumento pode ser passado para a função quando ela é chamada dessa forma.

Quando há um espaço após uma variável e um literal de string, a chamada de função age como mostrado acima. O literal de string pertence a quaisquer expressões seguintes (se existirem), que servem como lista de argumentos.

x = func"hello" + 100
y = func "hello" + 100

Compilar

Argumentos multilinha

Ao chamar funções que recebem um grande número de argumentos, é conveniente dividir a lista de argumentos em várias linhas. Devido à natureza sensível a espaço em branco da linguagem, deve-se ter cuidado ao dividir a lista de argumentos.

Se uma lista de argumentos for continuada na próxima linha, a linha atual deve terminar em vírgula. E a linha seguinte deve estar mais indentada que a indentação atual. Uma vez indentada, todas as outras linhas de argumentos devem estar no mesmo nível de indentação para fazer parte da lista de argumentos.

my_func 5, 4, 3,
  8, 9, 10

cool_func 1, 2,
  3, 4,
  5, 6,
  7, 8

Compilar

Este tipo de invocação pode ser aninhado. O nível de indentação é usado para determinar a qual função os argumentos pertencem.

my_func 5, 6, 7,
  6, another_func 6, 7, 8,
    9, 1, 2,
  5, 4

Compilar

Como as tabelas também usam vírgula como delimitador, esta sintaxe de indentação ajuda a deixar os valores fazerem parte da lista de argumentos em vez de fazerem parte da tabela.

x = [
  1, 2, 3, 4, a_func 4, 5,
    5, 6,
  8, 9, 10
]

Compilar

Embora incomum, observe como podemos dar uma indentação mais profunda para argumentos de função se soubermos que usaremos uma indentação menor mais adiante.

y = [ my_func 1, 2, 3,
   4, 5,
  5, 6, 7
]

Compilar

A mesma coisa pode ser feita com outras instruções em nível de bloco como condicionais. Podemos usar o nível de indentação para determinar a qual instrução um valor pertence:

if func 1, 2, 3,
  "hello",
  "world"
    print "hello"
    print "I am inside if"

if func 1, 2, 3,
    "hello",
    "world"
  print "hello"
  print "I am inside if"

Compilar

Desestruturação de parâmetros

YueScript agora suporta desestruturação de parâmetros de função quando o argumento é um objeto. Duas formas de literais de tabela de desestruturação estão disponíveis:

• Literais/parâmetros de objeto envolvidos em chaves, permitindo valores padrão opcionais quando os campos estão ausentes (ex.: {:a, :b}, {a: a1 = 123}).

• Sintaxe de tabela simples não envolvida, começando com uma sequência de ligações chave-valor ou abreviadas e continuando até outra expressão terminá-la (ex.: :a, b: b1, :c). Esta forma extrai múltiplos campos do mesmo objeto.

f1 = (:a, :b, :c) ->
  print a, b, c

f1 a: 1, b: "2", c: {}

f2 = ({a: a1 = 123, :b = 'abc'}, c = {}) ->
  print a1, b, c

arg1 = {a: 0}
f2 arg1, arg2

Compilar

Expressão de retorno prefixada

Ao trabalhar com corpos de função profundamente aninhados, pode ser tedioso manter a legibilidade e consistência do valor de retorno. Para resolver isso, YueScript introduz a sintaxe Expressão de Retorno Prefixada. Sua forma é a seguinte:

findFirstEven = (list): nil ->
  for item in *list
    if type(item) == "table"
      for sub in *item
        if sub % 2 == 0
          return sub

Compilar

Isso é equivalente a:

findFirstEven = (list) ->
  for item in *list
    if type(item) == "table"
      for sub in *item
        if sub % 2 == 0
          return sub
  nil

Compilar

A única diferença é que você pode mover a expressão de retorno final antes do token -> ou => para indicar o valor de retorno implícito da função como última instrução. Dessa forma, mesmo em funções com múltiplos loops aninhados ou ramificações condicionais, você não precisa mais escrever uma expressão de retorno no final do corpo da função, tornando a estrutura lógica mais direta e fácil de seguir.

Varargs nomeados

Você pode usar a sintaxe (...t) -> para armazenar automaticamente varargs em uma tabela nomeada. Esta tabela conterá todos os argumentos passados (incluindo valores nil), e o campo n da tabela armazenará o número real de argumentos passados (incluindo valores nil).

f = (...t) ->
  print "contagem de argumentos:", t.n
  print "comprimento da tabela:", #t
  for i = 1, t.n
    print t[i]

f 1, 2, 3
f "a", "b", "c", "d"
f!

-- Tratando casos com valores nil
process = (...args) ->
  sum = 0
  for i = 1, args.n
    if args[i] != nil and type(args[i]) == "number"
      sum += args[i]
  sum

process 1, nil, 3, nil, 5

Compilar

Backcalls

Backcalls são usados para desaninhar callbacks. Eles são definidos usando setas apontando para a esquerda como o último parâmetro, preenchendo por padrão uma chamada de função. Toda a sintaxe é basicamente a mesma das funções seta regulares, exceto que apenas aponta para o outro lado e o corpo da função não requer indentação.

x <- f
print "hello" .. x

Compilar

Funções seta “fat” também estão disponíveis.

<= f
print @value

Compilar

Você pode especificar um placeholder para onde deseja que a função backcall vá como parâmetro.

(x) <- map _, [1, 2, 3]
x * 2

Compilar

Se você desejar ter mais código após seus backcalls, pode colocá-los em uma instrução do. E os parênteses podem ser omitidos com funções seta não-fat.

result, msg = do
  data <- readAsync "filename.txt"
  print data
  info <- processAsync data
  check info
print result, msg

Compilar

Stubs de função

É comum passar uma função de um objeto como valor, por exemplo, passando um método de instância para uma função como callback. Se a função espera o objeto em que está operando como primeiro argumento, então você deve de alguma forma empacotar esse objeto com a função para que ela possa ser chamada corretamente.

A sintaxe de function stub é uma forma abreviada de criar uma nova função closure que empacota tanto o objeto quanto a função. Esta nova função chama a função empacotada no contexto correto do objeto.

Sua sintaxe é a mesma que chamar um método de instância com o operador , mas sem lista de argumentos fornecida.

my_object = {
  value: 1000
  write: => print "the value:", @value
}

run_callback = (func) ->
  print "running callback..."
  func!

-- isso não funcionará:
-- a função não tem referência a my_object
run_callback my_object.write

-- sintaxe de function stub
-- nos permite empacotar o objeto em uma nova função
run_callback my_object\write

Compilar

Condicionais

have_coins = false
if have_coins
  print "Tem moedas"
else
  print "Sem moedas"

Compilar

Uma sintaxe curta para instruções únicas também pode ser usada:

have_coins = false
if have_coins then print "Tem moedas" else print "Sem moedas"

Compilar

Como instruções if podem ser usadas como expressões, isso também pode ser escrito como:

have_coins = false
print if have_coins then "Tem moedas" else "Sem moedas"

Compilar

Condicionais também podem ser usados em instruções de retorno e atribuições:

is_tall = (name) ->
  if name == "Rob"
    true
  else
    false

message = if is_tall "Rob"
  "Sou muito alto"
else
  "Não sou tão alto"

print message -- imprime: Sou muito alto

Compilar

O oposto de if é unless:

unless os.date("%A") == "Monday"
  print "não é segunda-feira!"

Compilar

print "Você tem sorte!" unless math.random! > 0.1

Compilar

Em expressão

Você pode escrever código de verificação de intervalo com uma in-expression.

a = 5

if a in [1, 3, 5, 7]
  print "verificando igualdade com valores discretos"

if a in list
  print "verificando se `a` está na lista"

Compilar

O operador in também pode ser usado com tabelas e suporta a variante not in para negação:

has = "foo" in {"bar", "foo"}

if a in {1, 2, 3}
  print "a está na tabela"

not_exist = item not in list

check = -> value not in table

Compilar

Uma lista ou tabela de único elemento verifica igualdade com esse elemento:

-- [1,] verifica se valor == 1
c = a in [1,]

-- {1} também verifica se valor == 1
c = a in {1}

-- Sem vírgula, [1] é acesso por índice (tb[1])
with tb
  c = a in [1]

Compilar

Loop For

Existem duas formas de loop for, assim como no Lua. Uma numérica e uma genérica:

for i = 10, 20
  print i

for k = 1, 15, 2 -- um passo opcional fornecido
  print k

for key, value in pairs object
  print key, value

Compilar

Os operadores de slicing e * podem ser usados, assim como com compreensões:

for item in *items[2, 4]
  print item

Compilar

Uma sintaxe mais curta também está disponível para todas as variações quando o corpo é apenas uma linha:

for item in *items do print item

for j = 1, 10, 3 do print j

Compilar

Um loop for também pode ser usado como expressão. A última instrução no corpo do loop for é convertida em expressão e anexada a uma tabela array acumuladora.

Dobrando cada número par:

doubled_evens = for i = 1, 20
  if i % 2 == 0
    i * 2
  else
    i

Compilar

Além disso, os loops for suportam break com valores de retorno, permitindo que o próprio loop seja usado como expressão que sai antecipadamente com um resultado significativo. Expressões for suportam break com múltiplos valores.

Por exemplo, para encontrar o primeiro número maior que 10:

first_large = for n in *numbers
  break n if n > 10

Compilar

Esta sintaxe de break-com-valor permite padrões concisos e expressivos de busca ou saída antecipada diretamente em expressões de loop.

key, score = for k, v in pairs data
  break k, v * 10 if k == "target"

Compilar

Você também pode filtrar valores combinando a expressão do loop for com a instrução continue.

Loops for no final do corpo de uma função não são acumulados em uma tabela para valor de retorno (em vez disso, a função retornará nil). Uma instrução return explícita pode ser usada, ou o loop pode ser convertido em compreensão de lista.

func_a = -> for i = 1, 10 do print i
func_b = -> return for i = 1, 10 do i

print func_a! -- imprime nil
print func_b! -- imprime objeto table

Compilar

Isso é feito para evitar a criação desnecessária de tabelas para funções que não precisam retornar os resultados do loop.

Loop While

O loop while também vem em quatro variações:

i = 10
while i > 0
  print i
  i -= 1

while running == true do my_function!

Compilar

i = 10
until i == 0
  print i
  i -= 1

until running == false do my_function!

Compilar

Como os loops for, o loop while também pode ser usado como expressão. Expressões while e until suportam break com múltiplos valores.

value, doubled = while true
  n = get_next!
  break n, n * 2 if n > 10

Compilar

Além disso, para uma função retornar o valor acumulado de um loop while, a instrução deve ser explicitamente retornada.

Loop Repeat

O loop repeat vem do Lua:

i = 10
repeat
  print i
  i -= 1
until i == 0

Compilar

Expressões repeat também suportam break com múltiplos valores:

i = 1
value, scaled = repeat
  break i, i * 100 if i > 3
  i += 1
until false

Compilar

Continue

Uma instrução continue pode ser usada para pular a iteração atual em um loop.

i = 0
while i < 10
  i += 1
  continue if i % 2 == 0
  print i

Compilar

continue também pode ser usado com expressões de loop para impedir que essa iteração seja acumulada no resultado. Este exemplo filtra a tabela array para apenas números pares:

my_numbers = [1, 2, 3, 4, 5, 6]
odds = for x in *my_numbers
  continue if x % 2 == 1
  x

Compilar

Goto

YueScript suporta a instrução goto e a sintaxe de rótulos para controlar o fluxo do programa, seguindo as mesmas regras da instrução goto do Lua. Nota: A instrução goto requer Lua 5.2 ou superior. Ao compilar para Lua 5.1, o uso da sintaxe goto resultará em um erro de compilação.

Um rótulo é definido usando dois pontos duplos:

::inicio::
::fim::
::meu_rotulo::

Compilar

A instrução goto salta para um rótulo especificado:

a = 0
::inicio::
a += 1
goto fim if a == 5
goto inicio
::fim::
print "a agora é 5"

Compilar

A instrução goto é útil para sair de laços profundamente aninhados:

for z = 1, 10
  for y = 1, 10 do for x = 1, 10
    if x^2 + y^2 == z^2
      print 'triplo pitagórico encontrado:', x, y, z
      goto ok
::ok::

Compilar

Você também pode usar rótulos para pular para um nível específico de laço:

for z = 1, 10
  for y = 1, 10
    for x = 1, 10
      if x^2 + y^2 == z^2
        print 'triplo pitagórico encontrado:', x, y, z
        print 'tentando próximo z...'
        goto zcontinue
  ::zcontinue::

Compilar

Notas

• Rótulos devem ser únicos dentro de seu escopo
• goto pode pular para rótulos nos mesmos níveis de escopo ou externos
• goto não pode pular para escopos internos (como dentro de blocos ou laços)
• Use goto com moderação, pois pode tornar o código mais difícil de ler e manter

Switch

A instrução switch é uma forma abreviada de escrever uma série de instruções if que verificam o mesmo valor. Observe que o valor é avaliado apenas uma vez. Como as instruções if, os switches podem ter um bloco else para tratar ausência de correspondências. A comparação é feita com o operador ==. Na instrução switch, você também pode usar expressão de atribuição para armazenar valor de variável temporária.

switch name := "Dan"
  when "Robert"
    print "Você é Robert"
  when "Dan", "Daniel"
    print "Seu nome é Dan"
  else
    print "Não sei quem você é com o nome #{name}"

Compilar

Uma cláusula when de um switch pode corresponder a múltiplos valores listando-os separados por vírgula.

Os switches também podem ser usados como expressões; aqui podemos atribuir o resultado do switch a uma variável:

b = 1
next_number = switch b
  when 1
    2
  when 2
    3
  else
    error "não consigo contar tão alto!"

Compilar

Podemos usar a palavra-chave then para escrever o bloco when de um switch em uma única linha. Nenhuma palavra-chave extra é necessária para escrever o bloco else em uma única linha.

msg = switch math.random(1, 5)
  when 1 then "você tem sorte"
  when 2 then "você quase tem sorte"
  else "não tão sortudo"

Compilar

Se você quiser escrever código com uma indentação a menos ao escrever uma instrução switch, pode colocar a primeira cláusula when na linha de início da instrução, e então todas as outras cláusulas podem ser escritas com uma indentação a menos.

switch math.random(1, 5)
  when 1
    print "você tem sorte" -- duas indentações
  else
    print "não tão sortudo"

switch math.random(1, 5) when 1
  print "você tem sorte" -- uma indentação
else
  print "não tão sortudo"

Compilar

Vale notar a ordem da expressão de comparação do case. A expressão do case está no lado esquerdo. Isso pode ser útil se a expressão do case quiser sobrescrever como a comparação é feita definindo um metamétodo eq.

Correspondência de tabela

Você pode fazer correspondência de tabela em uma cláusula when de switch, se a tabela puder ser desestruturada por uma estrutura específica e obter valores não-nil.

items =
  * x: 100
    y: 200
  * width: 300
    height: 400

for item in *items
  switch item
    when :x, :y
      print "Vec2 #{x}, #{y}"
    when :width, :height
      print "tamanho #{width}, #{height}"

Compilar

Você pode usar valores padrão para opcionalmente desestruturar a tabela para alguns campos.

item = {}

{pos: {:x = 50, :y = 200}} = item -- obtém erro: attempt to index a nil value (field 'pos')

switch item
  when {pos: {:x = 50, :y = 200}}
    print "Vec2 #{x}, #{y}" -- a desestruturação de tabela ainda passará

Compilar

Você também pode corresponder contra elementos de array, campos de tabela, e até estruturas aninhadas com literais de array ou tabela.

Corresponder contra elementos de array.

switch tb
  when [1, 2, 3]
    print "1, 2, 3"
  when [1, b, 3]
    print "1, #{b}, 3"
  when [1, 2, b = 3] -- b tem valor padrão
    print "1, 2, #{b}"

Compilar

Corresponder contra campos de tabela com desestruturação.

switch tb
  when success: true, :result
    print "sucesso", result
  when success: false
    print "falhou", result
  else
    print "inválido"

Compilar

Corresponder contra estruturas de tabela aninhadas.

switch tb
  when data: {type: "success", :content}
    print "sucesso", content
  when data: {type: "error", :content}
    print "erro", content
  else
    print "inválido"

Compilar

Corresponder contra array de tabelas.

switch tb
  when [
      {a: 1, b: 2}
      {a: 3, b: 4}
      {a: 5, b: 6}
      fourth
    ]
    print "correspondido", fourth

Compilar

Corresponder contra uma lista e capturar um intervalo de elementos.

segments = ["admin", "users", "logs", "view"]
switch segments
  when [...groups, resource, action]
    print "Grupo:", groups -- imprime: {"admin", "users"}
    print "Recurso:", resource -- imprime: "logs"
    print "Ação:", action -- imprime: "view"

Compilar

Literais de tabela

Como no Lua, as tabelas são delimitadas por chaves.

some_values = {1, 2, 3, 4}

Compilar

Diferente do Lua, atribuir um valor a uma chave em uma tabela é feito com : (em vez de =).

some_values = {
  name: "Bill",
  age: 200,
  ["favorite food"]: "rice"
}

Compilar

As chaves podem ser omitidas se uma única tabela de pares chave-valor está sendo atribuída.

profile =
  height: "4 feet",
  shoe_size: 13,
  favorite_foods: ["ice cream", "donuts"]

Compilar

Quebras de linha podem ser usadas para delimitar valores em vez de vírgula (ou ambos):

values = {
  1, 2, 3, 4
  5, 6, 7, 8
  name: "superman"
  occupation: "crime fighting"
}

Compilar

Ao criar um literal de tabela em uma única linha, as chaves também podem ser omitidas:

my_function dance: "Tango", partner: "none"

y = type: "dog", legs: 4, tails: 1

Compilar

As chaves de um literal de tabela podem ser palavras-chave da linguagem sem precisar escapar:

tbl = {
  do: "something"
  end: "hunger"
}

Compilar

Se você está construindo uma tabela a partir de variáveis e deseja que as chaves sejam iguais aos nomes das variáveis, então o operador de prefixo : pode ser usado:

hair = "golden"
height = 200
person = { :hair, :height, shoe_size: 40 }

print_table :hair, :height

Compilar

Se você quiser que a chave de um campo na tabela seja o resultado de uma expressão, então pode envolvê-la em [ ], assim como no Lua. Você também pode usar um literal de string diretamente como chave, omitindo os colchetes. Isso é útil se sua chave tiver caracteres especiais.

t = {
  [1 + 2]: "hello"
  "hello world": true
}

Compilar

As tabelas Lua têm tanto uma parte array quanto uma parte hash, mas às vezes é útil fazer uma distinção semântica entre as duas. Você pode usar [ ] em vez de { } para declarar explicitamente uma tabela como um array, fazer isso impedirá que quaisquer pares chave-valor sejam escritos dentro dela.

some_values = [1, 2, 3, 4]
list_with_one_element = [1, ]

Compilar

Compreensões

As compreensões fornecem uma sintaxe conveniente para construir uma nova tabela iterando sobre algum objeto existente e aplicando uma expressão a seus valores. Existem dois tipos de compreensões: compreensões de lista e compreensões de tabela. Ambas produzem tabelas Lua; as compreensões de lista acumulam valores em uma tabela semelhante a array, e as compreensões de tabela permitem definir tanto a chave quanto o valor em cada iteração.

Compreensões de lista

O seguinte cria uma cópia da tabela items mas com todos os valores dobrados.

items = [ 1, 2, 3, 4 ]
doubled = [item * 2 for i, item in ipairs items]

Compilar

Os itens incluídos na nova tabela podem ser restringidos com uma cláusula when:

slice = [item for i, item in ipairs items when i > 1 and i < 3]

Compilar

Como é comum iterar sobre os valores de uma tabela indexada numericamente, um operador * é introduzido. O exemplo doubled pode ser reescrito como:

doubled = [item * 2 for item in *items]

Compilar

Nas compreensões de lista, você também pode usar o operador spread ... para achatar listas aninhadas, alcançando um efeito de flat map:

data =
  a: [1, 2, 3]
  b: [4, 5, 6]

flat = [...v for k,v in pairs data]
-- flat agora é [1, 2, 3, 4, 5, 6]

Compilar

As cláusulas for e when podem ser encadeadas tanto quanto desejado. O único requisito é que uma compreensão tenha pelo menos uma cláusula for.

Usar múltiplas cláusulas for é o mesmo que usar loops aninhados:

x_coords = [4, 5, 6, 7]
y_coords = [9, 2, 3]

points = [ [x, y] for x in *x_coords \
for y in *y_coords]

Compilar

Loops for numéricos também podem ser usados em compreensões:

evens = [i for i = 1, 100 when i % 2 == 0]

Compilar

Compreensões de tabela

A sintaxe para compreensões de tabela é muito semelhante, diferindo apenas por usar { e } e receber dois valores de cada iteração.

Este exemplo faz uma cópia da tabela thing:

thing = {
  color: "red"
  name: "fast"
  width: 123
}

thing_copy = {k, v for k, v in pairs thing}

Compilar

no_color = {k, v for k, v in pairs thing when k != "color"}

Compilar

O operador * também é suportado. Aqui criamos uma tabela de consulta de raiz quadrada para alguns números.

numbers = [1, 2, 3, 4]
sqrts = {i, math.sqrt i for i in *numbers}

Compilar

A tupla chave-valor em uma compreensão de tabela também pode vir de uma única expressão, caso em que a expressão deve retornar dois valores. O primeiro é usado como chave e o segundo é usado como valor:

Neste exemplo convertemos um array de pares em uma tabela onde o primeiro item do par é a chave e o segundo é o valor.

tuples = [ ["hello", "world"], ["foo", "bar"]]
tbl = {unpack tuple for tuple in *tuples}

Compilar

Slicing

Uma sintaxe especial é fornecida para restringir os itens sobre os quais se itera ao usar o operador *. Isso é equivalente a definir os limites de iteração e um tamanho de passo em um loop for.

Aqui podemos definir os limites mínimo e máximo, pegando todos os itens com índices entre 1 e 5 inclusive:

slice = [item for item in *items[1, 5]]

Compilar

Qualquer um dos argumentos do slice pode ser omitido para usar um padrão sensato. Neste exemplo, se o índice máximo for omitido, ele usa como padrão o comprimento da tabela. Isso pegará tudo exceto o primeiro elemento:

slice = [item for item in *items[2,]]

Compilar

Se o limite mínimo for omitido, ele usa como padrão 1. Aqui fornecemos apenas um tamanho de passo e deixamos os outros limites em branco. Isso pega todos os itens com índice ímpar: (1, 3, 5, …)

slice = [item for item in *items[,,2]]

Compilar

Tanto o limite mínimo quanto o máximo podem ser negativos, o que significa que os limites são contados a partir do fim da tabela.

-- pegar os últimos 4 itens
slice = [item for item in *items[-4,-1]]

Compilar

O tamanho do passo também pode ser negativo, o que significa que os itens são tomados em ordem reversa.

reverse_slice = [item for item in *items[-1,1,-1]]

Compilar

Expressão de slicing

O slicing também pode ser usado como expressão. Isso é útil para obter uma sublista de uma tabela.

-- pegar o 2º e 4º itens como nova lista
sub_list = items[2, 4]

-- pegar os últimos 4 itens
last_four_items = items[-4, -1]

Compilar

Programação orientada a objetos

Nestes exemplos, o código Lua gerado pode parecer avassalador. É melhor focar primeiro no significado do código YueScript e depois olhar o código Lua se desejar conhecer os detalhes da implementação.

Uma classe simples:

class Inventory
  new: =>
    @items = {}

  add_item: (name) =>
    if @items[name]
      @items[name] += 1
    else
      @items[name] = 1

Compilar

Uma classe é declarada com uma instrução class seguida de uma declaração semelhante a tabela onde todos os métodos e propriedades são listados.

A propriedade new é especial pois se tornará o construtor.

Observe como todos os métodos da classe usam a sintaxe de função seta fat. Ao chamar métodos em uma instância, a própria instância é enviada como primeiro argumento. A seta fat cuida da criação do argumento self.

O prefixo @ em um nome de variável é abreviação para self.. @items torna-se self.items.

O bloco da classe também suporta campos de metatable escrevendo chaves de metamétodo entre <>, como <tostring>.

class User
  new: (@name) =>
  <tostring>: => "User(#{@name})"

print tostring User "Yue"

Compilar

Criar uma instância da classe é feito chamando o nome da classe como uma função.

inv = Inventory!
inv\add_item "t-shirt"
inv\add_item "pants"

Compilar

Como a instância da classe precisa ser enviada aos métodos quando são chamados, o operador \ é usado.

Todas as propriedades de uma classe são compartilhadas entre as instâncias. Isso é bom para funções, mas para outros tipos de objetos, resultados indesejados podem ocorrer.

Considere o exemplo abaixo, a propriedade clothes é compartilhada entre todas as instâncias, então modificações nela em uma instância aparecerão em outra:

class Person
  clothes: []
  give_item: (name) =>
    table.insert @clothes, name

a = Person!
b = Person!

a\give_item "pants"
b\give_item "shirt"

-- vai imprimir tanto pants quanto shirt
print item for item in *a.clothes

Compilar

A forma correta de evitar esse problema é criar o estado mutável do objeto no construtor:

class Person
  new: =>
    @clothes = []

Compilar

Herança

A palavra-chave extends pode ser usada em uma declaração de classe para herdar as propriedades e métodos de outra classe.

class BackPack extends Inventory
  size: 10
  add_item: (name) =>
    if #@items > size then error "backpack is full"
    super name

Compilar

Aqui estendemos nossa classe Inventory e limitamos a quantidade de itens que ela pode carregar.

Neste exemplo, não definimos um construtor na subclasse, então o construtor da classe pai é chamado quando criamos uma nova instância. Se definirmos um construtor, podemos usar o método super para chamar o construtor pai.

Sempre que uma classe herda de outra, ela envia uma mensagem à classe pai chamando o método __inherited na classe pai se ele existir. A função recebe dois argumentos: a classe que está sendo herdada e a classe filha.

class Shelf
  @__inherited: (child) =>
    print @__name, "was inherited by", child.__name

-- vai imprimir: Shelf was inherited by Cupboard
class Cupboard extends Shelf

Compilar

Super

super é uma palavra-chave especial que pode ser usada de duas formas diferentes: pode ser tratado como um objeto, ou pode ser chamado como uma função. Só tem funcionalidade especial quando está dentro de uma classe.

Quando chamado como função, chamará a função de mesmo nome na classe pai. O self atual será automaticamente passado como primeiro argumento. (Como visto no exemplo de herança acima)

Quando super é usado como valor normal, é uma referência ao objeto da classe pai.

Pode ser acessado como qualquer objeto para recuperar valores na classe pai que possam ter sido sombreados pela classe filha.

Quando o operador de chamada \ é usado com super, self é inserido como primeiro argumento em vez do valor do próprio super. Ao usar . para recuperar uma função, a função bruta é retornada.

Alguns exemplos de uso de super de diferentes formas:

class MyClass extends ParentClass
  a_method: =>
    -- os seguintes têm o mesmo efeito:
    super "hello", "world"
    super\a_method "hello", "world"
    super.a_method self, "hello", "world"

    -- super como valor é igual à classe pai:
    assert super == ParentClass

Compilar

super também pode ser usado no lado esquerdo de um Function Stub. A única diferença principal é que, em vez da função resultante estar vinculada ao valor de super, ela está vinculada a self.

Tipos

Cada instância de uma classe carrega seu tipo consigo. Isso é armazenado na propriedade especial __class. Esta propriedade contém o objeto da classe. O objeto da classe é o que chamamos para construir uma nova instância. Também podemos indexar o objeto da classe para recuperar métodos e propriedades da classe.

b = BackPack!
assert b.__class == BackPack

print BackPack.size -- imprime 10

Compilar

Objetos de classe

O objeto da classe é o que criamos quando usamos uma instrução class. O objeto da classe é armazenado em uma variável com o mesmo nome da classe.

O objeto da classe pode ser chamado como uma função para criar novas instâncias. É assim que criamos instâncias de classes nos exemplos acima.

Uma classe é composta por duas tabelas. A própria tabela da classe e a tabela base. A base é usada como metatable para todas as instâncias. Todas as propriedades listadas na declaração da classe são colocadas na base.

A metatable do objeto da classe lê propriedades da base se não existirem no objeto da classe. Isso significa que podemos acessar funções e propriedades diretamente da classe.

É importante notar que atribuir ao objeto da classe não atribui à base, então não é uma forma válida de adicionar novos métodos às instâncias. Em vez disso, a base deve ser alterada explicitamente. Veja o campo __base abaixo.

O objeto da classe tem algumas propriedades especiais:

O nome da classe quando foi declarada é armazenado como string no campo __name do objeto da classe.

print BackPack.__name -- imprime Backpack

Compilar

O objeto base é armazenado em __base. Podemos modificar esta tabela para adicionar funcionalidade a instâncias que já foram criadas e às que ainda serão criadas.

Se a classe estende de algo, o objeto da classe pai é armazenado em __parent.

Variáveis de classe

Podemos criar variáveis diretamente no objeto da classe em vez da base usando @ na frente do nome da propriedade em uma declaração de classe.

class Things
  @some_func: => print "Hello from", @__name

Things\some_func!

-- variáveis de classe não visíveis em instâncias
assert Things().some_func == nil

Compilar

Em expressões, podemos usar @@ para acessar um valor armazenado no **class de self. Assim, @@hello é abreviação para self.**class.hello.

class Counter
  @count: 0

  new: =>
    @@count += 1

Counter!
Counter!

print Counter.count -- imprime 2

Compilar

A semântica de chamada de @@ é semelhante a @. Chamar um nome @@ passará a classe como primeiro argumento usando a sintaxe de dois pontos do Lua.

@@hello 1,2,3,4

Compilar

Instruções de declaração de classe

No corpo de uma declaração de classe, podemos ter expressões normais além de pares chave/valor. Neste contexto, self é igual ao objeto da classe.

Aqui está uma forma alternativa de criar variável de classe comparada ao descrito acima:

class Things
  @class_var = "hello world"

Compilar

Estas expressões são executadas após todas as propriedades terem sido adicionadas à base.

Todas as variáveis declaradas no corpo da classe são locais às propriedades da classe. Isso é conveniente para colocar valores privados ou funções auxiliares que apenas os métodos da classe podem acessar:

class MoreThings
  secret = 123
  log = (msg) -> print "LOG:", msg

  some_method: =>
    log "hello world: " .. secret

Compilar

Valores @ e @@

Quando @ e @@ são prefixados na frente de um nome, eles representam, respectivamente, esse nome acessado em self e self.__class.

Se forem usados sozinhos, são aliases para self e self.__class.

assert @ == self
assert @@ == self.__class

Compilar

Por exemplo, uma forma rápida de criar uma nova instância da mesma classe a partir de um método de instância usando @@:

some_instance_method = (...) => @@ ...

Compilar

Promoção de propriedade no construtor

Para reduzir o código repetitivo na definição de objetos de valor simples. Você pode escrever uma classe simples como:

class Something
  new: (@foo, @bar, @@biz, @@baz) =>

-- O que é abreviação para

class Something
  new: (foo, bar, biz, baz) =>
    @foo = foo
    @bar = bar
    @@biz = biz
    @@baz = baz

Compilar

Você também pode usar esta sintaxe para uma função comum para inicializar os campos de um objeto.

new = (@fieldA, @fieldB) => @
obj = new {}, 123, "abc"
print obj

Compilar

Expressões de classe

A sintaxe de classe também pode ser usada como expressão que pode ser atribuída a uma variável ou retornada explicitamente.

x = class Bucket
  drops: 0
  add_drop: => @drops += 1

Compilar

Classes anônimas

O nome pode ser omitido ao declarar uma classe. O atributo __name será nil, a menos que a expressão da classe esteja em uma atribuição. O nome no lado esquerdo da atribuição é usado em vez de nil.

BigBucket = class extends Bucket
  add_drop: => @drops += 10

assert Bucket.__name == "BigBucket"

Compilar

Você pode até omitir o corpo, significando que pode escrever uma classe anônima em branco assim:

x = class

Compilar

Mistura de classes

Você pode fazer mistura com a palavra-chave using para copiar funções de uma tabela simples ou de um objeto de classe predefinido para sua nova classe. Ao fazer mistura com uma tabela simples, você pode sobrescrever a função de indexação da classe (metamétodo __index) para sua implementação personalizada. Ao fazer mistura com um objeto de classe existente, os metamétodos do objeto da classe não serão copiados.

MyIndex = __index: var: 1

class X using MyIndex
  func: =>
    print 123

x = X!
print x.var

class Y using X

y = Y!
y\func!

assert y.__class.__parent ~= X -- X não é pai de Y

Compilar

Instrução With

Um padrão comum envolvendo a criação de um objeto é chamar uma série de funções e definir uma série de propriedades imediatamente após criá-lo.

Isso resulta em repetir o nome do objeto várias vezes no código, adicionando ruído desnecessário. Uma solução comum para isso é passar uma tabela como argumento que contém uma coleção de chaves e valores para sobrescrever. O inconveniente é que o construtor desse objeto deve suportar essa forma.

O bloco with ajuda a aliviar isso. Dentro de um bloco with podemos usar instruções especiais que começam com . ou \ que representam essas operações aplicadas ao objeto com o qual estamos usando with.

Por exemplo, trabalhamos com um objeto recém-criado:

with Person!
  .name = "Oswald"
  \add_relative my_dad
  \save!
  print .name

Compilar

A instrução with também pode ser usada como expressão que retorna o valor ao qual foi dado acesso.

file = with File "favorite_foods.txt"
  \set_encoding "utf8"

Compilar

Expressões with suportam break com um valor:

result = with obj
  break .value

Compilar

Depois que break value é usado dentro de with, a expressão with deixa de retornar seu objeto-alvo e passa a retornar o valor de break.

a = with obj
  .x = 1
-- a é obj

b = with obj
  break .x
-- b é .x, não obj

Compilar

Diferente de for / while / repeat / do, with suporta apenas um valor de break.

Ou…

create_person = (name,  relatives) ->
  with Person!
    .name = name
    \add_relative relative for relative in *relatives

me = create_person "Leaf", [dad, mother, sister]

Compilar

Neste uso, with pode ser visto como uma forma especial do combinador K.

A expressão na instrução with também pode ser uma atribuição, se você quiser dar um nome à expressão.

with str := "Hello"
  print "original:", str
  print "upper:", \upper!

Compilar

Você pode acessar chaves especiais com [] em uma instrução with.

with tb
  [1] = 1
  print [2]
  with [abc]
    [3] = [2]\func!
    ["key-name"] = value
  [] = "abc" -- anexando a "tb"

Compilar

with? é uma versão aprimorada da sintaxe with, que introduz uma verificação existencial para acessar com segurança objetos que podem ser nil sem verificações explícitas de null.

with? obj
  print .name

Compilar

Macro

Uso comum

A função macro é usada para avaliar uma string em tempo de compilação e inserir os códigos gerados na compilação final.

macro PI2 = -> math.pi * 2
area = $PI2 * 5

macro HELLO = -> "'hello world'"
print $HELLO

macro config = (debugging) ->
  global debugMode = debugging == "true"
  ""

macro asserts = (cond) ->
  debugMode and "assert #{cond}" or ""

macro assert = (cond) ->
  debugMode and "assert #{cond}" or "#{cond}"

$config true
$asserts item ~= nil

$config false
value = $assert item

-- as expressões passadas são tratadas como strings
macro and = (...) -> "#{ table.concat {...}, ' and ' }"
if $and f1!, f2!, f3!
  print "OK"

Compilar

Inserir códigos brutos

Uma função macro pode retornar uma string YueScript ou uma tabela de configuração contendo códigos Lua.

macro yueFunc = (var) -> "local #{var} = ->"
$yueFunc funcA
funcA = -> "fail to assign to the Yue macro defined variable"

macro luaFunc = (var) -> {
  code: "local function #{var}() end"
  type: "lua"
}
$luaFunc funcB
funcB = -> "fail to assign to the Lua macro defined variable"

macro lua = (code) -> {
  :code
  type: "lua"
}

-- os símbolos inicial e final da string bruta são aparados automaticamente
$lua[==[
-- inserção de códigos Lua brutos
if cond then
  print("output")
end
]==]

Compilar

Exportar macro

Funções macro podem ser exportadas de um módulo e importadas em outro módulo. Você deve colocar funções export macro em um único arquivo para uso, e apenas definição de macro, importação de macro e expansão de macro inline podem ser colocadas no módulo exportador de macro.

-- arquivo: utils.yue
export macro map = (items, action) -> "[#{action} for _ in *#{items}]"
export macro filter = (items, action) -> "[_ for _ in *#{items} when #{action}]"
export macro foreach = (items, action) -> "for _ in *#{items}
  #{action}"

-- arquivo main.yue
import "utils" as {
  $, -- símbolo para importar todas as macros
  $foreach: $each -- renomear macro $foreach para $each
}
[1, 2, 3] |> $map(_ * 2) |> $filter(_ > 4) |> $each print _

Compilar

Macro embutida

Existem algumas macros embutidas, mas você pode sobrescrevê-las declarando macros com os mesmos nomes.

print $FILE -- obtém string do nome do módulo atual
print $LINE -- obtém número 2

Compilar

Gerando macros com macros

No YueScript, as funções macro permitem que você gere código em tempo de compilação. Aninhando funções macro, você pode criar padrões de geração mais complexos. Este recurso permite que você defina uma função macro que gera outra função macro, permitindo geração de código mais dinâmica.

macro Enum = (...) ->
  items = {...}
  itemSet = {item, true for item in *items}
  (item) ->
    error "got \"#{item}\", expecting one of #{table.concat items, ', '}" unless itemSet[item]
    "\"#{item}\""

macro BodyType = $Enum(
  Static
  Dynamic
  Kinematic
)

print "Valid enum type:", $BodyType Static
-- print "Compilation error with enum type:", $BodyType Unknown

Compilar

Gerando código em múltiplas linhas

Quando uma macro retorna código Yue em múltiplas linhas, não é recomendado usar uma string multilinha entre aspas. Prefira -> |.

Uma string entre aspas preserva o texto literal, enquanto uma string multilinha estilo YAML remove a indentação inicial comum. Isso normalmente deixa os blocos Yue gerados mais estáveis, especialmente quando o código gerado contém comentários ou blocos aninhados.

macro default_conf = (conf) -> "
  -- useful; only set once
#{conf}.identity = 'LOVE'
#{conf}.version = \"11.5\"
  "

love.conf = (t) ->
  $default_conf t

Compilar

macro default_conf = (conf) -> |
  -- useful; only set once
  #{conf}.identity = 'LOVE'
  #{conf}.version = "11.5"

love.conf = (t) ->
  $default_conf t

Compilar

Validação de argumentos

Você pode declarar os tipos de nós AST esperados na lista de argumentos e verificar se os argumentos da macro recebidos atendem às expectativas em tempo de compilação.

macro printNumAndStr = (num `Num, str `String) -> |
  print(
    #{num}
    #{str}
  )

$printNumAndStr 123, "hello"

Compilar

Se você precisar de verificação de argumentos mais flexível, pode usar a função macro embutida $is_ast para verificar manualmente no lugar apropriado.

macro printNumAndStr = (num, str) ->
  error "expected Num as first argument" unless $is_ast Num, num
  error "expected String as second argument" unless $is_ast String, str
  "print(#{num}, #{str})"

$printNumAndStr 123, "hello"

Compilar

Para mais detalhes sobre os nós AST disponíveis, consulte as definições em maiúsculas em yue_parser.cpp.

Instruções de anotação

As instruções de anotação aplicam uma macro à instrução logo em seguida.

Isso equivale a chamar a macro com o código-fonte da instrução seguinte anexado como último argumento.

macro ShowName = (code) -> |
  print "#{code\match '^[%w_]*'}"

$[ShowName]
myFunc = ->

return

Compilar

Quando a macro de anotação retorna uma tabela de configuração, o campo opcional before controla se o resultado gerado será emitido antes ou depois da instrução anotada.

macro Tag = (tag, code) ->
  tableName = code\match "^[%w_]+"
  return
    type: "text"
    before: tag == "before"
    code: "-- #{tag}:#{tableName}"

$[Tag before]
tableA = {}

$[Tag after]
tableB = {}

return

Compilar

Como a instrução seguinte é passada como um argumento extra para a macro, anotações também podem ser usadas para gerar código de registro a partir de declarações de classe. Você também pode usar as mesmas checagens de AST nos argumentos que macros normais oferecem.

macro Register = (registry, code`ClassDecl) ->
  className = code\match "^class%s+(%w+)"
  return |
    #{registry}["#{className}"] = #{className}

registry = {}

$[Register(registry)]
class Worker
  run: => "ok"

return

Compilar

Anotações também podem injetar código de empacotamento em volta de funções:

macro ValidateNumberArgs = (code) ->
  funcName = code\match "^(%w+)%s*="
  return |
    local __orig_#{funcName} = #{funcName}
    #{funcName} = (...) ->
      for i = 1, select "#", ...
        assert type(select i, ...) == "number", "expected number for arg \#{i}"
      __orig_#{funcName} ...

$[ValidateNumberArgs]
add = (a, b) -> a + b

Compilar

Uma anotação sempre precisa ser seguida por uma instrução, e ela não pode ser aplicada a uma instrução return. Se a instrução anotada aparecer no fim de um bloco e você precisar da forma AST bruta dessa instrução, adicione um return explícito em seguida para evitar que ela seja envolvida por uma expressão com retorno implícito.

Decoradores de linha

Por conveniência, o loop for e a instrução if podem ser aplicados a instruções únicas no final da linha:

print "hello world" if name == "Rob"

Compilar

E com loops básicos:

print "item: ", item for item in *items

Compilar

E com loops while:

game\update! while game\isRunning!

reader\parse_line! until reader\eof!

Compilar

Do

Quando usado como instrução, do funciona exatamente como no Lua.

do
  var = "hello"
  print var
print var -- nil aqui

Compilar

O do do YueScript também pode ser usado como expressão. Permitindo combinar múltiplas linhas em uma. O resultado da expressão do é a última instrução em seu corpo.

counter = do
  i = 0
  ->
    i += 1
    i

print counter!
print counter!

Compilar

tbl = {
  key: do
    print "assigning key!"
    1234
}

Compilar

Expressões do suportam usar break para interromper o fluxo de execução e retornar múltiplos valores antecipadamente.

status, value = do
  n = 12
  if n > 10
    break "large", n
  break "small", n

Compilar

Try

A sintaxe para tratamento de erros do Lua em uma forma comum.

try
  func 1, 2, 3
catch err
  print yue.traceback err

success, result = try
  func 1, 2, 3
catch err
  yue.traceback err

try func 1, 2, 3
catch err
  print yue.traceback err

success, result = try func 1, 2, 3

try
  print "trying"
  func 1, 2, 3

-- funcionando com padrão de atribuição em if
if success, result := try func 1, 2, 3
catch err
    print yue.traceback err
  print result

Compilar

Try?

try? é um uso simplificado para sintaxe de tratamento de erros que omite o status booleano da instrução try, e retornará o resultado do bloco try quando tiver sucesso, retornando nil em vez do objeto de erro caso contrário.

a, b, c = try? func!

-- com operador de coalescência de nil
a = (try? func!) ?? "default"

-- como argumento de função
f try? func!

-- com bloco catch
f try?
  print 123
  func!
catch e
  print e
  e

Compilar

A biblioteca YueScript

Acesse com local yue = require("yue") no Lua.

yue

Descrição:

A biblioteca da linguagem YueScript.

version

Tipo: Campo.

Descrição:

A versão do YueScript.

Assinatura:

version: string

dirsep

Tipo: Campo.

Descrição:

O separador de arquivos da plataforma atual.

Assinatura:

dirsep: string

yue_compiled

Tipo: Campo.

Descrição:

O cache de código de módulo compilado.

Assinatura:

yue_compiled: {string: string}

to_lua

Tipo: Função.

Descrição:

A função de compilação do YueScript. Compila o código YueScript para código Lua.

Assinatura:

to_lua: function(code: string, config?: Config):
    --[[codes]] string | nil,
    --[[error]] string | nil,
    --[[globals]] {{string, integer, integer}} | nil

Parâmetros:

Parâmetro	Tipo	Descrição
code	string	O código YueScript.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
string | nil	O código Lua compilado, ou nil se a compilação falhou.
string | nil	A mensagem de erro, ou nil se a compilação foi bem-sucedida.
{{string, integer, integer}} | nil	As variáveis globais que aparecem no código (com nome, linha e coluna), ou nil se a opção do compilador lint_global for false.

file_exist

Tipo: Função.

Descrição:

Função de verificação de existência do arquivo fonte. Pode ser sobrescrita para personalizar o comportamento.

Assinatura:

file_exist: function(filename: string): boolean

Parâmetros:

Parâmetro	Tipo	Descrição
filename	string	O nome do arquivo.

Retorna:

Tipo de Retorno	Descrição
boolean	Se o arquivo existe.

read_file

Tipo: Função.

Descrição:

Função de leitura do arquivo fonte. Pode ser sobrescrita para personalizar o comportamento.

Assinatura:

read_file: function(filename: string): string

Parâmetros:

Parâmetro	Tipo	Descrição
filename	string	O nome do arquivo.

Retorna:

Tipo de Retorno	Descrição
string	O conteúdo do arquivo.

insert_loader

Tipo: Função.

Descrição:

Insere o carregador YueScript nos carregadores de pacote (searchers).

Assinatura:

insert_loader: function(pos?: integer): boolean

Parâmetros:

Parâmetro	Tipo	Descrição
pos	integer	[Opcional] A posição para inserir o carregador. Padrão é 3.

Retorna:

Tipo de Retorno	Descrição
boolean	Se o carregador foi inserido com sucesso. Falhará se o carregador já estiver inserido.

remove_loader

Tipo: Função.

Descrição:

Remove o carregador YueScript dos carregadores de pacote (searchers).

Assinatura:

remove_loader: function(): boolean

Retorna:

Tipo de Retorno	Descrição
boolean	Se o carregador foi removido com sucesso. Falhará se o carregador não estiver inserido.

loadstring

Tipo: Função.

Descrição:

Carrega código YueScript de uma string em uma função.

Assinatura:

loadstring: function(input: string, chunkname: string, env: table, config?: Config):
    --[[loaded function]] nil | function(...: any): (any...),
    --[[error]] string | nil

Parâmetros:

Parâmetro	Tipo	Descrição
input	string	O código YueScript.
chunkname	string	O nome do chunk de código.
env	table	A tabela de ambiente.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
function | nil	A função carregada, ou nil se o carregamento falhou.
string | nil	A mensagem de erro, ou nil se o carregamento foi bem-sucedido.

loadstring

Tipo: Função.

Descrição:

Carrega código YueScript de uma string em uma função.

Assinatura:

loadstring: function(input: string, chunkname: string, config?: Config):
    --[[loaded function]] nil | function(...: any): (any...),
    --[[error]] string | nil

Parâmetros:

Parâmetro	Tipo	Descrição
input	string	O código YueScript.
chunkname	string	O nome do chunk de código.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
function | nil	A função carregada, ou nil se o carregamento falhou.
string | nil	A mensagem de erro, ou nil se o carregamento foi bem-sucedido.

loadstring

Tipo: Função.

Descrição:

Carrega código YueScript de uma string em uma função.

Assinatura:

loadstring: function(input: string, config?: Config):
    --[[loaded function]] nil | function(...: any): (any...),
    --[[error]] string | nil

Parâmetros:

Parâmetro	Tipo	Descrição
input	string	O código YueScript.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
function | nil	A função carregada, ou nil se o carregamento falhou.
string | nil	A mensagem de erro, ou nil se o carregamento foi bem-sucedido.

loadfile

Tipo: Função.

Descrição:

Carrega código YueScript de um arquivo em uma função.

Assinatura:

loadfile: function(filename: string, env: table, config?: Config):
    nil | function(...: any): (any...),
    string | nil

Parâmetros:

Parâmetro	Tipo	Descrição
filename	string	O nome do arquivo.
env	table	A tabela de ambiente.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
function | nil	A função carregada, ou nil se o carregamento falhou.
string | nil	A mensagem de erro, ou nil se o carregamento foi bem-sucedido.

loadfile

Tipo: Função.

Descrição:

Carrega código YueScript de um arquivo em uma função.

Assinatura:

loadfile: function(filename: string, config?: Config):
    nil | function(...: any): (any...),
    string | nil

Parâmetros:

Parâmetro	Tipo	Descrição
filename	string	O nome do arquivo.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
function | nil	A função carregada, ou nil se o carregamento falhou.
string | nil	A mensagem de erro, ou nil se o carregamento foi bem-sucedido.

dofile

Tipo: Função.

Descrição:

Carrega código YueScript de um arquivo em uma função e o executa.

Assinatura:

dofile: function(filename: string, env: table, config?: Config): any...

Parâmetros:

Parâmetro	Tipo	Descrição
filename	string	O nome do arquivo.
env	table	A tabela de ambiente.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
any…	Os valores de retorno da função carregada.

dofile

Tipo: Função.

Descrição:

Carrega código YueScript de um arquivo em uma função e o executa.

Assinatura:

dofile: function(filename: string, config?: Config): any...

Parâmetros:

Parâmetro	Tipo	Descrição
filename	string	O nome do arquivo.
config	Config	[Opcional] As opções do compilador.

Retorna:

Tipo de Retorno	Descrição
any…	Os valores de retorno da função carregada.

find_modulepath

Tipo: Função.

Descrição:

Resolve o nome do módulo YueScript para o caminho do arquivo.

Assinatura:

find_modulepath: function(name: string): string

Parâmetros:

Parâmetro	Tipo	Descrição
name	string	O nome do módulo.

Retorna:

Tipo de Retorno	Descrição
string	O caminho do arquivo.

pcall

Tipo: Função.

Descrição:

Chama uma função em modo protegido. Captura quaisquer erros e retorna um código de status e resultados ou objeto de erro. Reescreve o número da linha do erro para o número da linha original no código YueScript quando ocorrem erros.

Assinatura:

pcall: function(f: function, ...: any): boolean, any...

Parâmetros:

Parâmetro	Tipo	Descrição
f	function	A função a chamar.
…	any	Argumentos a passar para a função.

Retorna:

Tipo de Retorno	Descrição
boolean, …	Código de status e resultados da função ou objeto de erro.

require

Tipo: Função.

Descrição:

Carrega um módulo dado. Pode ser um módulo Lua ou um módulo YueScript. Reescreve o número da linha do erro para o número da linha original no código YueScript se o módulo for um módulo YueScript e o carregamento falhar.

Assinatura:

require: function(name: string): any...

Parâmetros:

Parâmetro	Tipo	Descrição
modname	string	O nome do módulo a carregar.

Retorna:

Tipo de Retorno	Descrição
any	O valor armazenado em package.loaded[modname] se o módulo já estiver carregado. Caso contrário, tenta encontrar um carregador e retorna o valor final de package.loaded[modname] e os dados do carregador como segundo resultado.

p

Tipo: Função.

Descrição:

Inspeciona as estruturas dos valores passados e imprime representações em string.

Assinatura:

p: function(...: any)

Parâmetros:

Parâmetro	Tipo	Descrição
…	any	Os valores a inspecionar.

options

Tipo: Campo.

Descrição:

As opções atuais do compilador.

Assinatura:

options: Config.Options

traceback

Tipo: Função.

Descrição:

A função traceback que reescreve os números das linhas do stack trace para os números das linhas originais no código YueScript.

Assinatura:

traceback: function(message: string): string

Parâmetros:

Parâmetro	Tipo	Descrição
message	string	A mensagem de traceback.

Retorna:

Tipo de Retorno	Descrição
string	A mensagem de traceback reescrita.

is_ast

Tipo: Função.

Descrição:

Verifica se o código corresponde ao AST especificado.

Assinatura:

is_ast: function(astName: string, code: string): boolean

Parâmetros:

Parâmetro	Tipo	Descrição
astName	string	O nome do AST.
code	string	O código.

Retorna:

Tipo de Retorno	Descrição
boolean	Se o código corresponde ao AST.

AST

Tipo: Campo.

Descrição:

A definição do tipo AST com nome, linha, coluna e subnós.

Assinatura:

type AST = {string, integer, integer, any}

to_ast

Tipo: Função.

Descrição:

Converte o código para o AST.

Assinatura:

to_ast: function(code: string, flattenLevel?: number, astName?: string, reserveComment?: boolean):
    --[[AST]] AST | nil,
    --[[error]] nil | string

Parâmetros:

Parâmetro	Tipo	Descrição
code	string	O código.
flattenLevel	integer	[Opcional] O nível de achatamento. Nível mais alto significa mais achatamento. Padrão é 0. Máximo é 2.
astName	string	[Opcional] O nome do AST. Padrão é “File”.
reserveComment	boolean	[Opcional] Se deve preservar os comentários originais. Padrão é false.

Retorna:

Tipo de Retorno	Descrição
AST | nil	O AST, ou nil se a conversão falhou.
string | nil	A mensagem de erro, ou nil se a conversão foi bem-sucedida.

format

Tipo: Função.

Descrição:

Formata o código YueScript.

Assinatura:

format: function(code: string, tabSize?: number, reserveComment?: boolean): string

Parâmetros:

Parâmetro	Tipo	Descrição
code	string	O código.
tabSize	integer	[Opcional] O tamanho da tabulação. Padrão é 4.
reserveComment	boolean	[Opcional] Se deve preservar os comentários originais. Padrão é true.

Retorna:

Tipo de Retorno	Descrição
string	O código formatado.

__call

Tipo: Metamétodo.

Descrição:

Requer o módulo YueScript. Reescreve o número da linha do erro para o número da linha original no código YueScript quando o carregamento falha.

Assinatura:

metamethod __call: function(self: yue, module: string): any...

Parâmetros:

Parâmetro	Tipo	Descrição
module	string	O nome do módulo.

Retorna:

Tipo de Retorno	Descrição
any	O valor do módulo.

Config

Descrição:

As opções de compilação do compilador.

lint_global

Tipo: Campo.

Descrição:

Se o compilador deve coletar as variáveis globais que aparecem no código.

Assinatura:

lint_global: boolean

implicit_return_root

Tipo: Campo.

Descrição:

Se o compilador deve fazer retorno implícito para o bloco de código raiz.

Assinatura:

implicit_return_root: boolean

reserve_line_number

Tipo: Campo.

Descrição:

Se o compilador deve preservar o número da linha original no código compilado.

Assinatura:

reserve_line_number: boolean

reserve_comment

Tipo: Campo.

Descrição:

Se o compilador deve preservar os comentários originais no código compilado.

Assinatura:

reserve_comment: boolean

space_over_tab

Tipo: Campo.

Descrição:

Se o compilador deve usar o caractere de espaço em vez do caractere de tabulação no código compilado.

Assinatura:

space_over_tab: boolean

same_module

Tipo: Campo.

Descrição:

Se o compilador deve tratar o código a ser compilado como o mesmo módulo que está sendo compilado atualmente. Apenas para uso interno.

Assinatura:

same_module: boolean

line_offset

Tipo: Campo.

Descrição:

Se a mensagem de erro do compilador deve incluir o deslocamento do número da linha. Apenas para uso interno.

Assinatura:

line_offset: integer

yue.Config.LuaTarget

Tipo: Enumeração.

Descrição:

A enumeração da versão alvo do Lua.

Assinatura:

enum LuaTarget
  "5.1"
  "5.2"
  "5.3"
  "5.4"
  "5.5"
end

options

Tipo: Campo.

Descrição:

As opções extras a serem passadas para a função de compilação.

Assinatura:

options: Options

Options

Descrição:

A definição das opções extras do compilador.

target

Tipo: Campo.

Descrição:

A versão alvo do Lua para a compilação.

Assinatura:

target: LuaTarget

path

Tipo: Campo.

Descrição:

O caminho de busca de módulo extra.

Assinatura:

path: string

dump_locals

Tipo: Campo.

Descrição:

Se deve incluir as variáveis locais na mensagem de erro do traceback. Padrão é false.

Assinatura:

dump_locals: boolean

simplified

Tipo: Campo.

Descrição:

Se deve simplificar a mensagem de erro. Padrão é true.

Assinatura:

simplified: boolean

Mascote, Xiaoyu

Sobre

Xiaoyu (小玉, “pequeno jade”) é uma coelha cibernética e a mascote oficial do projeto YueScript. Ela fica empoleirada em uma lua crescente, escrevendo YueScript em seu laptop.

Seu titulo completo é Xiaoyu, a Coelha Cibernética (机兔小玉). Ela reflete o que o YueScript busca: limpo, expressivo e divertido.

Tyson Tan projetou e ilustrou Xiaoyu para o projeto de forma gratuita. Somos gratos pela sua contribuição.

Imagens

Clique em qualquer imagem para abri-la em tamanho real.

Arte completa

Baixar PNG em tamanho real

Fundo transparente

Baixar PNG transparente

Arquivo .kra compactado

Baixar arquivo .kra compactado

Licença

Xiaoyu é duplamente licenciada sob a Licença MIT e a Creative Commons CC-BY-SA 4.0.

Licença: MIT

Copyright (c) 2017-2026 Li Jin <dragon-fly@qq.com>

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o “Software”), para negociar o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que pessoas a quem o Software seja fornecido o façam, sujeito às seguintes condições:

O aviso de direitos autorais acima e este aviso de permissão devem ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO “NO ESTADO EM QUE SE ENCONTRA”, SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM DETERMINADO FIM E NÃO VIOLAÇÃO. EM NENHUMA HIPÓTESE OS AUTORES OU DETENTORES DOS DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUAISQUER REIVINDICAÇÕES, DANOS OU OUTRAS RESPONSABILIDADES, SEJA EM UMA AÇÃO DE CONTRATO, ATO ILÍCITO OU OUTRA, DECORRENTES DE, FORA DE OU RELACIONADAS COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.

Compilador online do YueScript

Experimente YueScript no navegador com WASM.