Home

SmartGameFormat.jl Documentation

SmartGameFormat.jl is a Julia package to read/write from/to SGF files. More specifically does this package aim to implement the specification of the SGF FF[4] standard.

Description from the official website:

SGF is the abbreviation of 'Smart Game Format'. The file format is designed to store game records of board games for two players. It's a text only, tree based format. Therefore games stored in this format can easily be emailed, posted or processed with text-based tools. The main purposes of SGF are to store records of played games and to provide features for storing annotated and analyzed games (e.g. board markup, variations).

Exported Types

SmartGameFormat.SGFNode — Type.
SGFNode(properties::Pair{Symbol,Any}...)

Create an SGF node with the given properties. The parameter properties is optional, which means that its possible to create empty nodes.

Additional properties can be added at any time using the function setindex! or push!. Note how the property values are stored in a Vector{Any}. This is on purpose in order to support multi-value properties.

julia> using SmartGameFormat

julia> node = SGFNode()
SmartGameFormat.SGFNode with 0 properties

julia> node[:KM] = 6.5; # set komi property

julia> node
SmartGameFormat.SGFNode with 1 property:
  :KM => Any[6.5]

While setindex! will always overwrite existing values, the function push! will instead try to append the given value to an existing property.

julia> push!(node, :AB => "aa")
SmartGameFormat.SGFNode with 2 properties:
  :AB => Any["aa"]
  :KM => Any[6.5]

julia> push!(node, :AB => "bb")
SmartGameFormat.SGFNode with 2 properties:
  :AB => Any["aa", "bb"]
  :KM => Any[6.5]
source
SmartGameFormat.SGFGameTree — Type.
SGFGameTree([sequence::Vector{SGFNode}], [variations::Vector{SGFGameTree}])

Create a game tree with the given sequence and variations. Both parameters are optional, which means that its possible to create empty game trees.

To edit a SGFGameTree simply manipulate the two member variables directly. Note that SGFGameTree is a subtype of AbstractVector{SGFNode}, where getindex and setindex! correspond to the appropriate node in the main game path. This means that if there are any variations, then the first variation must denote the continuation of the main game path.

julia> using SmartGameFormat

julia> t = SGFGameTree()
0-node SmartGameFormat.SGFGameTree with 0 variation(s)

julia> push!(t.sequence, SGFNode(:KM => 6.5)); t
1-node SmartGameFormat.SGFGameTree with 0 variation(s):
 KM[6.5]

julia> t.variations = [SGFGameTree(SGFNode(:C=>"first")), SGFGameTree(SGFNode(:C=>"second"))]; t
2-node SmartGameFormat.SGFGameTree with 2 variation(s):
 KM[6.5]
 C[…]

julia> t[1]
SmartGameFormat.SGFNode with 1 property:
  :KM => Any[6.5]

julia> t[2]
SmartGameFormat.SGFNode with 1 property:
  :C => Any["first"]
source

Public Functions

SmartGameFormat.load_sgf — Function.
load_sgf(path::String) -> Vector{SGFGameTree}

Read the content from the file at path, and call parse_sgf to convert it to a collection of SGFGameTree (i.e. a Vector{SGFGameTree}).

julia> using SmartGameFormat

julia> path = joinpath(Pkg.dir("SmartGameFormat"), "examples", "sample.sgf");

julia> col = load_sgf(path)
1-element Array{SmartGameFormat.SGFGameTree,1}:
 SmartGameFormat.SGFNode[FF[4] GM[1] SZ[19], B[aa], W[bb], B[cc]]

julia> col[1]
4-node SmartGameFormat.SGFGameTree with 2 variation(s):
 FF[4] GM[1] SZ[19]
 B[aa]
 W[bb]
 B[cc]
source
SmartGameFormat.save_sgf — Function.
save_sgf(path::String, sgf)

Write the given sgf object (e.g. SGFNode, or SGFGameTree) into the given file at path. Note that it is a current limitation that the character encoding is hardcoded to UTF8 (no matter what any property specifies).

julia> using SmartGameFormat

julia> save_sgf("/tmp/example.sgf", SGFGameTree(SGFNode(:KM => 6.5)))

julia> readstring("/tmp/example.sgf") # take a look at file content
"(; KM[6.5])"
source
SmartGameFormat.parse_sgf — Function.
parse_sgf(io::IO) -> Vector{SGFGameTree}
parse_sgf(str::String) -> Vector{SGFGameTree}

Read the content from io (or str), and attempt to parse it as an SGF collection. If successful, the collection is returned as a vector of SGFGameTree. In most cases this collection will just have a single tree.

julia> using SmartGameFormat

julia> col = parse_sgf("(; FF[4] KM[6.5]; B[aa])")
1-element Array{SmartGameFormat.SGFGameTree,1}:
 SmartGameFormat.SGFNode[KM[6.5] FF[4], B[aa]]

julia> tree = col[1]
2-node SmartGameFormat.SGFGameTree with 0 variation(s):
 KM[6.5] FF[4]
 B[aa]

julia> node = tree[1]
SmartGameFormat.SGFNode with 2 properties:
  :KM => Any[6.5]
  :FF => Any[4]

Depending on the content an exception may be thrown to signal that it is not a legal SGF specification.

  • Base.EOFError: Premature end-of-file encountered during tokenisation.

  • Lexer.LexicalError: illegal characters used outside property values. For example lower case letters for identifier.

  • Parser.ParseError: content is not a valid SGF specification (while considering the given the FF version).

Internally, the function simply calls Parser.parse. Take a look at the corresponding documentation for more details.

source
SmartGameFormat.print_sgf — Function.
print_sgf([io], sgf; [color = true])

Write the given parsed sfg to io (defaults to STDOUT). If the keyword parameter color = true, then an ANSI based syntax highlighting will be used.

source

Index